4. 【Blazor全栈开发实战指南】--Blazor开发环境搭建

一、安装.NET 10 SDK与版本管理

工欲善其事，必先利其器。在开始编写第一行Blazor代码之前，我们需要在本机搭建好完整的.NET 10开发环境。.NET 10是微软发布的最新长期支持版本，内置了大量针对Blazor和ASP.NET Core的性能改进与新特性，是目前开始新项目的最佳选择。

前往dotnet.microsoft.com官方下载页面，选择".NET 10 SDK"对应你操作系统的安装包，下载后按向导完成安装。安装完毕后，打开终端（PowerShell、命令提示符或bash），执行以下命令验证安装是否成功：

bash 复制代码

dotnet --version

如果终端输出类似10.0.xxx的版本号，说明SDK已经正确安装。dotnet --info命令则会列出所有已安装的.NET运行时和SDK版本，以及当前系统架构等详细信息，当系统存在多个.NET版本时这个命令非常有用。

在实际项目中，团队协作时常有一个痛点：不同成员的机器上安装了不同版本的.NET SDK，导致编译行为出现差异。.NET提供了一个优雅的解决方案------global.json文件。在项目根目录放置该文件后，dotnet命令会自动锁定使用指定版本的SDK，消除了版本不一致带来的隐患。

json 复制代码

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestPatch"
  }
}

这里的version字段指定了SDK的基准版本，而rollForward设置为latestPatch意味着当系统没有精确的10.0.100版本时，允许向前滚动到同一小版本的最新补丁（如10.0.101），在保证稳定性的前提下不会因为补丁版本差异而报错。将global.json提交到版本控制系统，团队所有成员便能在统一的SDK版本下开发，CI/CD流水线也会受益于这一约束。

二、IDE选择与配置

Blazor开发对IDE的支持已经相当成熟，主要有两个选择：Visual Studio 2022和Visual Studio Code。

Visual Studio 2022 是Windows平台上功能最完备的Blazor IDE。它内置了对.razor文件的完整支持，包括Razor语法高亮、IntelliSense代码补全、实时错误检查以及与调试器的深度集成。通过Visual Studio Installer安装时，勾选"ASP.NET 和 Web 开发"工作负载即可获得所有Blazor相关工具。在调试Blazor WebAssembly应用时，Visual Studio可以直接在IDE内设置断点并调试运行在浏览器中的C#代码，体验与调试普通桌面应用别无二致。

Visual Studio Code则是跨平台（Windows/macOS/Linux）的轻量级选择，借助以下扩展可以达到接近VS的开发体验：

首先安装C# Dev Kit 扩展（扩展ID：ms-dotnettools.csdevkit），它是微软官方提供的C#开发套件，集成了语言服务、测试资源管理器、解决方案资源管理器等功能，并内置了对.razor文件的IntelliSense支持。安装C# Dev Kit后，C#扩展 （ms-dotnettools.csharp）和**.NET Install Tool**会作为依赖自动安装。

此外，建议安装Razor+扩展以获得更精准的Razor语法高亮，以及GitLens 和REST Client等日常开发工具。

安装完毕后，打开VS Code的设置（Ctrl+,），搜索dotnet，确认"Dotnet: Default Solution"等设置项符合预期。VS Code会在工作区根目录寻找.sln或.csproj文件来自动配置项目，因此建议将整个解决方案目录作为工作区根目录打开。

三、创建第一个Blazor Server应用

环境就绪后，让我们用dotnet命令行工具创建第一个Blazor Server应用。打开终端，切换到你希望存放项目的目录，然后执行：

bash 复制代码

dotnet new blazor -o MyBlazorServer --interactivity Server
cd MyBlazorServer
dotnet run

在.NET 10中，微软对Blazor项目模板进行了统一，blazor模板通过--interactivity参数来指定渲染模式。Server代表Blazor Server交互模式，WebAssembly代表Blazor WebAssembly模式，Auto则根据运行时条件自动选择，None表示纯静态服务器渲染（SSR）。-o MyBlazorServer指定了输出目录和项目名称。

dotnet run启动后，终端会输出类似以下内容：

复制代码

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000

打开浏览器访问https://localhost:5001，你将看到Blazor默认的演示应用，包含首页、计数器和数据获取三个页面。这个计数器页面很有代表性------点击"Click me"按钮时，计数器数字会增加，而整个过程完全没有页面刷新，这正是Blazor Server通过SignalR在服务端处理事件、将差异推送到客户端实现的实时交互。

现在让我们深入了解项目结构。用VS Code或资源管理器打开MyBlazorServer目录：

复制代码

MyBlazorServer/
├── Components/
│   ├── App.razor              # 应用根组件，配置Router和HeadOutlet
│   ├── Routes.razor           # 路由配置组件
│   ├── Layout/
│   │   ├── MainLayout.razor   # 主布局模板（导航栏+页面内容区域）
│   │   └── NavMenu.razor      # 侧边导航菜单组件
│   └── Pages/
│       ├── Home.razor         # 首页（/）
│       ├── Counter.razor      # 计数器页面（/counter）
│       └── Weather.razor      # 天气数据页面（/weather）
├── wwwroot/                   # 静态文件目录
│   ├── app.css                # 全局样式
│   └── favicon.png
├── Program.cs                 # 应用程序入口与服务注册
└── MyBlazorServer.csproj      # 项目文件

Program.cs是理解Blazor Server配置的关键入口，让我们看看它的内容：

csharp 复制代码

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 向依赖注入容器注册Blazor Server所需服务
// AddRazorComponents() 注册了Razor组件渲染引擎
// .AddInteractiveServerComponents() 进一步添加了SignalR实时交互支持
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

// 配置HTTP请求管道（中间件）
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();  // 启用wwwroot目录下的静态文件服务
app.UseAntiforgery();  // 启用防跨站请求伪造（CSRF）保护

// 映射Razor组件的请求处理，启用Server交互模式
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

.AddRazorComponents()将Razor组件渲染引擎注册到服务容器，而.AddInteractiveServerComponents()则在此基础上叠加了SignalR Hub的注册，使组件具备服务端实时交互能力。MapRazorComponents<App>()将App.razor作为应用的根组件挂载到请求管道，AddInteractiveServerRenderMode()告知框架需要支持Server渲染模式。

四、创建第一个Blazor WebAssembly应用

理解了Blazor Server的结构之后，按同样步骤创建一个WebAssembly应用来感受其结构差异：

bash 复制代码

dotnet new blazor -o MyBlazorWasm --interactivity WebAssembly
cd MyBlazorWasm
dotnet run

同样访问https://localhost:5001，你会发现应用界面与Blazor Server几乎完全一样，但首次加载时浏览器的网络面板会显示下载了大量.wasm和.dll文件------这正是.NET 10运行时本身和应用代码被传输到客户端的过程。

WebAssembly托管模式的项目结构与Server模式高度相似，但Program.cs有所不同：

csharp 复制代码

// Program.cs（WebAssembly模式）
var builder = WebApplication.CreateBuilder(args);

// 注册Razor组件服务，并添加WebAssembly交互式组件支持
// 服务器端负责首次静态渲染，客户端WebAssembly再接管交互
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAntiforgery();

// 此处新增了WebAssembly资源的专用端点映射
app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(MyBlazorWasm.Client._Imports).Assembly);

app.Run();

与Server版本相比，最显著的变化是.AddInteractiveWebAssemblyComponents()和.AddInteractiveWebAssemblyRenderMode()。.AddAdditionalAssemblies()则告诉路由引擎，客户端程序集中也定义了Razor组件页面，需要将它们一并纳入路由扫描范围。这是因为WASM模式下，交互式组件运行在独立的Client类库项目中，服务端需要知道客户端组件的位置才能进行正确的路由解析。

两种模式的最本质区别在于C#代码的执行位置：Blazor Server的所有Razor组件逻辑在服务器内存中运行，通过SignalR将UI差分推送给浏览器；Blazor WebAssembly的组件逻辑则被编译成WebAssembly在浏览器沙箱中执行，服务器只提供初始HTML和静态资源。这一差异决定了两种模式在网络需求、服务器负载、初始加载时间和离线能力等方面的本质不同，在上一章我们已经做了详细对比，选择时可以回顾那部分内容。

五、总结

本章我们完成了Blazor开发环境的全套搭建：从安装.NET 10 SDK、用global.json锁定版本，到配置Visual Studio 2022或VS Code，再到分别创建并运行了Blazor Server和Blazor WebAssembly两种类型的项目，并逐一解析了Program.cs的关键配置和项目目录结构。至此，你的机器已经具备了编写和调试Blazor应用的全部条件。

然而，光有环境还不够------应用最终由一个个组件拼装而成。下一章，我们将深入探讨Blazor组件的基础知识：.razor文件的语法结构、组件的完整生命周期钩子、参数与事件的传递机制，以及让UI响应数据变化的绑定与渲染指令。这些是编写任何Blazor应用所必须掌握的核心积木。