C#与Blazor

1. 学习目标与 Bloom 分类法

本节遵循 Benjamin Bloom 于 1956 年提出、Anderson 等人于 2001 年修订的认知能力分类体系，将学习目标按六个层级进行显式标注，便于学习者自评与教师评估。

1.1 学习目标矩阵

1.2 预期先修知识

• C# 基础语法（类型系统、泛型、异步编程）
• .NET 平台基础（SDK、运行时、项目结构）
• HTML/CSS/JavaScript 基础概念
• HTTP 协议与 REST API 设计
• 数据结构与算法基础（树、图、动态规划入门）

1.3 学习评估方式

• L1-L2：通过课后习题的选择题与简答题评估
• L3-L4：通过编程实践作业（实现指定功能组件）评估
• L5-L6：通过课程项目（设计完整应用并撰写技术决策报告）评估

2. 历史动机与演进脉络

2.1 Web 前端的 JavaScript 垄断期（1995-2015）

1995 年 Brendan Eich 在 Netscape 用十天时间设计出 JavaScript，自此浏览器端的脚本编程被这一语言长期垄断。尽管 JavaScript 凭借 ECMAScript 标准化与 V8 引擎的极致优化逐步成为通用前端语言，但其设计历史遗留的诸多问题（隐式类型转换、原型继承混乱、this 绑定诡异）始终困扰开发者。

2009 年 Node.js 的出现使 JavaScript 渗透到服务端，TypeScript（2012）通过类型系统缓解了大规模工程的维护痛点，但前端生态仍被 Webpack、Babel、Rollup 等构建工具链所主导，对 C#/.NET 开发者而言存在显著的认知迁移成本。

2.2 WebAssembly 的诞生与机遇（2015-2017）

WebAssembly（简称 Wasm）是 2015 年由所有主流浏览器厂商联合宣布的二进制指令格式标准，2017 年成为第四种浏览器原生支持的语言（与 HTML、CSS、JavaScript 并列）。Wasm 的关键特性在于：

• 语言中立：任何能编译为 Wasm 字节码的语言都可在浏览器运行
• 沙箱执行：基于 JS 引擎的安全模型，无法直接访问文件系统
• 接近原生的性能：AOT 编译后的执行效率显著高于解释执行的 JavaScript
• 确定性加载：二进制格式体积小、解析快，规避了 JavaScript 的解析开销

Wasm 的出现为非 JavaScript 语言进入浏览器打开了大门，Mozilla 于 2017 年发起的 blazor 实验项目即是其中之一。

2.3 Blazor 的诞生与命名由来

Blazor 的命名来源于 Browser + Razor，即”运行在浏览器中的 Razor 视图引擎”。Razor 是 ASP.NET MVC 时代引入的视图引擎，支持在 HTML 中嵌入 C# 代码。Steve Sanderson（ASP.NET MVC 的原作者之一）于 2017 年在 GitHub 上发布了原型项目 SteveSandersonMS/blazor，使用 Mono 的 Wasm 编译后端将 .NET 程序集在浏览器中运行。

微软于 2018 年正式接手该项目，2019 年发布 Blazor Server 1.0，2020 年发布 Blazor WebAssembly 3.2。.NET 5（2020 年 11 月）将两者合并为统一的 Blazor 框架，.NET 8（2023 年 11 月）引入了 Blazor Auto 渲染模式，标志着 Blazor 进入成熟期。

2.4 渲染模式的代际演进

3. 形式化定义

本节使用形式化语言严格定义 Blazor 的核心概念，便于后续理论推导与性能分析。

3.1 渲染树的代数定义

定义 3.1（渲染树）：Blazor 组件的渲染结果是一棵有序有根树 $T = (V, E, r)$，其中：

• $V$ 是节点集合，每个节点 $v \in V$ 是一个二元组 $v = (\text{type}, \text{attrs})$，其中 $\text{type} \in \{\text{Element}, \text{Component}, \text{Text}\}$，$\text{attrs}: \text{Key} \to \text{Value}$ 是属性映射
• $E \subseteq V \times V$ 是边集合，表示父子关系
• $r \in V$ 是根节点

定义 3.2（渲染函数）：给定组件 $C$ 与状态 $s$，渲染函数 $\text{Render}: (C, s) \to T$ 将组件状态映射为一棵渲染树。Blazor 的 BuildRenderTree 方法即是该函数的实现。

定义 3.3（差分渲染）：设 $T_{n-1}$ 为上一次渲染的树，$T_n$ 为本次渲染的树，差分函数 $\text{Diff}: (T_{n-1}, T_n) \to \Delta$ 输出一组编辑操作 $\Delta = \{(\text{op}, v_i, v_j)\}$，其中 $\text{op} \in \{\text{Insert}, \text{Delete}, \text{Update}, \text{Move}\}$。Blazor 的差分算法基于 顺序键匹配：对每对兄弟节点列表，按顺序比较并优先匹配 @key 标注的节点。

3.2 SignalR 通信模型

定义 3.4（SignalR 连接）：Blazor Server 通过 SignalR 建立持久连接 $\mathcal{C} = (\text{client}, \text{server}, \text{transport})$，其中 $\text{transport} \in \{\text{WebSocket}, \text{SSE}, \text{LongPolling}\}$。连接上的消息流可建模为双向队列：

$\mathcal{C} = (Q_{c \to s}, Q_{s \to c})$

其中 $Q_{c \to s}$ 是客户端到服务端的事件队列，$Q_{s \to c}$ 是服务端到客户端的 DOM 更新指令队列。

定义 3.5（端到端延迟）：用户交互的端到端延迟 $\tau$ 可分解为：

$\tau = \tau_{\text{net}}^{(c \to s)} + \tau_{\text{queue}}^{s} + \tau_{\text{render}}^{s} + \tau_{\text{net}}^{(s \to c)} + \tau_{\text{apply}}^{c}$

其中：

• $\tau_{\text{net}}^{(c \to s)}$：客户端事件上行网络延迟
• $\tau_{\text{queue}}^{s}$：服务端事件队列等待时间
• $\tau_{\text{render}}^{s}$：服务端渲染计算时间
• $\tau_{\text{net}}^{(s \to c)}$：DOM 更新指令下行网络延迟
• $\tau_{\text{apply}}^{c}$：客户端应用 DOM diff 时间

3.3 WebAssembly 加载模型

定义 3.6（WASM 应用加载时间）：Blazor WebAssembly 应用的首屏加载时间 $T_{\text{load}}$ 由以下分量构成：

$T_{\text{load}} = T_{\text{fetch}} + T_{\text{parse}} + T_{\text{instantiate}} + T_{\text{init}} + T_{\text{firstRender}}$

其中：

• $T_{\text{fetch}} = \frac{|\text{wasm}| + |\text{dlls}|}{\text{bandwidth}}$：下载 wasm 运行时与 DLL 的时间
• $T_{\text{parse}}$：浏览器解析 wasm 二进制时间
• $T_{\text{instantiate}}$：wasm 实例化时间
• $T_{\text{init}}$：.NET 运行时初始化时间
• $T_{\text{firstRender}}$：首屏渲染时间

3.4 组件状态机

定义 3.7（组件生命周期状态机）：Blazor 组件的状态可建模为有限状态机 $\mathcal{M} = (S, \Sigma, \delta, s_0, F)$，其中：

• $S = \{\text{Created}, \text{Initializing}, \text{Initialized}, \text{ParametersSet}, \text{Rendering}, \text{Rendered}, \text{Disposing}, \text{Disposed}\}$
• $\Sigma = \{\text{construct}, \text{init}, \text{paramsSet}, \text{render}, \text{stateChanged}, \text{dispose}\}$
• $\delta: S \times \Sigma \to S$ 是状态转移函数
• $s_0 = \text{Created}$ 是初始状态
• $F = \{\text{Disposed}\}$ 是终态

状态转移规则如下：

$\delta(\text{Created}, \text{construct}) = \text{Initializing}$ $\delta(\text{Initializing}, \text{init}) = \text{Initialized}$ $\delta(\text{Initialized}, \text{paramsSet}) = \text{ParametersSet}$ $\delta(\text{ParametersSet}, \text{render}) = \text{Rendering}$ $\delta(\text{Rendering}, \_) = \text{Rendered}$ $\delta(\text{Rendered}, \text{stateChanged}) = \text{Rendering}$ $\delta(\text{Rendered}, \text{paramsSet}) = \text{ParametersSet}$ $\delta(\text{Rendered}, \text{dispose}) = \text{Disposing}$ $\delta(\text{Disposing}, \_) = \text{Disposed}$

4. 理论推导与性能分析

4.1 差分渲染算法复杂度

定理 4.1（差分渲染复杂度）：设两棵兄弟节点列表长度分别为 $m$ 与 $n$，若所有节点均使用 @key 标注且键唯一，则 Blazor 的差分算法时间复杂度为 $\mathcal{O}(m + n)$；若不使用 @key，最坏情况为 $\mathcal{O}(m \cdot n)$。

证明：使用 @key 时，算法通过哈希表索引实现 $O(1)$ 查找，整体为线性扫描，故 $O(m + n)$。不使用 @key 时，算法退化为顺序比较，对于”删除头部、追加尾部”等场景需逐项移动，最坏情况下每项需线性查找匹配点，故 $O(m \cdot n)$。$\square$

推论 4.1：在动态列表场景（如表格排序、过滤）中，未标注 @key 会造成 $n$ 倍的性能退化，应强制使用 @key。

4.2 SignalR 延迟下界

定理 4.2（最小交互延迟）：在 Blazor Server 模式下，单次用户交互的最小端到端延迟 $\tau_{\min}$ 满足：

$\tau_{\min} \geq 2 \cdot \text{RTT} + \tau_{\text{render}}^{s}$

其中 RTT 为客户端到服务端的往返时延。这是由于事件必须上行至服务端、渲染结果必须下行至客户端，至少经历一次完整往返。

实证数据（来自微软官方基准测试）：

4.3 WebAssembly 加载时间下界

定理 4.3（WASM 首屏加载下界）：在带宽 $B$ 与最小应用体积 $V$ 给定时，Blazor WebAssembly 应用的首屏加载时间下界为：

$T_{\text{load}} \geq \frac{V}{B} + T_{\text{instantiate}}$

实测数据（.NET 8，未裁剪的应用，带宽 10 Mbps）：

通过 Trimmer 裁剪 与 AOT 编译 可将体积压缩至 2-3 MB，加载时间降至 2-3 秒。

4.4 内存占用模型

定理 4.4（组件内存占用）：Blazor 应用中，单个组件实例的内存占用 $M$ 近似为：

$M \approx M_{\text{base}} + |\text{state}| + |\text{refs}| \cdot 8 + |\text{handlers}| \cdot 32$

其中 $M_{\text{base}} \approx 200$ 字节是组件基类开销，$|\text{state}|$ 是字段总字节数，$|\text{refs}|$ 是对象引用数，$|\text{handlers}|$ 是事件处理器数量。

工程含义：复杂表格中若有 10000 行，每行 5 个事件处理器，则仅事件处理器开销即 $10000 \times 5 \times 32 = 1.6$ MB。应通过虚拟化（<Virtualize>）限制同时渲染的行数。

5. 代码示例与实战演示

本节通过完整代码示例演示 Blazor 的核心功能，所有代码均包含中文工程级注释，遵循可维护性优先原则。

5.1 基础组件：计数器

@* Counter.razor - 最基础的 Blazor 组件，演示状态与事件绑定 *@
@page "/counter"

<PageTitle>计数器示例</PageTitle>

<h1>计数器</h1>
<p role="status" aria-live="polite">当前计数: @currentCount</p>
<p>步长: @Step</p>

<button class="btn btn-primary" @onclick="IncrementCount">
    点击加 @Step
</button>

<button class="btn btn-secondary" @onclick="ResetCount">
    重置
</button>

@code {
    // 组件内部状态，每次状态变化触发重新渲染
    private int currentCount = 0;

    // 组件参数，可由父组件传入
    [Parameter]
    public int Step { get; set; } = 1;

    // 递增方法，作为事件处理器
    private void IncrementCount()
    {
        currentCount += Step;
    }

    // 重置方法
    private void ResetCount()
    {
        currentCount = 0;
    }
}

5.2 组件参数与父子通信

@* ProductCard.razor - 子组件，演示参数接收与事件回调 *@
<div class="card @CardClass">
    <img src="@ImageUrl" alt="@Title" class="card-img-top" />
    <div class="card-body">
        <h5 class="card-title">@Title</h5>
        <p class="card-text">@Description</p>
        <p class="card-price">¥@Price.ToString("F2")</p>

        @* 条件渲染 *@
        @if (IsInStock)
        {
            <button class="btn btn-primary" @onclick="OnBuyClicked">
                加入购物车
            </button>
        }
        else
        {
            <span class="text-muted">暂时缺货</span>
        }
    </div>
</div>

@code {
    // 必填参数，父组件必须提供
    [Parameter]
    [EditorRequired]
    public string Title { get; set; } = string.Empty;

    // 可选参数，带默认值
    [Parameter]
    public string Description { get; set; } = string.Empty;

    [Parameter]
    public decimal Price { get; set; }

    [Parameter]
    public string ImageUrl { get; set; } = "/images/default.png";

    [Parameter]
    public bool IsInStock { get; set; } = true;

    // 级联参数：父组件通过 CascadingValue 提供，无需显式传递
    [CascadingParameter]
    public ThemeInfo? Theme { get; set; }

    // 事件回调：通知父组件发生了指定事件
    [Parameter]
    public EventCallback<ProductCard> OnBuyClicked { get; set; }

    // 计算属性：根据主题返回 CSS 类
    private string CardClass => Theme?.Mode switch
    {
        "dark" => "bg-dark text-light",
        "light" => "bg-light",
        _ => string.Empty
    };
}

@* ProductList.razor - 父组件，演示参数传递与回调处理 *@
@page "/products"
@inject IProductService ProductService

<PageTitle>商品列表</PageTitle>

<h1>商品列表</h1>

@* 级联参数：所有子组件均可接收 *@
<CascadingValue Value="themeInfo" Name="Theme">
    <div class="product-grid">
        @foreach (var product in products)
        {
            <ProductCard
                Title="@product.Name"
                Description="@product.Description"
                Price="@product.Price"
                ImageUrl="@product.ImageUrl"
                IsInStock="@product.Stock > 0"
                OnBuyClicked="HandleBuy" />

            @* 使用 @key 提升 diff 性能 *@
        }
    </div>
</CascadingValue>

@if (cart.Count > 0)
{
    <div class="cart-summary">
        购物车: @cart.Count 件商品，合计 ¥@cart.Sum(p => p.Price).ToString("F2")
    </div>
}

@code {
    // 注入的服务：依赖注入获取商品数据
    [Inject]
    private IProductService ProductService { get; set; } = default!;

    // 组件状态
    private List<Product> products = new();
    private List<Product> cart = new();
    private readonly ThemeInfo themeInfo = new() { Mode = "light" };

    // 生命周期：组件初始化时加载商品数据
    protected override async Task OnInitializedAsync()
    {
        products = await ProductService.GetProductsAsync();
    }

    // 处理子组件回调
    private void HandleBuy(ProductCard card)
    {
        var product = products.First(p => p.Name == card.Title);
        cart.Add(product);
    }
}

// 主题信息载体
public class ThemeInfo
{
    public string Mode { get; set; } = "light";
}

5.3 双向绑定与表单

@* FormDemo.razor - 演示双向绑定、表单验证、模型驱动 *@
@page "/form"

<PageTitle>用户注册</PageTitle>

<h1>用户注册</h1>

<EditForm Model="@model" OnValidSubmit="HandleSubmit" Context="formContext">
    <DataAnnotationsValidator />

    <div class="form-group">
        <label for="username">用户名</label>
        <InputText id="username"
                   @bind-Value="model.UserName"
                   @bind-Value:event="oninput"
                   class="form-control" />
        <ValidationMessage For="@(() => model.UserName)" class="text-danger" />
    </div>

    <div class="form-group">
        <label for="email">邮箱</label>
        <InputText id="email" @bind-Value="model.Email" class="form-control" />
        <ValidationMessage For="@(() => model.Email)" class="text-danger" />
    </div>

    <div class="form-group">
        <label for="age">年龄</label>
        <InputNumber id="age" @bind-Value="model.Age" class="form-control" />
        <ValidationMessage For="@(() => model.Age)" class="text-danger" />
    </div>

    <div class="form-group">
        <label>性别</label>
        <InputRadioGroup @bind-Value="model.Gender">
            @foreach (var g in genders)
            {
                <div class="form-check">
                    <InputRadio Value="@g.Value" id="gender-@g.Value" class="form-check-input" />
                    <label for="gender-@g.Value" class="form-check-label">@g.Label</label>
                </div>
            }
        </InputRadioGroup>
    </div>

    <div class="form-group">
        <label>兴趣</label>
        <InputCheckbox @bind-Value="model.AcceptTerms" /> 同意服务条款
        <ValidationMessage For="@(() => model.AcceptTerms)" class="text-danger" />
    </div>

    <button type="submit" class="btn btn-primary" disabled="@formContext.IsSubmitting">
        @(formContext.IsSubmitting ? "提交中..." : "提交")
    </button>
</EditForm>

@code {
    private RegisterModel model = new();
    private bool isSubmitting = false;

    // 性别选项数据源
    private readonly List<GenderOption> genders = new()
    {
        new() { Value = "M", Label = "男" },
        new() { Value = "F", Label = "女" },
        new() { Value = "O", Label = "其他" }
    };

    // 处理表单提交
    private async Task HandleSubmit(EditContext context)
    {
        isSubmitting = true;
        try
        {
            // 模拟异步提交
            await Task.Delay(1000);
            // 实际场景：调用后端 API
            Console.WriteLine($"注册用户: {model.UserName}");
        }
        finally
        {
            isSubmitting = false;
        }
    }
}

// 注册模型，使用 DataAnnotations 进行验证
public class RegisterModel
{
    [Required(ErrorMessage = "用户名不能为空")]
    [StringLength(20, MinimumLength = 3, ErrorMessage = "用户名长度 3-20 个字符")]
    public string UserName { get; set; } = string.Empty;

    [Required(ErrorMessage = "邮箱不能为空")]
    [EmailAddress(ErrorMessage = "邮箱格式不正确")]
    public string Email { get; set; } = string.Empty;

    [Range(18, 120, ErrorMessage = "年龄必须在 18-120 之间")]
    public int Age { get; set; }

    [Required(ErrorMessage = "请选择性别")]
    public string Gender { get; set; } = string.Empty;

    [Range(typeof(bool), "true", "true", ErrorMessage = "必须同意服务条款")]
    public bool AcceptTerms { get; set; }
}

public class GenderOption
{
    public string Value { get; set; } = string.Empty;
    public string Label { get; set; } = string.Empty;
}

5.4 生命周期方法详解

@* LifecycleDemo.razor - 完整生命周期演示 *@
@page "/lifecycle"
@implements IDisposable
@implements IAsyncDisposable

<h3>生命周期演示</h3>

<p>当前阶段: @currentPhase</p>
<p>渲染次数: @renderCount</p>

@code {
    private string currentPhase = "未初始化";
    private int renderCount = 0;
    private Timer? _timer;
    private CancellationTokenSource _cts = new();

    // 阶段 1：构造函数（在所有生命周期之前）
    // 注意：此时注入的服务尚未就绪
    public LifecycleDemo()
    {
        currentPhase = "构造完成";
    }

    // 阶段 2：同步初始化
    // 适用场景：设置初始状态、初始化字段
    protected override void OnInitialized()
    {
        currentPhase = "OnInitialized";
    }

    // 阶段 3：异步初始化
    // 适用场景：调用 API 加载数据、异步初始化资源
    protected override async Task OnInitializedAsync()
    {
        currentPhase = "OnInitializedAsync - 开始";
        await Task.Delay(500); // 模拟异步操作
        currentPhase = "OnInitializedAsync - 完成";

        // 启动后台定时器
        _timer = new Timer(_ =>
        {
            InvokeAsync(StateHasChanged);
        }, null, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(1));
    }

    // 阶段 4：参数设置（每次参数变化时调用）
    protected override void OnParametersSet()
    {
        currentPhase = "OnParametersSet";
    }

    // 阶段 5：异步参数设置
    protected override Task OnParametersSetAsync()
    {
        return Task.CompletedTask;
    }

    // 阶段 6：渲染前调用（用于设置渲染状态）
    // 注意：此时不应触发状态变化，否则会导致无限渲染循环
    protected override bool ShouldRender()
    {
        return true;
    }

    // 阶段 7：渲染后调用
    // firstRender 表示是否首次渲染
    protected override void OnAfterRender(bool firstRender)
    {
        renderCount++;
        if (firstRender)
        {
            currentPhase = "首次渲染完成";
            // 此时 DOM 已就绪，可调用 JS 互操作
            _ = InitializeJsInteropAsync();
        }
    }

    // 阶段 8：异步渲染后调用
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await Task.CompletedTask;
        }
    }

    // 阶段 9：释放资源（同步版本）
    public void Dispose()
    {
        _timer?.Dispose();
        _cts.Cancel();
        _cts.Dispose();
    }

    // 阶段 10：异步释放资源
    public async ValueTask DisposeAsync()
    {
        await Task.CompletedTask;
    }

    private async Task InitializeJsInteropAsync()
    {
        // JS 互操作代码
        await Task.CompletedTask;
    }
}

5.5 路由与导航

// Program.cs - 配置路由
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

var app = builder.Build();

app.UseAntiforgery();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Counter).Assembly);

app.Run();

@* App.razor - 根组件，配置路由 *@
<Router AppAssembly="@typeof(App).Assembly"
        AdditionalAssemblies="new[] { typeof(Client.Pages.Products).Assembly }">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
    <NotFound>
        <PageTitle>未找到</PageTitle>
        <h1>页面未找到</h1>
        <p>抱歉，您访问的页面不存在。</p>
        <a href="/">返回首页</a>
    </NotFound>
</Router>

@* UserDetail.razor - 路由参数与约束 *@
@page "/user/{Id:int}"
@page "/user/{Id:int}/{Name:length(1,50)}"
@page "/user/{Id:int}/{Name:length(1,50)}/{Tab:regex(^profile$|^posts$)}"

@inject NavigationManager Navigation

<h3>用户详情</h3>
<p>用户 ID: @Id</p>
<p>姓名: @Name</p>
<p>当前标签页: @Tab</p>

<nav>
    <button @onclick="GoToProfile">个人资料</button>
    <button @onclick="GoToPosts">发布内容</button>
    <button @onclick="GoBack">返回列表</button>
</nav>

@code {
    // 路由参数自动绑定到属性
    [Parameter]
    public int Id { get; set; }

    [Parameter]
    public string Name { get; set; } = "匿名用户";

    [Parameter]
    public string Tab { get; set; } = "profile";

    // 查询参数：通过 NavigationManager 获取
    [SupplyParameterFromQuery]
    public string? Filter { get; set; }

    private void GoToProfile()
    {
        Navigation.NavigateTo($"/user/{Id}/{Name}/profile");
    }

    private void GoToPosts()
    {
        Navigation.NavigateTo($"/user/{Id}/{Name}/posts");
    }

    private void GoBack()
    {
        Navigation.NavigateTo("/users");
    }

    // 拦截导航
    protected override void OnInitialized()
    {
        Navigation.LocationChanged += OnLocationChanged;
    }

    private void OnLocationChanged(object? sender, LocationChangedEventArgs e)
    {
        // 处理 URL 变化
    }

    public void Dispose()
    {
        Navigation.LocationChanged -= OnLocationChanged;
    }
}

5.6 依赖注入与服务生命周期

// Program.cs - 注册服务
var builder = WebApplication.CreateBuilder(args);

// Scoped：作用域单例，在 Blazor Server 中每个电路（connection）共享一个实例
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddScoped<CartService>();

// Singleton：应用单例，所有用户共享（注意线程安全）
builder.Services.AddSingleton<IConfigurationService, ConfigurationService>();

// Transient：瞬时，每次请求都创建新实例
builder.Services.AddTransient<IEmailSender, EmailSender>();

// Blazor Server 特有：电路内的 Scoped 等价于 Singleton
// Blazor WASM 特有：Scoped 等价于 Singleton（单客户端）

var app = builder.Build();
app.Run();

@* ServiceInjection.razor - 多种注入方式 *@
@page "/di-demo"
@inject IUserService UserService
@inject ILogger<ServiceInjectionDemo> Logger
@inject NavigationManager Navigation

<h3>依赖注入演示</h3>

<p>当前用户: @(currentUser?.Name ?? "未登录")</p>

@code {
    // 方式 1：@inject 指令注入（推荐用于页面组件）
    // UserService、Logger、Navigation 均通过 @inject 注入

    // 方式 2：[Inject] 特性注入（用于代码块）
    [Inject]
    public CartService Cart { get; set; } = default!;

    // 方式 3：构造函数注入（.NET 8+ 支持）
    // 注意：Blazor 组件的构造函数注入需要 [Inject] 特性
    private User? currentUser;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            currentUser = await UserService.GetCurrentUserAsync();
            Logger.LogInformation("用户 {Name} 已加载", currentUser?.Name);
        }
        catch (Exception ex)
        {
            Logger.LogError(ex, "加载用户信息失败");
        }
    }
}

5.7 JavaScript 互操作

@* JsInterop.razor - JS 互操作完整示例 *@
@page "/js-interop"
@inject IJSRuntime JS
@implements IAsyncDisposable

<h3>JavaScript 互操作</h3>

<button class="btn btn-primary" @onclick="ShowAlert">弹出提示</button>
<button class="btn btn-info" @onclick="GetWindowWidth">获取窗口宽度</button>
<button class="btn btn-warning" @onclick="ScrollToTop">滚动到顶部</button>

<p>窗口宽度: @windowWidth px</p>

<div id="chart-container" style="height: 300px;"></div>

@code {
    private int windowWidth;
    private IJSObjectReference? module;
    private IJSObjectReference? chartInstance;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            // 按需加载 JS 模块（推荐方式，避免污染全局命名空间）
            module = await JS.InvokeAsync<IJSObjectReference>(
                "import", "./js/chartModule.js");

            // 初始化图表
            chartInstance = await module.InvokeAsync<IJSObjectReference>(
                "createChart", "chart-container");
        }
    }

    private async Task ShowAlert()
    {
        // 简单调用：直接调用全局函数
        await JS.InvokeVoidAsync("alert", "这是来自 C# 的消息");
    }

    private async Task GetWindowWidth()
    {
        // 带返回值调用
        windowWidth = await JS.InvokeAsync<int>("eval", "window.innerWidth");
    }

    private async Task ScrollToTop()
    {
        // 调用模块内的方法
        if (module is not null)
        {
            await module.InvokeVoidAsync("scrollToTop", "smooth");
        }
    }

    // 释放 JS 对象引用，避免内存泄漏
    public async ValueTask DisposeAsync()
    {
        if (chartInstance is not null)
        {
            await chartInstance.InvokeVoidAsync("destroy");
            await chartInstance.DisposeAsync();
        }
        if (module is not null)
        {
            await module.DisposeAsync();
        }
    }
}

// wwwroot/js/chartModule.js - 按需加载的 ES 模块

// 创建图表实例
export function createChart(containerId) {
    const container = document.getElementById(containerId);
    if (!container) return null;

    // 模拟图表初始化
    const chart = {
        container: container,
        data: [],
        update(newData) {
            this.data = newData;
            this.render();
        },
        render() {
            // 实际场景：使用 ECharts、Chart.js 等库
            this.container.innerHTML = `<div>图表数据: ${JSON.stringify(this.data)}</div>`;
        },
        destroy() {
            this.container.innerHTML = '';
        }
    };

    return chart;
}

// 滚动到顶部
export function scrollToTop(behavior = 'smooth') {
    window.scrollTo({ top: 0, behavior: behavior });
}

// 注册全局函数（仅当必须时）
window.showToast = function(message) {
    alert(message);
};

5.8 状态管理：Scoped 服务与容器组件

// CartService.cs - 全局购物车状态
public class CartService : IDisposable
{
    // 状态存储
    private readonly List<CartItem> _items = new();
    private readonly SemaphoreSlim _lock = new(1, 1);

    // 状态变化通知：使用 .NET 事件
    public event Action? OnChange;

    // 只读快照
    public IReadOnlyList<CartItem> Items => _items.AsReadOnly();

    public decimal TotalPrice => _items.Sum(i => i.Price * i.Quantity);

    public int TotalCount => _items.Sum(i => i.Quantity);

    // 添加商品（线程安全）
    public async Task AddAsync(Product product, int quantity = 1)
    {
        await _lock.WaitAsync();
        try
        {
            var existing = _items.FirstOrDefault(i => i.ProductId == product.Id);
            if (existing is not null)
            {
                existing.Quantity += quantity;
            }
            else
            {
                _items.Add(new CartItem
                {
                    ProductId = product.Id,
                    Name = product.Name,
                    Price = product.Price,
                    Quantity = quantity
                });
            }
        }
        finally
        {
            _lock.Release();
        }

        // 通知订阅者
        OnChange?.Invoke();
    }

    public async Task RemoveAsync(int productId)
    {
        await _lock.WaitAsync();
        try
        {
            _items.RemoveAll(i => i.ProductId == productId);
        }
        finally
        {
            _lock.Release();
        }
        OnChange?.Invoke();
    }

    public void Dispose()
    {
        _lock.Dispose();
    }
}

public class CartItem
{
    public int ProductId { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public int Quantity { get; set; }
}

@* CartIndicator.razor - 订阅状态变化的指示器组件 *@
@inject CartService Cart
@implements IDisposable

<span class="badge badge-primary">@cartCount</span>

@code {
    private int cartCount;

    protected override void OnInitialized()
    {
        // 订阅状态变化
        Cart.OnChange += UpdateCount;
        UpdateCount();
    }

    private void UpdateCount()
    {
        cartCount = Cart.TotalCount;
        // 触发组件重新渲染
        InvokeAsync(StateHasChanged);
    }

    // 必须取消订阅，否则造成内存泄漏
    public void Dispose()
    {
        Cart.OnChange -= UpdateCount;
    }
}

5.9 认证与授权

// Program.cs - 配置认证
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();
builder.Services.AddCascadingAuthenticationState();
builder.Services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
builder.Services.AddScoped<IdentityRedirectManager>();

// CustomAuthStateProvider.cs - 自定义认证状态提供者
public class CustomAuthStateProvider : AuthenticationStateProvider
{
    private readonly HttpClient _http;
    private readonly IJSRuntime _js;

    public CustomAuthStateProvider(HttpClient http, IJSRuntime js)
    {
        _http = http;
        _js = js;
    }

    public override async Task<AuthenticationState> GetAuthenticationStateAsync()
    {
        // 从 localStorage 读取 token
        var token = await _js.InvokeAsync<string>("localStorage.getItem", "authToken");

        if (string.IsNullOrEmpty(token))
        {
            return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));
        }

        // 解析 token 获取声明
        var claims = ParseClaimsFromJwt(token);
        var identity = new ClaimsIdentity(claims, "jwt");
        var user = new ClaimsPrincipal(identity);

        return new AuthenticationState(user);
    }

    public void NotifyUserAuthentication(string token)
    {
        var claims = ParseClaimsFromJwt(token);
        var identity = new ClaimsIdentity(claims, "jwt");
        var user = new ClaimsPrincipal(identity);

        // 通知所有订阅 AuthorizeRouteView 的组件
        NotifyAuthenticationStateChanged(
            Task.FromResult(new AuthenticationState(user)));
    }

    public void NotifyUserLogout()
    {
        NotifyAuthenticationStateChanged(
            Task.FromResult(new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()))));
    }

    private static IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
    {
        var payload = jwt.Split('.')[1];
        var jsonBytes = ParseBase64WithoutPadding(payload);
        var keyValuePairs = JsonSerializer.Deserialize<Dictionary<string, object>>(jsonBytes)!;

        return keyValuePairs.Select(kvp => new Claim(kvp.Key, kvp.Value.ToString()!));
    }

    private static byte[] ParseBase64WithoutPadding(string base64)
    {
        switch (base64.Length % 4)
        {
            case 2: base64 += "=="; break;
            case 3: base64 += "="; break;
        }
        return Convert.FromBase64String(base64);
    }
}

@* Login.razor - 登录组件 *@
@page "/login"
@inject CustomAuthStateProvider AuthProvider
@inject NavigationManager Navigation
@inject IJSRuntime JS

<PageTitle>登录</PageTitle>

<h3>登录</h3>

<EditForm Model="@loginModel" OnValidSubmit="HandleLogin">
    <DataAnnotationsValidator />

    <div class="form-group">
        <label>用户名</label>
        <InputText @bind-Value="loginModel.Username" class="form-control" />
    </div>

    <div class="form-group">
        <label>密码</label>
        <InputText type="password" @bind-Value="loginModel.Password" class="form-control" />
    </div>

    <button type="submit" class="btn btn-primary" disabled="@isLoading">
        @(isLoading ? "登录中..." : "登录")
    </button>
</EditForm>

@if (errorMessage is not null)
{
    <div class="alert alert-danger">@errorMessage</div>
}

@code {
    private LoginModel loginModel = new();
    private bool isLoading = false;
    private string? errorMessage;

    private async Task HandleLogin()
    {
        isLoading = true;
        errorMessage = null;

        try
        {
            // 调用后端 API 获取 token
            var token = await LoginAsync(loginModel);

            // 存储 token
            await JS.InvokeVoidAsync("localStorage.setItem", "authToken", token);

            // 更新认证状态
            AuthProvider.NotifyUserAuthentication(token);

            // 跳转首页
            Navigation.NavigateTo("/");
        }
        catch (Exception ex)
        {
            errorMessage = "登录失败: " + ex.Message;
        }
        finally
        {
            isLoading = false;
        }
    }

    private async Task<string> LoginAsync(LoginModel model)
    {
        // 实际场景：调用后端 API
        await Task.Delay(500);
        return "fake.jwt.token";
    }
}

@* AuthorizeView - 基于角色的授权视图 *@
<AuthorizeView>
    <Authorized>
        <p>欢迎, @context.User.Identity?.Name!</p>
        <button @onclick="Logout">登出</button>
    </Authorized>
    <NotAuthorized>
        <p>请先登录</p>
        <a href="/login">去登录</a>
    </NotAuthorized>
</AuthorizeView>

@* 基于角色的授权 *@
<AuthorizeView Roles="Admin,Manager">
    <Authorized>
        <a href="/admin">管理后台</a>
    </Authorized>
</AuthorizeView>

@* 基于策略的授权 *@
<AuthorizeView Policy="Over18">
    <Authorized>
        <p>已验证年龄</p>
    </Authorized>
</AuthorizeView>

5.10 虚拟化与性能优化

@* VirtualizedList.razor - 大数据列表虚拟化 *@
@page "/virtualized"

<h3>大数据列表（虚拟化）</h3>

<Virtualize Items="@largeData" Context="item" OverscanCount="10">
    <ItemContent>
        <div class="list-item">
            <span>@item.Id</span>
            <span>@item.Name</span>
            <span>@item.CreatedAt.ToString("yyyy-MM-dd")</span>
        </div>
    </ItemContent>
    <Placeholder>
        <div class="list-item placeholder">加载中...</div>
    </Placeholder>
</Virtualize>

@code {
    private List<DataItem> largeData = new();

    protected override void OnInitialized()
    {
        // 生成 10 万条数据
        largeData = Enumerable.Range(1, 100000)
            .Select(i => new DataItem
            {
                Id = i,
                Name = $"项目 {i}",
                CreatedAt = DateTime.Now.AddDays(-i)
            })
            .ToList();
    }
}

public class DataItem
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; }
}

@* AsyncVirtualizedList.razor - 异步加载虚拟化列表 *@
@page "/async-virtualized"
@inject IDataService DataService

<Virtualize ItemsProvider="@LoadItems" Context="item">
    <ItemContent>
        <div>@item.Title</div>
    </ItemContent>
</Virtualize>

@code {
    // 异步数据提供者：按需加载
    private async ValueTask<ItemsProviderResult<RemoteItem>> LoadItems(
        ItemsProviderRequest request)
    {
        try
        {
            // request.StartIndex：起始索引
            // request.Count：请求数量
            var items = await DataService.GetItemsAsync(
                request.StartIndex, request.Count, request.CancellationToken);

            // 返回结果与总数
            return new ItemsProviderResult<RemoteItem>(
                items.Items, items.TotalCount);
        }
        catch (OperationCanceledException)
        {
            return new ItemsProviderResult<RemoteItem>(Array.Empty<RemoteItem>(), 0);
        }
    }
}

public record RemoteItem(string Title);
public record PagedResult<T>(IReadOnlyList<T> Items, int TotalCount);

6. 对比分析

6.1 Blazor 托管模型对比

6.2 Blazor 与其他前端框架对比

6.3 渲染模式选择决策矩阵

是否需要离线支持？
├── 是 → Blazor WebAssembly / Auto
│   └── 首屏速度是否关键？
│       ├── 是 → Blazor Auto
│       └── 否 → Blazor WebAssembly
└── 否
    └── 是否为内网应用？
        ├── 是 → Blazor Server
        └── 否
            └── 用户是否主要使用 C# 团队？
                ├── 是 → Blazor Auto
                └── 否 → 考虑 React/Vue

7. 常见陷阱与误区

7.1 渲染相关陷阱

陷阱 7.1：在 OnParametersSet 中触发状态变化

// 错误示例：会导致无限渲染循环
protected override void OnParametersSet()
{
    // 错误：每次参数设置都修改状态，触发重新渲染，再次进入 OnParametersSet
    someState = ComputeFromParameters();
    StateHasChanged(); // 多余且危险
}

// 正确做法：使用 OnParametersSetAsync 进行异步计算
protected override async Task OnParametersSetAsync()
{
    if (someState is null)
    {
        someState = await ComputeFromParametersAsync();
    }
}

陷阱 7.2：忘记使用 @key 导致列表性能问题

@* 错误：未使用 @key，排序时所有元素重新渲染 *@
@foreach (var item in items)
{
    <ListItem Data="@item" />
}

@* 正确：使用唯一键 *@
@foreach (var item in items)
{
    <ListItem Data="@item" @key="item.Id" />
}

陷阱 7.3：在 ShouldRender 中执行副作用

// 错误：ShouldRender 应为纯函数
protected override bool ShouldRender()
{
    Logger.LogInformation("渲染检查"); // 副作用！
    return true;
}

// 正确：保持纯净
protected override bool ShouldRender() => _shouldRender;

7.2 异步陷阱

陷阱 7.4：未 await 异步操作

// 错误：fire-and-forget，异常被吞掉
protected override void OnInitialized()
{
    _ = LoadDataAsync(); // 异常被吞掉
}

// 正确：使用 OnInitializedAsync 或捕获异常
protected override async Task OnInitializedAsync()
{
    try
    {
        await LoadDataAsync();
    }
    catch (Exception ex)
    {
        Logger.LogError(ex, "加载失败");
    }
}

陷阱 7.5：在事件处理器中未调用 StateHasChanged

// 错误：异步事件处理器中修改状态后未通知
private async Task LoadData()
{
    data = await FetchData();
    // 忘记调用 StateHasChanged
}

// 在 OnInitializedAsync 等生命周期中会自动调用
// 但在按钮点击等事件处理器中需要手动调用（实际上 Blazor 会自动处理）

7.3 内存泄漏陷阱

陷阱 7.6：未取消事件订阅

// 错误：订阅未取消，导致组件无法被 GC
protected override void OnInitialized()
{
    SomeService.OnChange += HandleChange;
}

// 正确：在 Dispose 中取消订阅
@implements IDisposable

protected override void OnInitialized()
{
    SomeService.OnChange += HandleChange;
}

public void Dispose()
{
    SomeService.OnChange -= HandleChange;
}

陷阱 7.7：JS 对象引用未释放

// 错误：创建的 JS 对象引用未释放
private IJSObjectReference? _chart;

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        _chart = await JS.InvokeAsync<IJSObjectReference>("createChart");
    }
}

// 正确：实现 IAsyncDisposable
public async ValueTask DisposeAsync()
{
    if (_chart is not null)
    {
        await _chart.DisposeAsync();
    }
}

7.4 Blazor Server 特有陷阱

陷阱 7.8：长时间运行的任务阻塞电路

// 错误：长时间阻塞会导致 SignalR 超时
private async Task ProcessLargeData()
{
    await Task.Run(() =>
    {
        // 长时间 CPU 密集型计算
        Thread.Sleep(30000); // 30 秒
    });
}

// 正确：分批处理并定期通知进度
private async Task ProcessLargeData()
{
    foreach (var batch in data.Chunk(100))
    {
        ProcessBatch(batch);
        progress = ...;
        StateHasChanged();
        await Task.Delay(1); // 让出控制权
    }
}

陷阱 7.9：滥用 Scoped 服务

// 错误：在 Blazor Server 中，Scoped 等于每电路单例
// 大量状态会导致内存占用爆炸
public class BigStateService
{
    private List<HugeData> _data = new(); // 每用户都有一份
}

// 正确：使用缓存或共享服务
builder.Services.AddSingleton<SharedCacheService>();

7.5 Blazor WebAssembly 特有陷阱

陷阱 7.10：同步阻塞操作

// 错误：WASM 是单线程，同步阻塞会冻结 UI
private void LoadData()
{
    var result = httpClient.GetStringAsync(url).Result; // 死锁！
}

// 正确：使用 async/await
private async Task LoadDataAsync()
{
    var result = await httpClient.GetStringAsync(url);
}

陷阱 7.11：未配置 CORS

// 错误：直接调用外部 API 会被浏览器 CORS 拦截
var response = await httpClient.GetAsync("https://api.example.com/data");

// 正确方案 1：服务端配置 CORS
// 方案 2：通过 Blazor Server 代理
// 方案 3：使用同源策略

8. 工程实践与最佳实践

8.1 项目结构规范

MyBlazorApp/
├── src/
│   ├── MyBlazorApp/                # 主项目
│   │   ├── Components/
│   │   │   ├── Layout/             # 布局组件
│   │   │   ├── Pages/              # 路由页面
│   │   │   ├── Shared/             # 共享组件
│   │   │   └── _Imports.razor      # 全局 using
│   │   ├── wwwroot/
│   │   │   ├── css/
│   │   │   ├── js/
│   │   │   └── lib/                # 第三方库
│   │   ├── Models/                 # 数据模型
│   │   ├── Services/               # 业务服务
│   │   ├── Data/                   # 数据访问
│   │   ├── Program.cs
│   │   └── appsettings.json
│   ├── MyBlazorApp.Client/         # WASM 客户端项目（Auto 模式）
│   └── MyBlazorApp.Shared/         # 共享代码
├── tests/
│   ├── MyBlazorApp.UnitTests/
│   └── MyBlazorApp.E2ETests/
└── MyBlazorApp.sln

8.2 组件设计原则

原则 8.1：单一职责

@* 错误：一个组件承担多个职责 *@
<Page>
    <Form />
    <Table />
    <Chart />
    <ExportButton />
</Page>

@* 正确：拆分为多个职责清晰的组件 *@
<Page>
    <Section Title="表单">
        <Form />
    </Section>
    <Section Title="数据">
        <DataTable />
        <Chart />
        <ExportButton />
    </Section>
</Page>

原则 8.2：状态提升

@* 状态提升到共同父组件 *@
<Parent>
    <ChildA Value="@sharedValue" ValueChanged="@OnValueChanged" />
    <ChildB Value="@sharedValue" />
</Parent>

@code {
    private string? sharedValue;

    private void OnValueChanged(string newValue)
    {
        sharedValue = newValue;
    }
}

8.3 性能优化清单

// 1. 启用 AOT 编译（WASM 模式）
// <PropertyGroup>
//   <RunAOTCompilation>true</RunAOTCompilation>
// </PropertyGroup>

// 2. 启用裁剪
// <PropertyGroup>
//   <PublishTrimmed>true</PublishTrimmed>
//   <TrimMode>full</TrimMode>
// </PropertyGroup>

// 3. 懒加载程序集
// <Router AppAssembly="..." PreferExactMatches="true">
//   <Found Context="routeData">
//     <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
//     <FocusOnNavigate RouteData="@routeData" Selector="h1" />
//   </Found>
// </Router>

// 4. 使用 WebAssembly 预渲染
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents(prerender: true);

8.4 错误处理与日志

// Program.cs - 全局异常处理
builder.Services.AddLogging(logging =>
{
    logging.AddConfiguration(builder.Configuration.GetSection("Logging"));
    logging.AddConsole();
    logging.AddDebug();
    logging.AddApplicationInsights();
});

// 组件级错误边界
// App.razor
// <ErrorBoundary>
//     <ChildContent>
//         <Router>...</Router>
//     </ChildContent>
//     <ErrorContent Context="ex">
//         <p>发生错误: @ex.Message</p>
//     </ErrorContent>
// </ErrorBoundary>

// 全局错误处理中间件
public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public ValueTask TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "全局异常捕获");

        httpContext.Response.StatusCode = 500;
        return ValueTask.CompletedTask;
    }
}

8.5 测试策略

// 组件单元测试（使用 bUnit）
using Bunit;
using Xunit;

public class CounterTests : TestContext
{
    [Fact]
    public void Counter_Increments_WhenButtonClicked()
    {
        // Arrange：渲染组件
        var cut = RenderComponent<Counter>(parameters => parameters
            .Add(p => p.Step, 5));

        // Assert：初始状态
        cut.Find("p").TextContent.Should().Contain("0");

        // Act：点击按钮
        cut.Find("button").Click();

        // Assert：状态更新
        cut.Find("p").TextContent.Should().Contain("5");
    }

    [Fact]
    public void Counter_RendersCorrectly_WithCustomStep()
    {
        var cut = RenderComponent<Counter>(parameters => parameters
            .Add(p => p.Step, 10));

        // 验证渲染输出
        cut.Markup.Should().Contain("点击加 10");
    }
}

// 模拟服务测试
public class ProductListTests : TestContext
{
    [Fact]
    public void ProductList_DisplaysProducts_WhenLoaded()
    {
        // Arrange：模拟服务
        var mockService = new Mock<IProductService>();
        mockService.Setup(s => s.GetProductsAsync())
            .ReturnsAsync(new List<Product>
            {
                new() { Name = "测试商品", Price = 100 }
            });

        Services.AddSingleton(mockService.Object);

        // Act：渲染组件
        var cut = RenderComponent<ProductList>();

        // Assert：验证显示
        cut.WaitForAssertion(() =>
        {
            cut.Markup.Should().Contain("测试商品");
            cut.Markup.Should().Contain("100");
        });
    }
}

8.6 端到端测试

// 使用 Playwright 进行 E2E 测试
using Microsoft.Playwright;
using Xunit;

public class BlazorE2ETests
{
    [Fact]
    public async Task UserCanLogin_AndSeeProducts()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Chromium.LaunchAsync();
        var page = await browser.NewPageAsync();

        // 导航到登录页
        await page.GotoAsync("http://localhost:5000/login");

        // 填写表单
        await page.FillAsync("input[placeholder='用户名']", "admin");
        await page.FillAsync("input[placeholder='密码']", "password");

        // 点击登录
        await page.ClickAsync("button[type='submit']");

        // 等待跳转
        await page.WaitForURLAsync("**/");

        // 验证显示
        await page.WaitForSelectorAsync("text=欢迎");
    }
}

9. 案例研究

9.1 案例一：企业管理后台（Blazor Server）

场景描述：一家中型企业需要构建内部管理系统，包含员工管理、审批流程、报表导出等功能。用户约 200 人，主要在内网使用。

技术选型决策：

核心架构：

// Program.cs - 企业应用配置
var builder = WebApplication.CreateBuilder(args);

// 添加服务
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// 数据库
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// 认证
builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.LoginPath = "/login";
        options.AccessDeniedPath = "/access-denied";
    });

// 授权策略
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireAdmin", policy => policy.RequireRole("Admin"));
    options.AddPolicy("RequireHR", policy => policy.RequireRole("HR", "Admin"));
});

// 业务服务
builder.Services.AddScoped<IEmployeeService, EmployeeService>();
builder.Services.AddScoped<IApprovalService, ApprovalService>();
builder.Services.AddScoped<IExportService, ExcelExportService>();

// 全局状态
builder.Services.AddScoped<AppState>();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();

app.Run();

性能优化实践：

@* EmployeeList.razor - 大数据列表优化 *@
@page "/employees"
@inject IEmployeeService EmployeeService
@attribute [Authorize(Policy = "RequireHR")]

<PageTitle>员工管理</PageTitle>

<h1>员工管理</h1>

<div class="toolbar">
    <InputText @bind-Value="searchKeyword" placeholder="搜索..." />
    <button @onclick="Search">搜索</button>
    <button @onclick="Export">导出 Excel</button>
</div>

@* 虚拟化列表：避免渲染全部数据 *@
<Virtualize ItemsProvider="@LoadEmployees" Context="emp" OverscanCount="20">
    <ItemContent>
        <div class="employee-row">
            <span>@emp.Name</span>
            <span>@emp.Department</span>
            <span>@emp.Position</span>
            <button @onclick="() => Edit(emp)">编辑</button>
        </div>
    </ItemContent>
</Virtualize>

@code {
    private string searchKeyword = string.Empty;

    // 异步数据提供者
    private async ValueTask<ItemsProviderResult<Employee>> LoadEmployees(
        ItemsProviderRequest request)
    {
        var result = await EmployeeService.SearchAsync(
            searchKeyword, request.StartIndex, request.Count);

        return new ItemsProviderResult<Employee>(result.Items, result.TotalCount);
    }

    private async Task Search()
    {
        // 触发虚拟化重新加载
        StateHasChanged();
    }

    private async Task Export()
    {
        // 调用服务端导出
        var bytes = await EmployeeService.ExportToExcelAsync(searchKeyword);
        // 触发下载
    }

    private void Edit(Employee emp) { /* ... */ }
}

9.2 案例二：实时协作应用（Blazor Server + SignalR）

场景描述：在线协作白板，多人实时编辑，需要低延迟通信。

// WhiteboardHub.cs - SignalR Hub
public class WhiteboardHub : Hub
{
    private readonly ICollaborationService _collab;

    public WhiteboardHub(ICollaborationService collab)
    {
        _collab = collab;
    }

    public async Task JoinBoard(string boardId)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, boardId);
        var state = _collab.GetBoardState(boardId);
        await Clients.Caller.SendAsync("BoardState", state);
    }

    public async Task DrawStroke(string boardId, Stroke stroke)
    {
        // 广播给组内其他用户
        await Clients.OthersInGroup(boardId).SendAsync("StrokeReceived", stroke);
        _collab.AddStroke(boardId, stroke);
    }

    public async Task ClearBoard(string boardId)
    {
        _collab.ClearBoard(boardId);
        await Clients.Group(boardId).SendAsync("BoardCleared");
    }
}

@* Whiteboard.razor - 协作白板组件 *@
@page "/whiteboard/{BoardId}"
@inject IJSRuntime JS
@implements IAsyncDisposable

<div id="canvas-container" @ref="canvasContainer"
     @onpointerdown="StartDrawing"
     @onpointermove="Draw"
     @onpointerup="StopDrawing">
</div>

@code {
    [Parameter] public string BoardId { get; set; } = string.Empty;

    private ElementReference canvasContainer;
    private IJSObjectReference? _canvasModule;
    private bool _isDrawing = false;
    private Stroke? _currentStroke;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            _canvasModule = await JS.InvokeAsync<IJSObjectReference>(
                "import", "./js/whiteboard.js");

            // 初始化 Hub 连接
            await _canvasModule.InvokeVoidAsync("initHub", BoardId);
            _canvasModule.InvokeVoidAsync("onStrokeReceived", DotNet.Create(
                this, nameof(OnRemoteStroke)));
        }
    }

    private async Task StartDrawing(PointerEventArgs e)
    {
        _isDrawing = true;
        _currentStroke = new Stroke();
        _currentStroke.Points.Add(new Point(e.ClientX, e.ClientY));
    }

    private async Task Draw(PointerEventArgs e)
    {
        if (!_isDrawing || _currentStroke is null) return;

        _currentStroke.Points.Add(new Point(e.ClientX, e.ClientY));
        await _canvasModule!.InvokeVoidAsync("drawSegment",
            _currentStroke.Points[^2], _currentStroke.Points[^1]);
    }

    private async Task StopDrawing()
    {
        if (!_isDrawing || _currentStroke is null) return;

        _isDrawing = false;
        // 发送到 Hub
        await _canvasModule!.InvokeVoidAsync("sendStroke", BoardId, _currentStroke);
        _currentStroke = null;
    }

    [JSInvokable]
    public async Task OnRemoteStroke(Stroke stroke)
    {
        // 渲染远程用户的笔画
        await _canvasModule!.InvokeVoidAsync("renderStroke", stroke);
    }

    public async ValueTask DisposeAsync()
    {
        if (_canvasModule is not null)
            await _canvasModule.DisposeAsync();
    }
}

public record Point(double X, double Y);
public class Stroke { public List<Point> Points { get; } = new(); }

9.3 案例三：PWA 离线应用（Blazor WebAssembly）

场景描述：现场作业人员使用的离线巡检应用，需要离线数据存储与同步。

// wwwroot/manifest.json
{
  "name": "巡检系统",
  "short_name": "巡检",
  "description": "离线巡检应用",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1976d2",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}