Jazor 1.0.0-preview.4

Jazor

定位：将受支持 C# 语义编译为确定性 ECMAScript 模块的核心 NuGet 包。

Jazor 包含框架无关的 runtime contract、analyzer、source generator、Emit 工具、MSBuild 集成与 ASP.NET Core 集成。它可以用于编写普通 ECMAScript 类库；Vue authoring、Razor-to-Vue、Vue bindings 与 Vue runtime 由独立的 Jazor.Vue opt-in 包提供。

资源契约：仓库自有 ECMAScript runtime 由 ECMAScript manifest 与 src/ECMAScript/clr/** 提供；其他运行时来自 manifest 声明的 npm/JSR package 或明确的 embedded carrier。Jazor 编译模块由程序集内的 Jazor.Generated.ModuleCatalog 携带，最终 宿主在 MSBuild 阶段由 Emit 生成标准 jazor/package.json 并物化项目。

类库的 JavaScript 来源由 package metadata 明确区分：ECMAScript 使用仓库内的 src/ECMAScript/clr/** embedded carrier，外部绑定使用 npm/JSR package，少数需要随包交付 的模块使用显式 embedded carrier。RazorVue 是纯 Jazor 类库的 authoring 场景，不是第三种 来源。ModuleCatalog（ECMAScriptCode）是开发者编写的 C#/RazorVue 模块的程序集内生成 载体；它是纯 Jazor 的正式生成格式，不是遗留兼容载体。

安装

ASP.NET Core 接入说明：静态资源、SPA 与 SSR；开发刷新与 HMR。两套程序集随本包交付 XML 文档，IDE 可直接查看参数、默认值与使用约束。

<ItemGroup>
  <PackageReference Include="Jazor" Version="1.0.0-preview.3" />
</ItemGroup>

纯 Jazor 类库（开发者编写 C# 并声明 [ECMAScriptModule]）直接引用 Jazor。类库保留默认 JazorMode=none，自身生成模块写入 DLL 内的 ModuleCatalog；最终可执行或 Web 宿主负责 收集程序集 catalog 与传递的资源 manifest 并输出产物。编写 RazorVue 组件的项目属于纯 Jazor 类库，必须直接引用 Jazor 和 Jazor.Vue；只消费上游类库的项目不会因普通引用获得工具资格。

定义 module 的类库应隔离这项工具引用：

<PackageReference Include="Jazor" Version="1.0.0-preview.3" PrivateAssets="all" />

最终 Exe/WinExe 宿主需要 Emit 时直接引用 Jazor，不设置 PrivateAssets。包内 build/Jazor.props 和 build/Jazor.targets 只对直接引用激活 compiler/analyzer/Emit； buildTransitive/Jazor.Resources.targets 只传递 ECMAScript resource manifest locator。

多项目场景遵循“谁使用，谁直接引用”：只消费上游程序集的中间类库不因资源传递而启用 Jazor 工具链；最终宿主必须自行直接引用 Jazor 并配置 Emit。完整的工具资产隔离和资源传播规则见 类库产物与引用契约。

宿主输出

<PropertyGroup>
  <JazorMode>debug</JazorMode>
  <JazorDir>$(MSBuildProjectDirectory)\jazor\</JazorDir>
</PropertyGroup>

JazorDir 是最终输出目录。Jazor.targets 在最终 Exe/WinExe 的 Build 后调用 Jazor.Emit，Emit 在此生成标准 JS 项目。增量状态写入 obj/jazor-manifest.json，不参与运行。 JazorSSR=true 会在同一依赖图下生成 SSR 与 hydration 入口。开发服务和 HMR 由标准前端工具 负责，ASP.NET Core 代理 HTTP/WebSocket。输出目录不是类库 carrier，也不会成为下一次资源发现的输入。

可选生态包

Vue Router、Pinia、UI 组件库与 CSS-in-JS 均需按使用场景显式引用对应 ECMAScript.* 包：

<ItemGroup>
  <PackageReference Include="ECMAScript.VueRoute" Version="1.0.0-preview.3" />
  <PackageReference Include="ECMAScript.Pinia" Version="1.0.0-preview.3" />
  <PackageReference Include="ECMAScript.Vuetify" Version="1.0.0-preview.3" />
  <PackageReference Include="ECMAScript.TDesign" Version="1.0.0-preview.3" />
  <PackageReference Include="ECMAScript.Style" Version="1.0.0-preview.3" />
</ItemGroup>

ECMAScript.Vue 随 Jazor.Vue 提供；ECMAScript.Pinia.Testing 是叠加在 ECMAScript.Pinia 之上的测试期 opt-in 包。所有 Jazor、Jazor.Vue 与 Vue 生态包应保持相同版本。

Blazor framework CLR mapping 由 Jazor.CLR.Generator 生成并由 Jazor.CLR 唯一持有；其 runtime JavaScript 由 ECMAScript 的 manifest 与 src/ECMAScript/clr/** embedded carrier 提供。 Jazor 不因此引用 ASP.NET Core framework。

SSR

在 ASP.NET Core Web 项目中配置 release 与 SSR：

<PropertyGroup>
  <JazorMode>release</JazorMode>
  <JazorSSR>true</JazorSSR>
</PropertyGroup>

builder.Services.AddJazorSsr();

var app = builder.Build();
app.UseJazorHost();
app.UseJazorSsr("components/app.mjs", new { Title = "Jazor" });

ASP.NET Core 持有请求管线与响应文档，DenoHost 执行标准项目中的 Vue 服务器模块，Vite 是可替换的默认浏览器工具。依赖恢复到项目的 node_modules，无需全局 Deno 或 CDN。

Razor-to-Vue

编写 RazorVue 组件的 Razor SDK 项目必须直接引用两个包：

<ItemGroup>
  <PackageReference Include="Jazor" Version="1.0.0-preview.3" />
  <PackageReference Include="Jazor.Vue" Version="1.0.0-preview.3" PrivateAssets="all" />
</ItemGroup>

该集成直接消费官方 Razor Source Generator 完成后的最终 Compilation，不需要 EnableRazorHostOutputs、Razor IR、RazorCodeDocument 或二次解析生成 C#。

相关文档

• 安装与配置
• 快速开始
• 产物管线
• Razor-to-Vue