用途:在 Blazor 中调用 API、把数据加载进组件并处理异步生命周期,适用于从后端获取数据、向 API 提交数据等场景。
主要能力与用法:先读 AGENTS.md,确认交互模式与范围。静态 SSR 在服务端注入服务或 DbContext,并用 [StreamRendering] 改善加载体验;Server 模式服务端注入,配合 ??= 与 [PersistentState] 防止预渲染重复请求;WebAssembly 仅用浏览器端 HttpClient,不能直连服务端;Auto 模式服务端与浏览器均运行,一律走 API。
调用外部 API 需注册 HttpClient(命名客户端需 Microsoft.Extensions.Http NuGet),WebAssembly/Auto 且启用预渲染时,需在服务端与 .Client 的 Program.cs 中都注册。组件用 OnInitializedAsync 加载数据,加载中显示占位内容;不需要在每个组件写错误处理,可在布局或父级用 <ErrorBoundary> 统一捕获非取消异常。
取消有特殊性:ComponentBase 会静默吞掉所有 OperationCanceledException,ErrorBoundary 看不到,自取消无需处理,外部超时会导致组件停在加载态;仅在需要重试或超时专用提示时才加 catch,并用 when (!cancellationToken.IsCancellationRequested) 区分外部取消。规则:不要显示 exception.Message(可能含 PII 或内部信息),用固定友好文案;通过 ILogger 记录真实异常;服务必须接受 CancellationToken。
当数据依赖会变化的路由或查询参数时,用 OnParametersSetAsync 加跟踪值守卫避免无关重载;先取消旧的 CancellationTokenSource,await 前在本地捕获 token,后续加载不清空已有数据,只叠加 isLoading 提示,并实现 IAsyncDisposable 在离开时取消。
提交数据用 PostAsJsonAsync、PutAsJsonAsync、DeleteAsync 并调用 EnsureSuccessStatusCode;保存期间禁用提交按钮防止重复请求。Auto 或带预渲染的 WebAssembly 可用抽象基类区分服务端数据库访问与客户端 API 调用。避免:在构造函数中调用 API、数据不随参数变化却用 OnParametersSetAsync、在 WebAssembly/Auto 中注入 DbContext、用 HttpClient 调用自家服务端、展示异常消息、捕获自取消异常。
限制:本技能面向 .NET/Blazor 项目,要求按交互模式选择数据访问方式;其他具体配置细节暂未提供。