深入 Blazor 全局交互式 Auto 模式基于 dotnet-blazor 技能的脚手架、项目结构与 AGENTS.md 落地指南【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills本文以开源仓库 skills17 中 dotnet-blazor 插件的 create-blazor-project 技能及其 auto-global 渲染配置模板 为核心系统讲解 Blazor Web App 中全局交互式 Auto 模式Interactive Auto, Global的完整落地路径从场景选型、脚手架命令、双项目结构、Program.cs与App.razor接线到交互组件放置规则、数据访问模式、服务注册纪律与 AGENTS.md 模板落地。读完本文你将能独立创建并维护一个首访走 Server、后续走 WebAssembly的全局交互 Blazor 应用并掌握其最容易踩坑的边界约束。Auto 模式与全局作用域先理解这套渲染模型AutoInteractive Auto是 Blazor 渲染模式中复杂度最高的一档同一份交互组件代码首次访问在服务器上以 SignalR 连接方式运行之后访问则切换到浏览器内的 WebAssembly 运行。其背后的执行流程在 auto-global.md 中被概括为用户第一次访问时组件通过 Interactive ServerSignalR渲染首屏加载快、无需下载 .NET 运行时后续访问时缓存的 WebAssembly 运行时接管交互完全在浏览器内执行不再产生服务器往返延迟。而全局Global则定义了交互的作用域所有页面默认都是交互式的无需在单个组件上逐个添加rendermode。对应的脚手架命令为dotnet new blazor -o {AppName} -int Auto -ai其中-int Auto指定交互模式为 Auto-ai--all-interactive指定全局作用域。整个 auto-global 模板对应的模式配置如下SettingValueInteractivity ModeAutoInteractivity ScopeGlobal何时该选 Auto 全局来自技能决策表的判断依据create-blazor-project/SKILL.md 将 Blazor 渲染模式描述为一条渐进刻度Static SSR → SSR Enhanced Nav → Interactive Server → Interactive WebAssembly并明确给出选型原则从满足需求的最简模式起步只有在出现具体理由时才向上迁移。针对 Auto 模式技能决策表给出的选择理由是需要首访加载快Server 之后低延迟WebAssembly二者兼得。SKILL.md 同时给出约束只有在 Server 和 WebAssembly 单独使用都各有不足、且你能明确说出理由时才选择 Auto所有交互组件必须放在.Client项目中与 WebAssembly 相同交互组件不能直接访问服务器资源无 EFDbContext、无文件系统、无服务器专用服务所有数据访问必须走 HTTP API服务器与客户端两个Program.cs必须注册匹配的服务代码不得假设自身执行环境——无HttpContext访问无未经RendererInfo防护的浏览器专用 API两种模式都要测试——开发期在 Server 上正常的组件可能在生产环境的第二次访问WebAssembly时出问题。该选型逻辑在 create-blazor-project 评测配置 的 Global logistics tracking for worldwide users 场景中得到验证面向全球用户、往返延迟明显、要求首访加载快、之后无需服务器往返的应用评测的评分标准明确要求选择-int Auto-ai且必须生成含.Client项目的双项目结构、在 Server 的Program.cs中同时注册 Server 与 WebAssembly 两套交互组件服务、所有数据通过 HTTP API 访问、两端Program.cs注册匹配服务。脚手架产物双项目结构的职责边界dotnet new blazor -int Auto -ai生成的是双项目结构auto-global 模板将其职责划分如下{AppName}服务器项目托管 Blazor 应用、提供静态文件与 API 端点{AppName}.ClientWebAssembly 项目承载全部交互式 UI 组件代码先在服务器运行再在浏览器运行。SKILL.md 对双项目结构有更完整的目录视图{AppName}服务器项目含Components/、Program.cs{AppName}.Client含Pages/、Program.cs、_Imports.razor并给出硬性规则使用InteractiveWebAssembly或InteractiveAuto的组件必须位于.Client项目中它们可以引用共享代码但绝不能引用服务器专用类型如 EFDbContext、服务器端服务。Program.cs 接线Auto 模式两端各注册什么Auto 模式是唯一需要同时启用 Server 与 WebAssembly 两套交互组件的模式。SKILL.md 给出了服务器端标准接线// Server Program.cs builder.Services.AddRazorComponents() .AddInteractiveServerComponents() .AddInteractiveWebAssemblyComponents(); // ... app.MapRazorComponentsApp() .AddInteractiveServerRenderMode() .AddInteractiveWebAssemblyRenderMode() .AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly);客户端Program.cs则注册AddAuthorizationCore()以及HttpClient等客户端侧服务// Client Program.cs builder.Services.AddAuthorizationCore(); // Register HttpClient, other client-side services注意AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly)这一行——它告诉服务器端的组件发现机制去扫描.Client程序集中的可路由组件与交互组件是双项目接线中不可缺少的一环。全局与每页的分水岭App.razor 一处之差SKILL.md 明确点出全局与每页per-page交互的唯一区别就在App.razor。每页模式默认Routes /与HeadOutlet /上不写rendermode由单个页面或组件自行选择是否加入交互全局模式在根组件上统一声明交互模式例如!DOCTYPE html html head HeadOutlet rendermodeInteractiveServer / /head body Routes rendermodeInteractiveServer / script src_framework/blazor.web.js/script /body /html将InteractiveServer替换为InteractiveAuto即为 Auto 全局配置。因此 auto-global 模板的 Donts 中特别强调不要在页面级再添加rendermode InteractiveAuto——全局交互性已在App.razor中配置完毕重复添加不仅冗余还容易造成配置漂移。添加新组件的硬性规则auto-global 模板为往这个项目里加东西定义了三条必须遵守的纪律交互组件必须放入.Client项目而不是服务器项目新页面放入{AppName}.Client/Pages/所有页面已是交互式全局模式无需在单个组件上添加rendermode。唯一的例外是服务器专用静态组件例如错误页应放在服务器项目的Components/文件夹中。这条规则的本质是只有放在.Client中的组件才能在服务器预渲染完成后被 WebAssembly 运行时无缝接管放错位置的交互组件预渲染时正常WebAssembly 接管后失败详见后文 Donts。数据访问模式交互组件安全读写数据的六步法由于交互组件运行在浏览器中Auto 模式下最终切到 WebAssembly它们不能直接访问数据库。auto-global 模板给出了标准六步模式在.Client项目中定义接口例如IDataService在.Client项目中用HttpClient调用服务器 API 来实现该接口在服务器项目中用直接数据访问EF CoreDbContext等实现同一接口在客户端Program.cs注册客户端实现、在服务器Program.cs注册服务器实现通过最小 API 端点例如app.MapGet(...)暴露服务器数据供客户端实现调用若页面需要授权需对Blazor 页面attribute [Authorize]与最小 API 端点.RequireAuthorization()应用相同的授权策略。这套模式的价值在于接口定义让两端实现可替换客户端拿到的永远是 HTTP 返回的数据契约服务器端的数据源数据库、文件、外部系统对客户端完全透明同时授权策略双端对齐避免页面受保护、接口裸奔的安全漏洞。服务注册纪律两端 DI 容器必须镜像与数据访问模式配套服务注册也有明确规则交互组件用到的任何 DI 服务服务器与客户端两个Program.cs都必须注册匹配的实现——因为同一个组件可能在服务器首次访问和浏览器后续访问两个环境中被激活任一端缺失注册都会在对应环境下解析失败服务器专用服务EF Core、Identity只留在服务器Program.cs中——它们本身就不应该暴露给浏览器端。这也解释了 SKILL.md 中两个Program.cs必须注册匹配服务的约束以及评测评分标准中交互组件注入的每个服务两端都要有实现的要求。环境约束双执行环境下的代码纪律Auto 全局模式下同一份代码要先后在两个截然不同的环境中运行因此 auto-global 模板立下三条环境约束代码必须同时在服务器与浏览器两种执行环境中工作不要使用HttpContext也不要在没有RendererInfo防护的情况下使用浏览器专用 JS API——HttpContext只存在于服务器端浏览器专用 API 只在浏览器端存在直接使用会在另一端抛错必须用RendererInfo判断当前渲染环境后再决定是否调用.NET 运行时约 10 MB在首次访问时下载到浏览器并缓存——后续访问直接使用 WebAssembly无需重复下载。这也是 Auto 模式首访快、之后更快的物理基础。Donts 清单Auto 全局模式最容易踩的坑auto-global 模板以五条禁令收尾每一句都对应一个真实的失败模式不要把交互组件放进服务器项目——它们在预渲染阶段看似正常但在 WebAssembly 接管后会失败不要在.Client组件中注入DbContext或服务器专用服务——请改用 HTTP API不要假设执行环境——同一个组件先在 Server 运行、后切 WebAssembly两种路径都要测不要给页面添加rendermode InteractiveAuto——全局交互性已在App.razor中配置好若配置了认证不要给 Identity/Account 页面添加rendermode——它们必须保持静态 SSR。最后一条与 SKILL.md 中的说明呼应-au Individual脚手架出的 ASP.NET Core Identity 页面位于Components/Account/永远是静态 SSR不参与交互渲染模式。落地把模板改写成项目的 AGENTS.mdauto-global 模板的最终用途是作为新建项目的AGENTS.md内容。SKILL.md 的 Create Project AGENTS.md 一节给出了规范流程脚手架完成后在项目根目录双项目结构放在服务器项目根目录创建AGENTS.md依据所选模式从assets/agents-md/中挑选对应模板——auto-global 对应的正是-int Auto -aiModeTemplate fileStatic SSR (-int None)assets/agents-md/ssr-none.mdServer, per-page (-int Server)assets/agents-md/server-per-page.mdServer, global (-int Server -ai)assets/agents-md/server-global.mdWebAssembly, per-page (-int WebAssembly)assets/agents-md/webassembly-per-page.mdWebAssembly, global (-int WebAssembly -ai)assets/agents-md/webassembly-global.mdAuto, per-page (-int Auto)assets/agents-md/auto-per-page.mdAuto, global (-int Auto -ai)assets/agents-md/auto-global.md将模板内容复制进AGENTS.md把每一处{AppName}替换为实际项目名若脚手架时使用了-au Individual追加## Authentication一节注明已配置 ASP.NET Core Identity且Components/Account/下的 Identity 页面始终为静态 SSR不得添加rendermode。这样生成的AGENTS.md会以本仓库模板为准绳为后续接手该项目的 AI Agent 固化渲染模式、组件放置规则、数据访问模式与服务注册纪律避免后续开发过程中破坏 Auto 全局的运行前提。验证与测试确认双环境都能跑SKILL.md 的 After Scaffolding 提供最小验证路径dotnet build确认可编译dotnet run双项目结构在服务器项目目录执行启动应用Auto 模式还需要额外验证两条执行路径——首次访问Server/SignalR与后续访问WebAssembly这正是 评测配置 中要求交代Auto 模式权衡、为何此渲染策略满足需求的原因。对双项目应用还可确认Program.cs已正确注册两套交互组件、交互组件均位于.Client项目、组件代码未假设执行环境——做到这些Auto 全局模式的首访快、之后更快、数据访问安全、认证不裸奔才能全部成立。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考