不使用 Blazor，在浏览器中运行 .NET：从 WebAssembly 模板到 JavaScript 互操作

09/23/2026 05:54:12 | China Standard Time

介绍如何直接基于 .NET WebAssembly 基础设施在浏览器中运行 C#，不依赖 Blazor 组件，并分析 JSExport、JSImport、发布优化、客户端指纹和体积控制。

# 不使用 Blazor，在浏览器中运行 .NET：从 WebAssembly 模板到 JavaScript 互操作
提到“在浏览器里运行 .NET”，大多数人首先想到的是 Blazor。但 Blazor 只是建立在 .NET WebAssembly 能力之上的一套组件化 Web 框架。如果应用不需要 Blazor 的组件模型、渲染模式和完整 Web 框架，也可以直接使用 .NET 的 WebAssembly 基础设施，让 C# 代码运行在浏览器中，并通过 JavaScript 与 DOM 交互。
这种方式更底层，但也更直接：HTML 负责页面结构，JavaScript 负责启动 .NET WebAssembly，C# 负责业务逻辑，`[JSImport]` 和 `[JSExport]` 负责两种语言之间的函数调用。
## .NET 与 WebAssembly 的几种组合方式
.NET 与 WebAssembly 并不只有 Blazor 这一种组合：
- 在浏览器中运行 .NET WebAssembly，但不使用 Blazor；
- 在 Node.js 进程中运行 .NET WebAssembly；
- 构建 WASI 兼容的 .NET 组件，并与其他语言编写的 WASI 组件组合；
- 将 Blazor 组件集成到 React、Vue 等 JavaScript 框架中。
本文关注第一种方式：让 .NET 程序直接运行在浏览器中，不引入 Blazor 组件模型。
## 安装 WebAssembly 浏览器模板
WebAssembly 相关模板并不总是随默认 .NET SDK 一起安装。可以根据目标 .NET 版本安装对应模板。以 .NET 10 为例：
```bash
dotnet new install Microsoft.NET.Runtime.WebAssembly.Templates.net10
```
模板包会提供几种项目模板：
- `wasmbrowser`：浏览器中的 WebAssembly 应用；
- `wasmconsole`：WebAssembly 控制台应用；
- `wasiconsole`：WASI 控制台应用。
也可以安装实验性 workload：
```bash
dotnet workload install wasm-experimental
```
如果需要 Native AOT，还需要安装 `wasm-tools` workload。AOT 通常能改善运行性能，但会增加构建复杂度，并可能增加初始下载体积，因此要根据应用规模和启动速度要求进行权衡。
## 创建第一个浏览器应用
创建一个浏览器项目：
```bash
dotnet new wasmbrowser -o WasmApp
cd WasmApp
dotnet run
```
开发服务器会提供一个本地地址。打开后，可以看到模板自带的秒表示例：页面加载后计时器开始运行，可以暂停、继续和重置。
这个示例的重要价值不在于秒表本身，而在于它展示了一个最小闭环：
1. HTML 提供按钮和显示时间的元素；
2. JavaScript 启动 .NET WebAssembly；
3. C# 执行计时逻辑；
4. C# 调用 JavaScript 更新 DOM；
5. JavaScript 调用 C# 暴露出来的方法响应按钮事件。
## HTML 只负责页面结构
这类应用的 HTML 可以非常简单：
```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="preload" id="webassembly" />
  <script type="importmap"></script>
  <script type="module" src="main#[.{fingerprint}].js"></script>
</head>
<body>
  <h1>Stopwatch</h1>
  <p>Time elapsed in .NET is <span id="time"><i>loading...</i></span></p>
  <p>
    <button id="pause">Pause</button>
    <button id="reset">Reset</button>
  </p>
</body>
</html>
```
这里没有 Blazor 组件，也没有 Razor 页面。HTML 只负责声明 DOM 元素，后续交互由 JavaScript 和 C# 协作完成。
## JavaScript 如何启动 .NET
入口脚本首先导入 .NET 的浏览器运行时：
```javascript
import { dotnet } from './_framework/dotnet.js';
const {
    setModuleImports,
    getAssemblyExports,
    getConfig,
    runMain
} = await dotnet
    .withApplicationArguments("start")
    .create();
```
`create()` 会初始化 .NET WebAssembly 运行环境。之后可以通过 `getConfig()` 获取应用配置，通过 `getAssemblyExports()` 获取 C# 程序中使用 `[JSExport]` 暴露的方法。
## 使用 [JSImport] 从 C# 调用 JavaScript
假设 JavaScript 提供一个更新 DOM 的函数：
```javascript
setModuleImports('main.js', {
    dom: {
        setInnerText: (selector, value) => {
            document.querySelector(selector).innerText = value;
        }
    }
});
```
C# 侧可以使用 `[JSImport]` 声明对应的 JavaScript 函数：
```csharp
using System.Runtime.InteropServices.JavaScript;
public partial class StopwatchSample
{
    [JSImport("dom.setInnerText", "main.js")]
    internal static partial void SetInnerText(string selector, string value);
}
```
调用 `SetInnerText("#time", value)` 时，.NET 代码就会进入 JavaScript，并更新页面元素。`JSImport` 并不是反射式地搜索 JavaScript 函数，而是由源代码生成器生成互操作代码。
## 使用 [JSExport] 让 JavaScript 调用 C#
反方向的调用可以使用 `[JSExport]`：
```csharp
[JSExport]
public static void Reset()
{
    _stopwatch.Reset();
}
[JSExport]
public static bool Toggle()
{
    if (_stopwatch.IsRunning)
        _stopwatch.Stop();
    else
        _stopwatch.Start();
    return _stopwatch.IsRunning;
}
```
JavaScript 启动运行时并获得导出方法：
```javascript
const config = getConfig();
const exports = await getAssemblyExports(config.mainAssemblyName);
document.getElementById('reset').addEventListener('click', event => {
    exports.StopwatchSample.Reset();
    event.preventDefault();
});
document.getElementById('pause').addEventListener('click', event => {
    const running = exports.StopwatchSample.Toggle();
    event.target.innerText = running ? 'Pause' : 'Start';
    event.preventDefault();
});
```
最后调用 `runMain()` 启动 C# 程序：
```javascript
await runMain();
```
从架构上看，`[JSImport]` 和 `[JSExport]` 是边界声明，源生成器会负责参数转换、调用约定和结果返回。实际项目中应尽量减少跨边界调用次数，把一批相关工作集中在一侧完成，再传递必要的数据。
## 发布应用
开发阶段可以直接使用 `dotnet run`。生产发布通常使用：
```bash
dotnet publish -c Release
```
发布过程会编译应用、裁剪不需要的框架引用，并生成 gzip 和 Brotli 压缩文件。浏览器首次打开时需要下载 .NET WebAssembly 运行时和应用程序集，因此发布体积和缓存策略会直接影响冷启动体验。
## .NET 10 的客户端资源指纹
静态资源指纹可以让浏览器安全地缓存 JavaScript 和 WebAssembly 文件：文件内容变化时，文件名也变化；文件内容不变时，浏览器可以继续复用缓存。
模板中可以使用：
```html
<link rel="preload" id="webassembly" />
<script type="importmap"></script>
<script type="module" src="main#[.{fingerprint}].js"></script>
```
项目文件中配置指纹模式：
```xml
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>
<ItemGroup>
  <StaticWebAssetFingerprintPattern
      Include="JS"
      Pattern="*.js"
      Expression="#[.{fingerprint}]!" />
</ItemGroup>
```
这里的 `Expression="#[.{fingerprint}]!"` 很重要。某些模板版本只配置了 `Pattern="*.js"`，发布后 `main.js` 仍然没有指纹。此时应显式指定表达式，确保最终生成的脚本名称带有内容指纹。
指纹的价值不仅是缓存命中。它还能避免部署新版本后，用户继续使用旧的 JavaScript 与新版本 WebAssembly 运行时不匹配的问题。
## 控制发布体积
一个最小的 .NET WebAssembly 应用仍然需要携带运行时，因此不能简单地与普通 JavaScript 小页面比较。通常可以从三个方向优化：
1. Release 发布和裁剪；
2. gzip 或 Brotli 压缩；
3. 减少不需要的框架功能和全球化数据。
如果应用不需要完整的全球化能力，可以评估项目文件中的：
```xml
<InvariantGlobalization>true</InvariantGlobalization>
```
Invariant globalization 会移除部分 ICU 全球化数据，从而减少发布体积。但它会限制区域、文化和格式化能力。涉及多语言、复杂日期格式、货币或本地化排序时，不应盲目启用。
## 这种方式适合什么场景
不使用 Blazor 直接运行 .NET WebAssembly，适合以下情况：
- 已经有成熟的 JavaScript 页面，只需要复用部分 C# 业务逻辑；
- 希望使用 C# 算法、协议处理或计算模块，但不想引入完整 Blazor UI；
- 需要在浏览器中运行共享的 .NET 库；
- 需要对 HTML、JavaScript 和 .NET 之间的边界保持明确控制；
- 正在构建一个较底层的 WebAssembly 能力验证项目。
它不一定适合所有 Web 应用。如果目标是完整的组件化页面、表单、路由、状态管理和服务器交互，Blazor 通常能提供更高层的开发效率。
## 工程上的取舍
这种方式的优点是层次少、边界清晰，不需要为了运行一小段 C# 逻辑而采用完整 UI 框架。缺点也同样明显：DOM 更新、事件绑定、状态同步、错误处理和生命周期都需要自己设计。
此外，JavaScript 与 .NET 之间的调用不是零成本操作。频繁地逐项传递对象、字符串或数组，会增加 marshalling 开销。更合理的做法是设计粗粒度 API，例如一次把输入数据传给 C#，完成计算后一次性返回结果。
## 总结
.NET WebAssembly 不等于 Blazor。Blazor 是构建在 WebAssembly 能力之上的完整 Web 框架，而 `wasmbrowser` 模板提供了更底层的选择：让 C# 程序直接运行在浏览器中，由 JavaScript 负责启动和 DOM 集成。
核心机制可以概括为：
- HTML 提供页面结构；
- JavaScript 导入并启动 .NET WebAssembly；
- `[JSImport]` 让 C# 调用 JavaScript；
- `[JSExport]` 让 JavaScript 调用 C#；
- Release 发布负责裁剪和压缩；
- 客户端资源指纹负责缓存失效；
- `InvariantGlobalization` 可以在适用时进一步缩小体积。
如果不需要 Blazor 的组件模型，但又希望在浏览器中复用 .NET 代码，这条路径值得评估。不过它更接近“自己组装运行时和互操作层”，应该把它当作底层基础设施，而不是另一个自动生成的前端框架。
参考：
- [Running .NET in the browser without Blazor](https://andrewlock.net/running-dotnet-in-the-browser-without-blazor/)
- [.NET WebAssembly JavaScript interop](https://learn.microsoft.com/aspnet/core/client-side/dotnet-interop)
- [.NET Aspire 与 WebAssembly 并无直接依赖，本文仅讨论 .NET WASM 浏览器模板]