C#怎么创建Blazor应用_C# Blazor前端开发入门方法教程【实战】

刚开始接触Blazor时，很多人都会选择用命令行来创建项目，这确实是最轻量、最可控的方式。但这里有几个细节，一旦忽略，后续可能会遇到不少麻烦。比如，选错了项目模板，或者忽略了文件命名与路由的匹配规则，等到组件不渲染、状态不更新时，排查起来就相当头疼了。

用 CLI 创建 Blazor Server 或 WebAssembly 项目

用命令行创建项目，可以说是最轻量也最可控的方式了。但需要注意，模板名必须准确，大小写和连字符都不能出错：

• dotnet new blazorserver -n MyBlazorApp 用于创建 Server 模式，这种模式依赖 SignalR，在服务端进行渲染。
• dotnet new blazorwasm -n MyBlazorApp 用于创建 WebAssembly 模式，这是纯前端方案，.NET 代码直接在浏览器中运行。

这里要留个心，千万别用 blazor 这个模糊的模板名，它已经被弃用了。另外，-n 参数也别忘了加，否则生成的项目会默认叫 WebApplication1，很容易和已有项目混淆。创建完成后，进入目录执行 dotnet run，看到控制台输出 Now listening on: https://localhost:7055，就说明启动成功了。

@page 和组件文件名必须严格匹配

Blazor 的路由注册机制比较特别，它不依赖文件路径，而是靠 @page 指令和文件名（首字母必须大写）来共同完成。常见的错误有两个：

一个是新建了 counter.razor（小写的 c），同时写了 @page "/counter"，结果浏览器虽然能访问，但组件就是不渲染，控制台还会报 Failed to find a valid digest in the index.html。另一个是写了 @page "/Counter"，但文件名却是 Counter.razor，这样路由虽然能命中，但 currentCount 变量却不会响应式更新，原因是组件类名生成失败了。

正确的做法是：文件名必须采用 PascalCase 命名法，比如 Counter.razor。@page 后面的路径可以自定义，但组件标签名（例如 ）会自动从文件名推导。这里有个小建议：不要手动去修改类名或添加 partial 关键字，因为 .razor 编译器会自动生成这些。

事件处理函数签名错一个字母就静默失败

Blazor 的 @onclick 这类事件绑定，编译时不会报错，但参数类型一旦写错，点击就会完全没反应。比如：

• private void IncrementCount(MouseEventArgs e) 是正确的写法，它能获取到按键的详细信息。
• 如果写成 private void IncrementCount(ClickEventArgs e)，这就错了，因为 ClickEventArgs 这个类根本不存在。方法不会被调用，而且控制台也不会有任何提示。
• private void IncrementCount() 也是正确的，但这样做就拿不到事件上下文了。

其他常见的事件参数类型还有 KeyboardEventArgs（对应 @onkeypress）、ChangeEventArgs（对应 @onchange）以及通用的 EventArgs。如果拿不准，最稳妥的办法是去查阅微软官方文档中 Event handling 的页面，确认好拼写和命名空间。

StateHasChanged() 不是万能解药，乱用反而掩盖问题

当发现 UI 没有刷新时，第一反应不应该是立即加上 StateHasChanged()，而是先检查一下，是否在非组件线程里修改了状态。这几种情况很典型：

• 在 Task.Run(() => { currentCount++; }) 里修改变量，因为是异步任务，所以必须显式调用 StateHasChanged()，否则 UI 不会更新。
• 在 async Task FetchData() 里，等待完异步操作再修改 currentCount，这时就不需要手动调用 StateHasChanged()，因为 Blazor 会自动触发重渲染。
• 在 OnInitializedAsync 生命周期里改完值就调用 StateHasChanged()，这其实是多余的，因为该生命周期结束后，Blazor 本身就会触发一次刷新。

真正需要警惕的是另一种情况：加了 StateHasChanged() 后 UI 确实刷新了，但数据又“回退”了。这往往说明你在多个地方重复初始化或覆盖了状态，问题根本不出在渲染机制上。这才是真正需要排查的地方。