Emiliano Montesdeoca

Blazor 从零开始：第 3 章 —— 可扩展的组件设计

Mon, 01 Jun 2026 00:00:00 +0000

欢迎来到 Blazor 从零开始 第 3 章。如果你还没看第 2 章，建议先看完并准备好基础项目。

第 2 章我们让应用跑起来了；第 3 章我们要让它 更易维护。

当每个页面都变成巨大 .razor 文件时，Blazor 项目会很快失控。组件化可以避免这一点：更一致、更可复用、边界更清晰。

Blazor 组件到底是什么

组件本质上是一个 .razor 文件，它可以：

渲染标记
保存本地状态
通过参数接收输入
向父组件发出事件
渲染子内容

运行时，Blazor 会把每个组件当作一个小型状态机。状态变化后，框架会重新渲染并应用 DOM 差异。

所以你的目标是：输入清晰、行为可预测。

第一步：从职责单一的组件开始

创建 Components/Common/SectionHeader.razor：

<header class="section-header">
 <h2>@Title</h2>
 @if (!string.IsNullOrWhiteSpace(Subtitle))
 {
 <p>@Subtitle</p>
 }
</header>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public string? Subtitle { get; set; }
}

在 Components/Pages/Home.razor 中使用：

@page "/"

<PageTitle>Blazor 从零开始</PageTitle>

<SectionHeader
 Title="Blazor 从零开始"
 Subtitle="第 3 章聚焦组件设计。" />

这个例子很小，但核心思想很关键：只看参数就应该能理解组件用途。

第二步：用参数显式表达行为

我们做一个可复用按钮组件。

Components/Common/AppButton.razor：

<button class="app-button @VariantCssClass" @onclick="OnClick">
 @Text
</button>

@code {
 [Parameter] public string Text { get; set; } = "Button";
 [Parameter] public string Variant { get; set; } = "primary";
 [Parameter] public EventCallback OnClick { get; set; }

 private string VariantCssClass => Variant.ToLowerInvariant() switch
 {
 "secondary" => "app-button--secondary",
 "danger" => "app-button--danger",
 _ => "app-button--primary"
 };
}

用法：

@code {
 private int _savedCount;

 private void Save()
 {
 _savedCount++;
 }
}

<AppButton Text="Save" Variant="primary" OnClick="Save" />
<p>已保存 @_savedCount 次。</p>

重点在于“契约设计”：

参数要少且清晰
命名要显式，避免“魔法行为”
默认值要安全

第三步：用 `RenderFragment` 做布局组合

RenderFragment 允许父组件把一段 UI 传给子组件。

创建 Components/Common/Card.razor：

<article class="card">
 <header class="card__header">@Title</header>
 <section class="card__body">
 @ChildContent
 </section>
</article>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public RenderFragment? ChildContent { get; set; }
}

用法：

<Card Title="Roadmap">
 <ul>
 <li>组件</li>
 <li>Data binding</li>
 <li>Routing</li>
 </ul>
</Card>

这个模式可以在不重复外层包装标记的前提下，保持页面结构一致。

第四步：优先组合，而不是巨型页面

当页面持续变大时，按职责拆分：

ProfileSummary：顶部信息块
ProfileStats：指标展示
ProfileActivityList：最近活动

这样页面就变成“编排层”，而不是塞满实现细节的地方。

第五步：保持标记与逻辑的平衡

简单组件使用内联 @code 就够了。

复杂组件建议使用 code-behind：

UserCard.razor
UserCard.razor.cs

这样既能保持标记可读，也能让 C# 逻辑更清晰。

第六步：实用的目录结构

一个较容易扩展的结构：

Components/Pages/ -> 可路由页面
Components/Layout/ -> 应用壳层与导航
Components/Common/ -> 通用共享组件
Components/Features/<FeatureName>/ -> 功能域组件

Blazor 初期常见问题

参数过多，而不是抽出专用模型
把业务规则直接写进页面组件
做出一个数百行的“上帝组件”
重复粘贴标记，而不是提取可复用组件

第 4 章我们将进入 数据绑定与事件：@bind、事件处理、双向绑定的权衡，以及如何让状态保持可预测。

从零开始 Blazor：第 2 章 — 你的第一个 Blazor 应用

Thu, 14 May 2026 00:00:00 +0000

欢迎来到 从零开始 Blazor 第 2 章。如果你还没看第 1 章，建议先读一下。

这一章我们会创建一个新的 Blazor 应用，在本地跑起来，并理解核心文件各自负责什么。

第 1 步：创建项目

在终端中执行：

dotnet new blazor -o BlazorFromScratch
cd BlazorFromScratch

这会创建一个采用默认结构的 .NET 9 Blazor Web App。

如果工具让你选择交互模型，先使用 Interactive Server。

第 2 步：本地运行

启动应用：

dotnet watch

然后打开终端里显示的 URL（通常是 https://localhost:5xxx）。你应该能看到默认的 Home、Counter、Weather 页面。

如果能正常打开，你的开发环境就准备好了。

第 3 步：理解项目结构

先掌握这些关键文件和目录：

Program.cs —— 注册服务并配置 HTTP 管道。
Components/App.razor —— 应用根组件。
Components/Routes.razor —— 页面路由映射。
Components/Pages/ —— 可路由页面（如 Home、Counter）。
Components/Layout/ —— 共享布局（MainLayout.razor、导航菜单）。
wwwroot/ —— 静态资源（CSS、图片、favicon）。
appsettings.json —— 配置值。

现在不需要把每个文件都吃透。这个阶段先知道 UI 在哪里、启动配置在哪里就够了。

第 4 步：做第一次修改

打开 Components/Pages/Home.razor，替换为：

@page "/"

<PageTitle>从零开始 Blazor</PageTitle>

<h1>从零开始 Blazor</h1>
<p>第 2 章内容已在本地运行。</p>

保存并刷新浏览器。使用 dotnet watch 时，修改会立即生效。

这个小改动验证了完整流程：编辑 -> 构建 -> 渲染。

第 5 步：读一遍 Program.cs

不用死记硬背，但请认识这几行：

AddRazorComponents()：启用 Razor 组件。
AddInteractiveServerComponents()：启用服务端交互组件。
MapRazorComponents<App>()：将根组件映射到端点。

这些代码说明了应用如何启动，以及启用了哪些渲染能力。

常见问题

如果运行失败，通常是以下原因：

SDK 版本过旧：执行 dotnet --version，确认是 .NET 9。
HTTPS 证书问题：执行 dotnet dev-certs https --trust。
端口冲突：停止旧的 dotnet 进程后再运行。

第 3 章我们将深入讲组件：参数、组合方式，以及如何组织可复用 UI。

Blazor 从零开始：第1章 — 什么是 Blazor？

Fri, 08 May 2026 00:00:00 +0000

欢迎来到从零开始学 Blazor的第1章。如果你错过了介绍本系列目的和受众的介绍文章，请先阅读那篇——很短。

在这一章中，我们将回答一个根本性的问题：Blazor 是什么？ 这听起来很简单，但答案有几个层面——尤其是因为多年来"Blazor"已经有了略微不同的含义。读完这篇文章，你将了解 Blazor 是什么、它如何融入 .NET 生态系统、有哪些不同的渲染模型，以及为什么你可能会选择它而不是 JavaScript 框架——或者不会。

简短的历史

Blazor 大约在 2017 年作为 Microsoft 的 Steve Sanderson 的实验性项目开始。这个想法很大胆：使用 WebAssembly 在浏览器中运行 C#，完全消除对 JavaScript 的需求。这是一个概念验证，名称是 Blazer 和 Razor 的刻意融合——Razor 是 Blazor 最终将在其上构建的模板引擎。

这个实验产生了足够的热情，让 Microsoft 认真对待。Blazor 于 2019 年 9 月作为 ASP.NET Core 3.0 的一部分发布，最初是 Blazor Server——一种在服务器上运行 C# 代码并使用实时 SignalR 连接将 UI 更新推送到浏览器的模型。Blazor WebAssembly 作为 ASP.NET Core 3.1 的一部分于 2020 年 5 月推出，为框架带来了真正的客户端执行。

.NET 6 和 7 改善了开发者体验。然后，2023 年 11 月发布的 .NET 8 从根本上重新思考了渲染模型，使用 Microsoft 称之为全栈 Web UI 的方式。静态服务器端渲染、流式渲染、交互式服务器、交互式 WebAssembly 和新的 Auto 模式都在一个项目的同一屋檐下共存。.NET 9 在此基础上构建并消除了粗糙之处。

这就是我们今天所处的位置。

Blazor 究竟是什么

从本质上说，Blazor 是一个面向 .NET 的基于组件的 UI 框架。你使用组件构建 UI——可以保存状态、响应事件并组合成更大结构的 C# 和 HTML 标记的自包含单元。如果你使用过 React 或 Vue，这个思维模型会感觉熟悉。关键区别在于，你写的是 C# 而不是 JavaScript。

Blazor 中的组件写在 .razor 文件中。.razor 文件使用 Razor 语法混合 HTML 标记和 C# 代码，你可能已经从 ASP.NET MVC 视图中了解过这种语法。一个简单的组件看起来像这样：

@page "/counter"

<h1>计数器</h1>
<p>当前计数: @currentCount</p>
<button @onclick="IncrementCount">点击我</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

没有 JavaScript。@onclick 指令将按钮点击绑定到 C# 方法。@currentCount 表达式渲染当前值。当状态改变时，Blazor 会确定需要更新 DOM 中的哪些内容。

这就是核心。其他所有内容——路由、依赖注入、表单、HTTP 调用——都建立在这个组件模型之上。

渲染模型

这里存在很多混淆，所以让我们精确一些。今天的"Blazor"指的是一系列渲染模式，而不是单一的部署模型。理解差异很重要，因为它影响性能、基础设施要求以及你的组件可以和不能做什么。

静态 SSR

最简单的模式。你的 Razor 组件在服务器上渲染为 HTML，该 HTML 被发送到浏览器。默认情况下没有持久连接、没有 WebAssembly、没有客户端交互性。这本质上是 Razor Pages 所做的，但使用组件模型。

用于内容丰富的页面、着陆页、任何不需要实时交互性的内容。

交互式服务器

组件代码在服务器上运行。浏览器和服务器之间建立 SignalR WebSocket 连接。当你点击按钮或在输入框中键入时，事件通过 WebSocket 传输到服务器，C# 代码执行，计算差异，然后 DOM 更新被发送回浏览器。

优势： 完全访问服务器资源（数据库、文件系统、密钥）。快速初始加载。下载量小。在不支持 WebAssembly 的浏览器中工作。

劣势： 每次用户交互都需要服务器往返，增加延迟。服务器资源随活跃连接数扩展。连接断开时应用会降级。

用于业务线应用、内部工具、服务器端数据访问比离线功能更重要的应用。

交互式 WebAssembly

.NET 运行时下载到浏览器，你的应用完全在客户端运行。初始下载后，应用完全离线工作，每次交互都是即时的——没有 UI 逻辑的服务器往返。

优势： 真正的客户端执行。离线工作。应用加载后服务器负载降低。

劣势： 更大的初始下载量（.NET 运行时 + 你的应用）。更慢的首次加载。需要 API 来访问服务器端数据。

用于具有离线功能的应用、需要即时响应性的工具、UI 不需要服务器处理的场景。

Auto 模式

在 .NET 8 中引入。应用以交互式服务器模式启动（快速初始加载，无需等待 WebAssembly 下载）。一旦 WebAssembly 文件在后台下载完成，后续访问会自动切换到 WebAssembly 模式。

这给你提供了服务器模式的快速首次加载，以及最终 WebAssembly 的完整客户端执行。这是最复杂的理解模型，但对许多应用来说是实用的默认值。

在同一应用中混合模式

在 .NET 8 及更高版本中，你不受限于整个应用的单一渲染模式。营销着陆页可以是静态 SSR；已验证的仪表板可以是交互式服务器；数据可视化小部件可以是交互式 WebAssembly。框架处理过渡。

在本系列中，我们将从交互式服务器开始，因为它最容易启动，具有最直接的思维模型。我们将在进行过程中探索其他模式。

Blazor 与 JavaScript 框架的比较

如果你使用过 React、Angular 或 Vue 进行开发，这可能是你好奇的比较。

相似之处是真实的。 Blazor 的组件模型刻意类似于 React。你有 props（Blazor 中的参数）、本地状态（@code 块中的字段）、生命周期钩子，以及相同的单向数据流/事件向上的通信模式。如果你了解 React，几小时内就会感到得心应手。

关键区别是语言。 在 Blazor 中你写 C#。业务逻辑、验证规则和数据模型都可以在 Blazor 前端和 ASP.NET Core 后端之间共享。当你已经用 C# 写好 User 类时，不再需要在 TypeScript 中重复。

生态系统差距是真实的，但正在缩小。 npm 生态系统庞大。UI 组件的 NuGet 生态系统较小，但已经大幅增长。对于特定的图表库或拖放小部件，JavaScript 仍然有更多选择。但对于大多数业务线应用，.NET 世界中可用的内容已经绰绰有余。

JavaScript 互操作在需要时存在。 Blazor 允许你从 C# 调用 JavaScript，从 JavaScript 调用 C#。对于没有 .NET 包装器的浏览器 API，或者当你想使用现有 JS 库时，互操作是可用的。它增加了一层，但并不痛苦。

诚实的答案： 如果你的团队完全是 JavaScript 开发者，正在构建一个 SEO、性能和 npm 生态系统至关重要的公开产品，请坚持使用 JavaScript。如果你的团队是 .NET 开发者，如果你正在构建内部或业务线应用，或者如果前后端之间的代码共享对你很重要，Blazor 是一个令人信服的选择。

跟进所需的内容

本系列其余部分你需要：

.NET 9 SDK — 从 dot.net 下载
IDE — Visual Studio 2022（社区版免费）、带有 C# Dev Kit 扩展的 VS Code，或 JetBrains Rider
基本的 C# 知识——类、属性、接口、async/await

就这些。不需要 Node、npm 或 webpack。

在第2章中，我们将搭建你的第一个 Blazor 应用，浏览项目结构，并确保你能在本地运行它。最后你将拥有一个工作中的应用和对每个文件作用的清晰认识。

在那里见。

Blazor 从零开始：全新系列

Mon, 04 May 2026 00:00:00 +0000

我写 Blazor 相关内容已经有一段时间了——组件生命周期、隔离 CSS、交互模型、身份验证。这些文章各自有其价值，但我一直觉得缺少一个基础。它们都默认你已经知道 Blazor 是什么、为什么存在，以及它如何融入更广泛的 .NET 生态系统。并非所有人都了解这些，这完全没问题。

所以我要开始一件新事：Blazor 从零开始。一个正经的系列，从基础构建，面向那些真正想理解自己在做什么的开发者——而不是一直复制粘贴直到能运行为止。

这个系列适合谁

如果你符合以下情况，这个系列就是为你准备的：

你是 .NET 开发者，听说过 Blazor，但从未找到合适的时机或起点深入研究。
你尝试过 Blazor，让它运行起来了，但感觉在猜测为什么事情会这样运作。
你来自 JavaScript/React/Angular 的世界，想了解微软对现代前端的答案是什么样的。
你想要一个完整一致的资源，而不是零散的文档和博客文章。

你不需要是高级开发者。但你需要对 C# 基础感到自在——类、接口、async/await。如果你能用 ASP.NET Core 写一个简单的 CRUD API，那你已经准备好了。

我们将涵盖的内容

以下是我计划的大致路线图。部分主题将根据需要扩展为多篇文章：

什么是 Blazor？ ——托管模型、历史背景、与传统 Web 开发的比较
你的第一个 Blazor 应用 ——脚手架、项目结构、本地运行
组件 ——每个 Blazor UI 的基本构建块
数据绑定与事件 ——让你的 UI 具有响应性
组件通信 ——参数、EventCallbacks、级联值
路由与导航 ——Blazor 如何处理 URL 和页面切换
依赖注入 ——服务、范围与 Blazor 中的 DI 容器
表单与验证 ——EditForm、DataAnnotations、自定义验证器
HTTP 与外部数据 ——在 Blazor 应用中调用 API
身份验证与授权 ——以正确方式保护你的应用
JavaScript 互操作 ——当你需要直接访问浏览器时
性能与优化 ——虚拟化、懒加载、渲染策略
Blazor 组件测试 ——bUnit 与一个扎实的测试长什么样
部署 ——发布到 Azure、IIS 和静态托管平台

这个列表会随时间演进。有些主题会拆分成多篇文章，有些可能会合并。随着系列推进，我会持续更新这篇文章，并在每篇文章发布时添加链接。

为什么要做系列，为什么是现在

Blazor 已经成熟了很多。随着 .NET 8 和 9，渲染模型经历了重大改造——静态 SSR、流式渲染、交互式 Server、交互式 WebAssembly 和 Auto 模式现在都在同一个框架下共存。这是一个真正有趣且能力强大的框架，但复杂度的提升让入门体验变得令人困惑。

我想构建一个能从你所在之处出发、系统地引导你走完全程的资源。不是官方文档的替代——官方文档很好，你应该去读——而是一个解释是什么背后的为什么的伙伴。

如何跟进系列

系列中的每篇文章都足够独立，可以单独阅读，但它们也会相互依托。如果你从头开始，我建议按顺序阅读。如果你是为了填补某个具体空白而来，那也完全没问题——我会在重要的地方链接前置文章。

每篇文章的代码都会发布在 GitHub 上。随着系列推进，我会陆续分享链接。

下篇见。

C# 联合类型：受歧视联合终于来了

Wed, 01 Apr 2026 00:00:00 +0000

如果您已经编写 C# 相当长的时间，那么在尝试对可能是“多种事物之一”的事物进行建模时，您很可能会遇到困难。也许您需要一个方法来返回成功值或错误。也许您正在构建一个处理信用卡、银行转账和数字钱包的支付系统——每个系统都具有完全不同的数据。或者也许您只是看着 F# 或 Rust 并想，“为什么我不能在 C# 中使用它？”

等待即将结束。 受歧视的工会即将进入 C#。

这一直是多年来最受欢迎的语言功能之一，社区讨论可以追溯到 2017 年或更早。 C# 语言设计团队一直致力于一项提案，该提案引入了 union 关键字，用于定义具有详尽模式匹配的封闭类型层次结构。在这篇文章中，我想向您介绍什么是受歧视的联合，为什么它们如此重要，到目前为止我们如何伪造它们，以及提议的语法实际上是什么样子 - 每个都有真实的代码示例。

在我们深入讨论之前，请注意：在撰写本文时，联合类型功能仍处于提案和预览阶段。我在此描述的语法和行为基于最新公开的设计文档以及 C# 语言设计团队的讨论。在最终版本发布之前情况可能会发生变化。我会明确哪些内容已被确认，哪些内容仍在讨论中。

什么是受歧视工会？

从本质上讲，可区分联合（有时称为“标记联合”或“总和类型”）是一种可以保存一组固定可能值之一的类型，其中每个变体可以携带不同的数据。 “可区分”部分意味着运行时始终知道它是哪个变体 - 有一个标签可以识别它。

把它想象成一个 enum，但每个成员都可以携带自己的数据有效负载。

如果您使用过其他语言，您可能以前见过这个概念：

F# 从第一天起就存在受歧视的工会：

type Shape =
 | Circle of radius: float
 | Rectangle of width: float * height: float
 | Triangle of base: float * height: float

Rust 使用 enum 实现相同的想法：

enum Shape {
 Circle { radius: f64 },
 Rectangle { width: f64, height: f64 },
 Triangle { base: f64, height: f64 },
}

TypeScript 通过标记联合实现了类似的效果：

type Shape =
 | { kind: "circle"; radius: number }
 | { kind: "rectangle"; width: number; height: number }
 | { kind: "triangle"; base: number; height: number };

在所有这些情况下，编译器知道每种可能的变体，并且可以强制您处理所有这些变体。这就是超能力：详尽检查。如果您添加新的变体，编译器会在您忘记处理它的任何地方告诉您。

C# 从未有过一流的方式来表达这一点。到目前为止。

今天我们如何模拟工会

多年来，C# 社区提出了多种解决方法，每种方法都有自己的优缺点。让我来介绍一下最常见的方法。

具有继承性的抽象记录

现代 C# 中最惯用的解决方法是使用具有密封派生类型的抽象记录：

public abstract record Shape
{
 public sealed record Circle(double Radius) : Shape;
 public sealed record Rectangle(double Width, double Height) : Shape;
 public sealed record Triangle(double Base, double Height) : Shape;

 private Shape() { } // Prevent external inheritance
}

这相当有效。您可以获得不变性、值相等，并且可以使用模式匹配：

double Area(Shape shape) => shape switch
{
 Shape.Circle c => Math.PI * c.Radius * c.Radius,
 Shape.Rectangle r => r.Width * r.Height,
 Shape.Triangle t => 0.5 * t.Base * t.Height,
 _ => throw new InvalidOperationException("Unknown shape")
};
```但也有明显的缺点。编译器不知道层次结构已关闭，因此您始终需要 `_` 丢弃臂，否则您会收到警告。如果你添加一个新的变体，编译器不会告诉你所有你忘记处理它的地方——丢弃会默默地吞掉它。这完全违背了目的。

### OneOf 图书馆

另一种流行的方法是 [OneOf](https://github.com/mcintyre321/OneOf) NuGet 包：

```csharp
public OneOf<Success<Order>, NotFound, ValidationError> ProcessOrder(OrderRequest request)
{
 // ...
}

// Usage
var result = ProcessOrder(request);
result.Switch(
 success => Console.WriteLine($"Order {success.Value.Id} processed"),
 notFound => Console.WriteLine("Order not found"),
 error => Console.WriteLine($"Validation failed: {error.Message}")
);

OneOf 通过其泛型类型参数在编译时提供详尽的检查，这非常棒。但它依赖于位置匹配（第一类型、第二类型等），通用签名很快变得笨拙，并且它不与语言的模式匹配集成。这是一个聪明的黑客，但它仍然是一个黑客。

手动枚举+数据模式

一些开发人员采用使用枚举标记和数据容器的经典路线：

public enum PaymentType { CreditCard, BankTransfer, DigitalWallet }

public class Payment
{
 public PaymentType Type { get; init; }
 public CreditCardInfo? CreditCard { get; init; }
 public BankTransferInfo? BankTransfer { get; init; }
 public DigitalWalletInfo? DigitalWallet { get; init; }
}

这是脆弱的。没有什么可以阻止您将 Type 设置为 CreditCard，但填充 BankTransfer 属性。编译器无法帮助您，最终您会遇到运行时错误和到处都是空检查。这是类型建模的“字符串类型”方法，并且无法扩展。

所有这些方法都有一个基本问题：**它们是在对抗语言而不是使用它。**编译器无法推理封闭的可能性集，因此您失去了可区分联合的最有价值的属性 - 详尽的检查。

C# 提案：`union` 关键字

C# 语言团队的提案引入了一个专用的 union 关键字，该关键字定义一组封闭的命名成员，每个成员可选地携带数据。这是提议的基本语法：

union Shape
{
 Circle(double Radius),
 Rectangle(double Width, double Height),
 Triangle(double Base, double Height)
}

就是这样。干净、简洁、易于阅读。联合内的每个成员都用自己的数据定义一个不同的变体。编译器知道 Shape 只能是这三者之一。

在底层，编译器生成一个密封的类型层次结构 - 类似于您使用抽象记录手工编写的内容，但编译器完全了解类型的封闭性质。这意味着编译器可以强制模式匹配的详尽性，这是主要的好处。

仅限超值会员

工会成员不必携带数据。您可以将数据携带成员与简单值成员混合使用：

union Option<T>
{
 Some(T Value),
 None
}

这是函数式程序员多年来在 C# 中要求的经典 Option/Maybe 类型。 None 不携带任何数据——它只是一个标签。

通用联合

从上面的 Option<T> 示例中可以看出，联合支持泛型。这是一个更复杂的例子：

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

这开辟了一种完整的错误处理风格，不依赖于预期失败情况的异常——这是多年来 Rust 和函数式语言的标准做法。

方法联合

该提案还允许联合拥有方法、计算属性和实现接口，就像任何其他类型一样：```csharp union Shape { Circle(double Radius), Rectangle(double Width, double Height), Triangle(double Base, double Height);

public double Area => this switch
{
Circle(var r) => Math.PI * r * r,
Rectangle(var w, var h) => w * h,
Triangle(var b, var h) => 0.5 * b * h
};
public double Perimeter => this switch
{
Circle(var r) => 2 * Math.PI * r,
Rectangle(var w, var h) => 2 * (w + h),
Triangle(var b, var h) => b + h + Math.Sqrt(b * b + h * h)
};

}


请注意 `Area` 和 `Perimeter` 内的 `switch` 表达式不需要默认臂。编译器知道联合是详尽的——只有三种变体，并且所有三种变体都被处理。如果稍后添加第四个变体，编译器将标记每个不处理它的 `switch`。

## 模式匹配集成

自版本 7.0 以来，模式匹配在 C# 中不断发展，联合类型被设计为该系统的一等公民。

### 详尽的 Switch 表达式

最有影响力的功能是详尽的开关检查。通过联合，编译器**知道**所有可能的情况：

```csharp
string Describe(Shape shape) => shape switch
{
 Circle(var r) => $"A circle with radius {r}",
 Rectangle(var w, var h) => $"A {w}x{h} rectangle",
 Triangle(var b, var h) => $"A triangle with base {b} and height {h}"
};

无丢弃臂。没有_ => throw new NotImplementedException()。如果您忘记了大小写，编译器会发出错误，而不是警告。这是安全性的根本性改进。

嵌套模式匹配

联合自然地与嵌套模式组合：

union Expr
{
 Literal(double Value),
 Add(Expr Left, Expr Right),
 Multiply(Expr Left, Expr Right),
 Negate(Expr Inner)
}

double Evaluate(Expr expr) => expr switch
{
 Literal(var v) => v,
 Add(var left, var right) => Evaluate(left) + Evaluate(right),
 Multiply(var left, var right) => Evaluate(left) * Evaluate(right),
 Negate(var inner) => -Evaluate(inner)
};

这种递归数据结构在编译器、解释器、规则引擎和数学建模中极为常见。如今，在 C# 中，您需要深层的类层次结构和访问者模式。通过联合，代码变得更加简单。

保护条款

正如您所期望的，与联合的模式匹配支持 when 保护：

string Classify(Shape shape) => shape switch
{
 Circle(var r) when r > 100 => "Large circle",
 Circle(var r) when r > 10 => "Medium circle",
 Circle(_) => "Small circle",
 Rectangle(var w, var h) when w == h => "Square",
 Rectangle _ => "Rectangle",
 Triangle _ => "Triangle"
};

实际例子

让我来看看一些现实场景，其中联合类型极大地改进了代码。

结果模式：替换预期错误的异常

现代应用程序开发中最常见的模式之一是表示在不使用控制流异常的情况下可以成功或失败的操作。异常应该是异常的——比如网络故障或内存不足的情况。验证错误或“未找到”结果是预期结果，而不是异常。

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

union OrderError
{
 NotFound(Guid OrderId),
 InsufficientStock(string ProductId, int Requested, int Available),
 PaymentDeclined(string Reason),
 ValidationFailed(IReadOnlyList<string> Errors)
}

Result<Order, OrderError> ProcessOrder(OrderRequest request)
{
 if (!Validate(request, out var errors))
 return new ValidationFailed(errors);

 var product = catalog.Find(request.ProductId);
 if (product is null)
 return new NotFound(request.OrderId);

 if (product.Stock < request.Quantity)
 return new InsufficientStock(request.ProductId, request.Quantity, product.Stock);

 var paymentResult = paymentGateway.Charge(request.Payment);
 if (!paymentResult.Success)
 return new PaymentDeclined(paymentResult.Message);

 var order = CreateOrder(request, product);
 return new Ok(order);
}

然后调用者被迫处理所有可能的结果：

var result = ProcessOrder(request);

var response = result switch
{
 Ok(var order) => Results.Created($"/orders/{order.Id}", order),
 Error(NotFound(var id)) => Results.NotFound($"Order {id} not found"),
 Error(InsufficientStock(var pid, var req, var avail)) =>
 Results.Conflict($"Product {pid}: requested {req}, only {avail} available"),
 Error(PaymentDeclined(var reason)) =>
 Results.UnprocessableEntity($"Payment declined: {reason}"),
 Error(ValidationFailed(var errors)) =>
 Results.BadRequest(new { Errors = errors })
};

没有 try-catch 块，没有被遗忘的异常类型，没有运行时意外。每个故障模式在类型签名中都是可见的，并由编译器强制执行。这是 API 可靠性的巨大改进。

领域建模：支付类型

这是一个现实世界的域建模示例 - 在电子商务系统中处理不同的支付方式：

union PaymentMethod
{
 CreditCard(string CardNumber, string Expiry, string Cvv),
 BankTransfer(string Iban, string Bic),
 DigitalWallet(string Provider, string Token),
 CashOnDelivery
}

decimal CalculateProcessingFee(PaymentMethod method, decimal amount) => method switch
{
 CreditCard _ => amount * 0.029m + 0.30m,
 BankTransfer _ => 1.50m,
 DigitalWallet(provider: "PayPal", _) => amount * 0.034m + 0.35m,
 DigitalWallet _ => amount * 0.025m,
 CashOnDelivery => 4.99m
};

string FormatForReceipt(PaymentMethod method) => method switch
{
 CreditCard(var num, _, _) => $"Credit Card ending in {num[^4..]}",
 BankTransfer(var iban, _) => $"Bank Transfer ({iban[..4]}****)",
 DigitalWallet(var provider, _) => $"Digital Wallet ({provider})",
 CashOnDelivery => "Cash on Delivery"
};

将此与当前方法进行比较，在当前方法中，您将拥有一个接口或抽象类，其中五个不同的实现分布在五个文件中，并且顶部可能带有访问者模式。联合方法将数据定义和操作保持在一起，可读且经过彻底检查。

状态机

状态机在软件中无处不在——订单处理、工作流引擎、连接管理、UI 状态。工会使它们明确且安全：

union ConnectionState
{
 Disconnected,
 Connecting(string Host, int Port, DateTime StartedAt),
 Connected(string Host, int Port, TcpClient Client),
 Reconnecting(string Host, int Port, int Attempt, TimeSpan Delay),
 Failed(string Host, Exception Error)
}

ConnectionState HandleEvent(ConnectionState state, ConnectionEvent evt) => (state, evt) switch
{
 (Disconnected, Connect(var host, var port)) =>
 new Connecting(host, port, DateTime.UtcNow),

 (Connecting(var h, var p, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Connecting(var h, var p, _), ConnectionFailed(var ex)) =>
 new Reconnecting(h, p, Attempt: 1, Delay: TimeSpan.FromSeconds(1)),

 (Reconnecting(var h, var p, var attempt, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(var ex)) when attempt >= 5 =>
 new Failed(h, ex),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(_)) =>
 new Reconnecting(h, p, attempt + 1, TimeSpan.FromSeconds(Math.Pow(2, attempt))),

 (Connected(_, _, var client), Disconnect) =>
 new Disconnected,

 _ => state // Ignore events that don't apply to current state
};

每个状态都准确地携带与该状态相关的数据。当您处于 Connecting 状态时，您不会意外访问 TcpClient，因为该变体上不存在它。类型系统强制执行状态机的不变量。

序列化和互操作注意事项联合类型立即出现的实际问题之一是：如何序列化它们？如果您正在构建 API 或存储数据，则需要 JSON 序列化才能正常工作。

设计团队一直在讨论对联合类型的内置 System.Text.Json 支持。预期的方法涉及使用鉴别器属性进行序列化：

{
 "$type": "Circle",
 "radius": 5.0
}

{
 "$type": "Rectangle",
 "width": 10.0,
 "height": 20.0
}

这与 .NET 7 中通过 JsonDerivedType 属性引入的现有多态序列化支持一致。期望联合体可以开箱即用地使用 System.Text.Json，默认情况下使用变体名称作为类型鉴别器。

对于 Entity Framework Core，可能的方法是使用鉴别器列存储联合值 - 类似于每个层次结构表 (TPH) 继承映射的工作方式。确切的 EF Core 集成仍在设计中，但处理封闭类型层次结构的基础设施已经存在。

值得注意的是，与其他 .NET 语言的互操作应该很顺利，因为联合将在底层编译为标准 IL 类层次结构。使用 C# 联合的 F# 代码会将其视为标准类型层次结构，反之亦然。

如何尝试

截至撰写本文时，联合类型已作为最新 .NET SDK 预览版中的预览功能提供。要试验建议的语法，您需要：

1.安装最新的.NET预览版SDK 2. 在项目文件中启用预览语言版本：

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <LangVersion>preview</LangVersion>
 </PropertyGroup>
</Project>

请记住，预览功能可能会发生变化。在最终版本发布之前，语法、行为和编译器诊断可能会发生显着变化。不要依赖预览语言功能来发布生产代码 - 但绝对要尝试它们并提供反馈。 C# 团队积极监控 csharplang 存储库讨论。

如果您想跟踪提案的进展，需要关注的关键地方是：

用于语言设计讨论的 dotnet/csharplang 存储库
dotnet/roslyn 编译器实现进度存储库
官方公告的 .NET 博客

与现有方法的比较

让我进行一个快速比较，以便您可以了解不同方法的叠加效果：

特色	摘要记录	OneOf<T1,T2>	枚举 + 数据	联合类型
详尽性检查	❌ 否	✅ 是的	❌ 否	✅ 是的
模式匹配	✅ 是的	❌ 有限	❌ 手册	✅ 本地人
编译器强制关闭	❌ 否	✅ 是的	❌ 否	✅ 是的
每个变体的数据	✅ 是的	✅ 是的	⚠️ 脆弱	✅ 是的
可读性	⚠️ 详细	⚠️ 位置	❌ 穷	✅ 优秀
连载	✅ 手册	⚠️ 复杂	✅ 手册	✅ 内置
样板	⚠️ 中等	✅ 低	⚠️高	✅ 最小
没有外部依赖	✅ 是的	❌NuGet	✅ 是的	✅ 是的

这对 .NET 生态系统意味着什么

受歧视工会的引入将波及整个 .NET 生态系统。这是我期望看到的：

库设计将会改进。 当前返回 null 以指示“未找到”或因验证失败引发异常的 API 将能够返回 Result<T, E> 类型。这使得类型签名中的故障模式变得明确——您可以通过查看方法签名来了解可能出现的问题，而不是通过阅读文档或源代码。

**领域建模变得更具表现力。**问题域和代码表示之间的差距急剧缩小。当您的领域专家说“付款可以是信用卡、银行转账或货到付款”时，您可以直接将其建模为联合，而不是将其转换为继承层次结构。

C# 开发人员可以接触到 F# 的想法。 许多 C# 开发人员从远处欣赏 F# 的类型系统，但无法在其组织中采用 F#。联合类型为 C# 带来了 F# 最强大的功能之一，这对整个 .NET 生态系统来说是一个胜利。

**更少的运行时错误。**单独的详尽检查就可以防止整个类别的错误。每次您向联合添加新变体时，编译器都会引导您到达代码库中需要更新的每个位置。不再有被遗忘的 switch 情况，默认分支中不再有 NotImplementedException 仅在生产中出现。

结论

近十年来，受歧视的工会一直位居 C# 社区愿望清单的首位，这是有充分理由的。它们解决了类型系统中的一个根本缺陷——对数据进行建模的能力，这些数据可以是具有编译器强制安全性的“多种事物之一”。

提议的 union 关键字带来了一种干净、简洁的语法，它与 C# 的模式匹配深度集成，与泛型一起使用，支持方法和接口，并支持在编译时而不是运行时捕获错误的详尽检查。

无论您是构建域模型、设计具有显式错误类型的 API、实现状态机，还是只是尝试用更自然的东西替换笨拙的继承层次结构，联合类型都将改变您编写 C# 的方式。

我们为此等待了很长时间。语法很优雅，与现有语言功能的集成经过深思熟虑，整个 .NET 生态系统都会感受到实际影响。

密切关注预览版本，尝试该功能，并向语言设计团队提供反馈。这是其中一项功能，一旦您使用过它，您就会想知道如果没有它您将如何生活。

使用语义内核在 C# 中构建 RAG 系统

Wed, 18 Mar 2026 00:00:00 +0000

简介

如果您尝试使用法学硕士来回答有关您自己的数据（公司文档、产品规格、内部知识库）的问题，您可能会注意到它要么产生幻觉，要么只是说“我没有这方面的信息”。这是因为模型只知道它接受的训练内容。

RAG（检索增强生成）解决了这个问题。您无需在数据上微调模型，而是在查询时检索文档的相关块并将它们作为上下文传递给 LLM。然后，该模型会根据您的实际数据生成答案。

在这篇文章中，我将引导您使用语义内核在 C# 中构建完整的 RAG 管道。

RAG 的工作原理

流程很简单：

摄取：将文档分割成块，为每个块生成嵌入，将它们存储在矢量数据库中
查询：当用户提出问题时，生成查询的嵌入，在向量数据库中搜索相似的块
生成：将检索到的块作为上下文以及用户的问题传递给 LLM

就是这样。神奇之处在于嵌入 - 它们将文本的语义捕获为向量，因此即使确切的单词不匹配，您也可以找到相关内容。

先决条件

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.Extensions.VectorData.Abstractions
dotnet add package Microsoft.SemanticKernel.Connectors.InMemory

对于生产，您可以将内存存储替换为 Azure AI Search、Qdrant、Pinecone 或任何其他支持的矢量数据库。但内存中非常适合学习和原型设计。

设置内核

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
using Microsoft.SemanticKernel.Embeddings;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-3-small",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

var kernel = builder.Build();

我们需要两种模型：一种用于聊天完成（回答问题），另一种用于生成嵌入（将文本转换为向量）。

定义数据模型

我们需要一个类来表示向量存储中的文档块：

using Microsoft.Extensions.VectorData;

public class DocumentChunk
{
 [VectorStoreRecordKey]
 public string Id { get; set; } = Guid.NewGuid().ToString();

 [VectorStoreRecordData]
 public string Content { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public string Source { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public int ChunkIndex { get; set; }

 [VectorStoreRecordVector(1536)]
 public ReadOnlyMemory<float> Embedding { get; set; }
}

VectorStoreRecordVector(1536) 属性告诉向量存储我们嵌入的维度。 text-embedding-3-small 模型生成 1536 维向量。

分块文档

在创建嵌入之前，我们需要将文档分割成可管理的块。这是一个简单的文本分割器：

public static class TextChunker
{
 public static List<string> SplitText(string text, int maxChunkSize = 500, int overlap = 50)
 {
 var chunks = new List<string>();
 var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
 var currentChunk = new System.Text.StringBuilder();

 foreach (var paragraph in paragraphs)
 {
 if (currentChunk.Length + paragraph.Length > maxChunkSize && currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());

 // Keep overlap from the end of the previous chunk
 var overlapText = currentChunk.ToString();
 currentChunk.Clear();
 if (overlapText.Length > overlap)
 {
 currentChunk.Append(overlapText[^overlap..]);
 currentChunk.Append(' ');
 }
 }

 currentChunk.Append(paragraph);
 currentChunk.Append("\n\n");
 }

 if (currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());
 }

 return chunks;
 }
}

重叠很重要——它确保块之间边界的上下文不会丢失。如果相关句子被分成两个块，则重叠意味着它将完全出现在至少其中一个块中。

摄取文档

现在，让我们将它们放在一起，将文档提取到我们的矢量存储中：

var vectorStore = new InMemoryVectorStore();
var collection = vectorStore.GetCollection<string, DocumentChunk>("documents");
await collection.CreateCollectionIfNotExistsAsync();

var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

async Task IngestDocument(string content, string source)
{
 var chunks = TextChunker.SplitText(content);

 for (int i = 0; i < chunks.Count; i++)
 {
 var embedding = await embeddingService.GenerateEmbeddingAsync(chunks[i]);

 var chunk = new DocumentChunk
 {
 Content = chunks[i],
 Source = source,
 ChunkIndex = i,
 Embedding = embedding
 };

 await collection.UpsertAsync(chunk);
 }

 Console.WriteLine($"✅ Ingested {chunks.Count} chunks from {source}");
}

// Ingest some documents
var doc1 = await File.ReadAllTextAsync("docs/product-guide.md");
var doc2 = await File.ReadAllTextAsync("docs/faq.md");
var doc3 = await File.ReadAllTextAsync("docs/troubleshooting.md");

await IngestDocument(doc1, "product-guide.md");
await IngestDocument(doc2, "faq.md");
await IngestDocument(doc3, "troubleshooting.md");

搜索相关块

当用户提出问题时，我们会为其查询生成嵌入并搜索相似的块：

async Task<List<DocumentChunk>> SearchAsync(string query, int topK = 3)
{
 var queryEmbedding = await embeddingService.GenerateEmbeddingAsync(query);

 var searchResults = await collection.VectorizedSearchAsync(
 queryEmbedding,
 new VectorSearchOptions { Top = topK });

 var results = new List<DocumentChunk>();
 await foreach (var result in searchResults.Results)
 {
 results.Add(result.Record);
 }

 return results;
}

根据上下文生成答案

现在是 RAG 部分 - 我们获取检索到的块并将它们作为上下文包含在提示中：

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();

async Task<string> AskAsync(string question)
{
 // Step 1: Retrieve relevant chunks
 var relevantChunks = await SearchAsync(question);

 // Step 2: Build context from chunks
 var context = string.Join("\n\n---\n\n",
 relevantChunks.Select(c => $"[Source: {c.Source}]\n{c.Content}"));

 // Step 3: Generate answer with context
 var history = new ChatHistory();
 history.AddSystemMessage($$"""
 You are a helpful assistant that answers questions based on the provided context.
 Use ONLY the information from the context to answer. If the context doesn't contain
 enough information to answer the question, say "I don't have enough information
 to answer that question."

 Do not make up information. Always cite the source document when possible.

 Context:
 {{context}}
 """);

 history.AddUserMessage(question);

 var response = await chatService.GetChatMessageContentAsync(history);
 return response.Content ?? "No response generated.";
}

使用它

// Ask questions about your documents
var answer1 = await AskAsync("How do I reset my password?");
Console.WriteLine($"Q: How do I reset my password?\nA: {answer1}\n");

var answer2 = await AskAsync("What are the system requirements?");
Console.WriteLine($"Q: What are the system requirements?\nA: {answer2}\n");

var answer3 = await AskAsync("What's the capital of France?");
Console.WriteLine($"Q: What's the capital of France?\nA: {answer3}\n");
// Should respond with "I don't have enough information" since it's not in the docs

转向生产

内存中的矢量存储非常适合原型设计，但对于生产，您需要一个持久的矢量数据库。语义内核有多个选项的连接器：

# Azure AI Search
dotnet add package Microsoft.SemanticKernel.Connectors.AzureAISearch

# Qdrant
dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant

# Redis
dotnet add package Microsoft.SemanticKernel.Connectors.Redis

交换很简单，因为它们都实现相同的 IVectorStore 接口：

// Instead of InMemoryVectorStore, use:
using Azure;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var vectorStore = new AzureAISearchVectorStore(
 new Azure.Search.Documents.Indexes.SearchIndexClient(
 new Uri(config["AzureAISearch:Endpoint"]),
 new AzureKeyCredential(config["AzureAISearch:ApiKey"])));
```其他一切都保持不变。这就是抽象的美妙之处。

## 构建 RAG 系统的技巧

我通过艰难的方式学到了一些东西：

- **块大小很重要。**太小，你会失去上下文。太大，你会在不相关的内容上浪费代币。从 500-800 个令牌开始，然后根据您的数据进行调整。
- **重叠可防止边界问题。** 块之间 50-100 个令牌重叠通常就足够了。
- **检索到的内容比您想象的要多。** 从 `topK = 5` 开始，如果您收到太多噪音，请减少。拥有额外的上下文比错过相关块要好。
- **系统提示至关重要。** 非常明确地仅使用提供的上下文。如果没有该指令，模型将很乐意“根据其训练数据”产生幻觉。
- **跟踪来源。** 始终将元数据与您的块一起存储，以便您可以引用答案的来源。当用户可以验证来源时，他们会更信任答案。
- **如果需要的话重新排名。**向量相似性并不完美。对于关键应用程序，使用交叉编码器模型添加重新排名步骤以提高精度。

## 结论

RAG 是目前人工智能中最实用的模式之一。它可以让您在自己的数据上构建人工智能驱动的问答系统，而无需进行微调，并且 Semantic Kernel 使其在 C# 中变得异常干净。从内存存储开始，正确进行分块和提示，然后在准备好生产时交换到真实的矢量数据库。

快乐编码！

## 资源

- [语义内核向量存储文档](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/)
- [使用 Azure AI 搜索的 RAG 模式](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview)
- [文本嵌入模型](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings)

使用 Microsoft Agent Framework 构建代理工作流程

Tue, 10 Feb 2026 00:00:00 +0000

简介

如果您阅读过我之前关于 Microsoft 代理框架的文章，您就会知道如何创建单个代理甚至多代理群组聊天。但在现实场景中，您通常需要更结构化的东西 - 代理按特定顺序执行、相互传递结果并根据结果处理分支逻辑的工作流程。

这正是 Agent Framework 中的工作流功能为您提供的功能。您无需将代理放入群聊中并希望他们能够解决问题，而是可以定义代理之间的显式步骤、依赖关系和数据流。

什么是代理工作流程？

将代理工作流程视为管道。每个步骤都由专门的代理处理，一个步骤的输出将输入到下一步。您可以按顺序、并行或根据结果有条件地运行步骤。

一些例子：

内容管道：研究→草稿→审查→发布
数据处理：提取→转换→验证→加载
客户支持：分类→路线→响应→跟进

先决条件

确保您拥有最新的代理框架包：

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

并配置了 Azure OpenAI 或 OpenAI 端点。

构建顺序工作流程

让我们用三个代理构建一个内容创建工作流程：研究员、作家和编辑。

定义代理

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var kernel = Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"])
 .Build();

var researcher = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = """
 You are a research specialist. Given a topic, find key facts, statistics,
 and talking points. Return a structured research brief with bullet points.
 Be thorough but concise.
 """,
 Kernel = kernel
};

var writer = new ChatCompletionAgent
{
 Name = "Writer",
 Instructions = """
 You are a technical blog writer. Given a research brief, write a clear
 and engaging blog post. Use a conversational tone, include code examples
 where relevant, and structure the post with clear headings.
 """,
 Kernel = kernel
};

var editor = new ChatCompletionAgent
{
 Name = "Editor",
 Instructions = """
 You are a senior editor. Review the blog post for clarity, accuracy,
 grammar, and flow. Return the corrected version with a summary of
 changes made at the end.
 """,
 Kernel = kernel
};

顺序执行

最简单的工作流程是顺序的——每个代理处理前一个代理的输出：

using Microsoft.SemanticKernel.Agents.Chat;
using Microsoft.SemanticKernel.ChatCompletion;

async Task<string> RunSequentialWorkflow(string topic)
{
 var history = new ChatHistory();
 string currentInput = $"Research the following topic: {topic}";

 var agents = new[] { researcher, writer, editor };

 foreach (var agent in agents)
 {
 history.AddUserMessage(currentInput);

 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 currentInput = response.ToString();
 Console.WriteLine($"✅ {agent.Name} completed");
 }

 return currentInput;
}

var result = await RunSequentialWorkflow("Blazor render modes in .NET 9");
Console.WriteLine(result);

每个代理获取累积的上下文，对其进行处理，然后将结果转移到下一步。

并行执行

有时代理可以独立工作。例如，您可能想同时研究多个子主题：

async Task<List<string>> RunParallelResearch(string[] topics)
{
 var tasks = topics.Select(async topic =>
 {
 var history = new ChatHistory();
 history.AddUserMessage($"Research: {topic}");

 var response = new System.Text.StringBuilder();
 await foreach (var message in researcher.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 Console.WriteLine($"✅ Research completed: {topic}");
 return response.ToString();
 });

 var results = await Task.WhenAll(tasks);
 return results.ToList();
}

var topics = new[]
{
 "Blazor SSR streaming",
 "Enhanced navigation in .NET 9",
 "Render mode boundaries"
};

var briefs = await RunParallelResearch(topics);

然后，您可以将所有研究摘要提供给单个作家代理，以生成一篇有凝聚力的帖子。

条件分支

真正的工作流程需要决策。也许您需要一个质量检查步骤，如果帖子不够好，可以返回给作者：

var qualityChecker = new ChatCompletionAgent
{
 Name = "QualityChecker",
 Instructions = """
 You are a quality assurance reviewer. Evaluate the blog post on:
 1. Technical accuracy
 2. Clarity and readability
 3. Completeness

 Respond with either:
 - "APPROVED" if the post meets all criteria
 - "REVISION NEEDED: [specific feedback]" if changes are required

 Be strict. Only approve posts that are truly ready to publish.
 """,
 Kernel = kernel
};

async Task<string> RunWithQualityLoop(string topic, int maxRevisions = 3)
{
 var history = new ChatHistory();

 // Step 1: Research
 history.AddUserMessage($"Research: {topic}");
 string research = await InvokeAgent(researcher, history);

 // Step 2: Write
 history.AddUserMessage(research);
 string draft = await InvokeAgent(writer, history);

 // Step 3: Quality loop
 for (int i = 0; i < maxRevisions; i++)
 {
 var qaHistory = new ChatHistory();
 qaHistory.AddUserMessage($"Review this post:\n\n{draft}");
 string qaResult = await InvokeAgent(qualityChecker, qaHistory);

 if (qaResult.Contains("APPROVED", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine($"✅ Approved after {i + 1} review(s)");
 return draft;
 }

 Console.WriteLine($"🔄 Revision {i + 1}: {qaResult[..Math.Min(100, qaResult.Length)]}...");

 // Send back to writer with feedback
 history.AddUserMessage($"Please revise based on this feedback:\n{qaResult}");
 draft = await InvokeAgent(writer, history);
 }

 Console.WriteLine("⚠️ Max revisions reached, returning latest draft");
 return draft;
}

async Task<string> InvokeAgent(ChatCompletionAgent agent, ChatHistory history)
{
 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }
 return response.ToString();
}

这个模式超级有用。质量检查器充当大门，工作流程循环直至输出足够好或达到最大修订限制。

添加插件到工作流代理

工作流中的代理可以像独立代理一样使用插件。这就是事情变得真正强大的地方 - 代理可以调用 API、查询数据库或执行文件操作，作为其工作流程步骤的一部分：

var researcherWithTools = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = "Research the topic using available tools. Summarize findings.",
 Kernel = kernel
};

// Add a web search plugin
kernel.Plugins.AddFromType<WebSearchPlugin>();

// Add a database plugin
kernel.Plugins.AddFromObject(new DatabasePlugin(connectionString), "Database");

public class WebSearchPlugin
{
 [KernelFunction, Description("Search the web for information")]
 public async Task<string> SearchAsync(
 [Description("The search query")] string query)
 {
 // Your search implementation
 using var httpClient = new HttpClient();
 var response = await httpClient.GetStringAsync(
 $"https://api.search.example.com?q={Uri.EscapeDataString(query)}");
 return response;
 }
}

工作流程中的错误处理

当您链接多个代理时，错误处理变得至关重要。您不希望某个失败的步骤导致整个工作流程悄无声息地崩溃：

async Task<WorkflowResult> RunResilientWorkflow(string input)
{
 var result = new WorkflowResult();

 try
 {
 result.Research = await InvokeAgent(researcher, new ChatHistory(input));
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Research failed: {ex.Message}");
 return result;
 }

 try
 {
 var writeHistory = new ChatHistory(result.Research);
 result.Draft = await InvokeAgent(writer, writeHistory);
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Writing failed: {ex.Message}");
 result.Draft = result.Research; // Fallback to research output
 }

 result.Success = result.Errors.Count == 0;
 return result;
}

class WorkflowResult
{
 public string Research { get; set; } = "";
 public string Draft { get; set; } = "";
 public List<string> Errors { get; set; } = new();
 public bool Success { get; set; }
}

最佳实践

在构建了几个代理工作流程之后，我学到了以下内容：- 保持代理指示的重点 - 每个代理都应该做好一件事。不要试图做瑞士军刀特工。

限制上下文 — 不要将整个对话历史记录传递给每个代理。只提供每一步所需的内容。
设置修订限制 - 质量循环很棒，但如果您不小心，可能会永远运行。始终有最大迭代次数上限。
记录一切 - 代理输出可能是不可预测的。记录每个步骤的输入和输出以进行调试。
明智地使用并行执行 - 它可以加快速度，但请注意您的 API 速率限制和令牌成本。
首先使用较小的模型进行测试 — 使用 GPT-3.5 开发和测试您的工作流程逻辑，然后再切换到 GPT-4o 进行生产。

结论

代理工作流程可让您构建复杂的多步骤 AI 管道，其中每个代理都是专家。从顺序工作流程开始，在步骤独立的情况下添加并行执行，并使用质量门的条件分支。这些模式是可组合的——一旦你掌握了它，你就可以构建一些相当复杂的自动化。

快乐编码！

资源

Blazor 组件生命周期：完整指南

Thu, 15 Jan 2026 00:00:00 +0000

我已经使用 Blazor 一段时间了，老实说，生命周期方法一开始让我感到困惑。 OnInitialized vs OnInitializedAsync？ OnParametersSet vs OnAfterRender？ StateHasChanged 何时真正触发重新渲染？经过大量的尝试和错误，我终于对这一切有了一个可靠的心理模型。

生命周期概览

当 Blazor 组件呈现时，它会按顺序执行以下方法：

SetParametersAsync
OnInitialized / OnInitializedAsync
OnParametersSet / OnParametersSetAsync
OnAfterRender / OnAfterRenderAsync
Dispose / DisposeAsync

让我们逐一介绍一下。

设置参数异步

这是调用的第一个方法。它从父组件接收原始 ParameterView。大多数情况下，您不会覆盖此设置 — Blazor 会自动处理映射参数。但是，如果您需要在分配自定义参数之前进行处理或验证：

public override async Task SetParametersAsync(ParameterView parameters)
{
 // Custom logic before parameters are set
 if (parameters.TryGetValue<string>("Title", out var title))
 {
 Console.WriteLine($"Title is being set to: {title}");
 }

 await base.SetParametersAsync(parameters);
}

我在实际项目中只使用过一次。大多数时候你会跳过它。

OnInitialized / OnInitializedAsync

这是您进行设置工作的地方 - 加载数据、初始化服务、设置默认值。它在组件首次创建时运行一次。

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 }
}

一件让我困惑的事情：在 Blazor Server 中，OnInitializedAsync 在预渲染期间被调用两次。第一次是在服务器端预渲染期间，第二次是在建立 SignalR 连接时。如果您的 API 调用成本高昂，您可能需要处理：

private bool isPrerendering = true;

protected override async Task OnInitializedAsync()
{
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 isPrerendering = false;
}

或者更好的是，使用 PersistentComponentState 完全避免双重调用。

OnParametersSet / OnParametersSetAsync

每次父组件重新渲染并传递新参数值时都会触发此事件。它也会在 OnInitialized 之后触发。这是对参数更改做出反应的正确位置：

[Parameter]
public int CategoryId { get; set; }

private int previousCategoryId;
private List<Product> products = new();

protected override async Task OnParametersSetAsync()
{
 if (CategoryId != previousCategoryId)
 {
 previousCategoryId = CategoryId;
 products = await Http.GetFromJsonAsync<List<Product>>(
 $"api/products?category={CategoryId}");
 }
}

对 CategoryId != previousCategoryId 的检查很重要 - 如果没有它，每次父级重新渲染时您都会重新加载数据，即使类别没有更改。

OnAfterRender / OnAfterRenderAsync

该事件在组件渲染到 DOM 后触发。 firstRender 参数告诉您这是否是初始渲染。这是 JS Interop 调用的地方，因为此时 DOM 元素已存在：

[Inject]
private IJSRuntime JS { get; set; }

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
 {
 await JS.InvokeVoidAsync("initializeChart", chartElement);
 }
}

我经常使用 firstRender 来避免每次重新渲染时重新初始化 JavaScript 库。如果您要设置事件侦听器、图表库或任何直接接触 DOM 的内容，那么这就是它所在的位置。

应该渲染

这个不太为人所知，但非常有用。它控制调用 StateHasChanged 时组件是否重新渲染：

private bool shouldRender = true;

protected override bool ShouldRender() => shouldRender;

private void HeavyOperation()
{
 shouldRender = false;

 // Do a bunch of state changes without triggering renders
 for (int i = 0; i < 1000; i++)
 {
 items[i].Process();
 }

 shouldRender = true;
 StateHasChanged(); // Now render once with all changes
}

我用它来优化处理大型列表的组件。您无需在每个项目更改时重新渲染，而是批量更新并在最后渲染一次。

处置/DisposeAsync

从 UI 中删除组件后，您应该清理所有资源。实施 IDisposable 或 IAsyncDisposable：

@implements IAsyncDisposable

@code {
 private Timer? timer;
 private IJSObjectReference? jsModule;

 protected override void OnInitialized()
 {
 timer = new Timer(OnTick, null, 0, 1000);
 }

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

 public async ValueTask DisposeAsync()
 {
 timer?.Dispose();

 if (jsModule is not null)
 {
 await jsModule.DisposeAsync();
 }
 }
}

要处理的常见内容：计时器、事件订阅、JS 模块引用、CancellationTokenSource 以及您创建的任何 IDisposable 服务。

状态已改变这不是生命周期方法，但密切相关。它告诉 Blazor“嘿，我的状态发生了变化，请重新渲染我。” Blazor 在事件处理程序之后自动调用它，但有时您需要手动调用它 - 通常是当状态从正常 Blazor 事件流外部发生更改时：

private async Task StartPolling()
{
 while (!cts.Token.IsCancellationRequested)
 {
 data = await Http.GetFromJsonAsync<Data>("api/data");
 StateHasChanged(); // Manual call needed since this isn't a Blazor event
 await Task.Delay(5000, cts.Token);
 }
}

一个重要注意事项：如果您从 Blazor Server 中的后台线程进行更新，请使用 InvokeAsync：

await InvokeAsync(() =>
{
 data = newData;
 StateHasChanged();
});

完整图片

以下是一切发生的顺序：

Component created
 └─ SetParametersAsync
 └─ OnInitialized / OnInitializedAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ Render
 └─ OnAfterRender(firstRender: true)

Parameter change from parent
 └─ SetParametersAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ ShouldRender?
 └─ Render
 └─ OnAfterRender(firstRender: false)

Component removed
 └─ Dispose / DisposeAsync

一旦你脑子里有了这个流程，调试生命周期问题就变得容易多了。

希望你喜欢这篇文章！请随时通过任何社交媒体与我联系：@emimontesdeoca。

资源

微软的代理框架拯救圣诞节

Tue, 16 Dec 2025 00:00:00 +0000

简介

寻找完美的圣诞礼物可能会带来压力。在集思广益的礼物创意、比较各商店的价格以及确保所有物品准时到达之间，假日购物很快就会变得势不可挡。如果我们可以将这些任务委托给协同工作的专门人工智能代理会怎么样？在这篇文章中，我们将探讨如何使用 Microsoft 的代理框架构建一个多代理系统，其中每个代理专门从事特定任务，从生成礼物创意到比较价格，所有这些都通过工作流程进行协调。

2025 年科技节日日历

<p对齐=“中心”>

该项目是我在 2025 年节日科技日历 会议的一部分，这是一场在节日期间庆祝科技的精彩社区活动。您可以在 Sessionize 上找到有关该活动的更多信息。

什么是微软的代理框架？

Agent Framework 是 Microsoft 用于构建、编排和部署 AI 代理和多代理系统的解决方案。它为创建可以顺序、并发或通过切换模式工作的代理提供了灵活的基础。该框架支持 OpenAI、Azure OpenAI 和 Microsoft Foundry 模型，使其具有令人难以置信的多功能性。

主要特点包括：

多代理编排：群聊、顺序、并发和切换模式
插件生态系统：使用本机功能、OpenAPI 和模型上下文协议 (MCP) 进行扩展
工作流支持：使用执行器和边缘构建复杂的代理管道

先决条件

在深入研究代码之前，请确保您拥有：

.NET 9
Azure OpenAI 访问（或 OpenAI API 密钥）
Visual Studio 或 Visual Studio Code

安装所需的软件包（请注意，在预览中需要 --prerelease 标志）：

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Azure.AI.Agents.Persistent --prerelease

礼品代购

我们的圣诞礼物搜寻器将由三个专业代理组成：

礼品创意代理 - 根据收件人的个人资料生成创意礼品建议
价格比较代理 - 查找不同商店的最优惠价格
Summary Agent - 编译最终建议

模型

让我们首先定义将流经代理管道的数据模型：

public class GiftRecipient
{
 public string Name { get; set; } = string.Empty;
 public int Age { get; set; }
 public List<string> Interests { get; set; } = [];
 public decimal Budget { get; set; }
}

public class GiftIdea
{
 public string Name { get; set; } = string.Empty;
 public string Description { get; set; } = string.Empty;
 public string Category { get; set; } = string.Empty;
 public decimal EstimatedPrice { get; set; }
}

public class PriceResult
{
 public string GiftName { get; set; } = string.Empty;
 public string Store { get; set; } = string.Empty;
 public decimal Price { get; set; }
 public string Url { get; set; } = string.Empty;
}

public class GiftRecommendation
{
 public GiftIdea Gift { get; set; } = new();
 public List<PriceResult> Prices { get; set; } = [];
 public PriceResult? BestDeal { get; set; }
}

构建代理

代理框架的优点在于创建专用代理是多么容易。每个代理只是一个 ChatClientAgent，具有定义其专业知识的特定系统提示。

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class ChristmasAgentFactory
{
 public static AIAgent CreateGiftIdeaAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a creative Christmas gift advisor. When given information about a person
 (age, interests, budget), you suggest thoughtful and personalized gift ideas.

 For each suggestion, provide:
 - Gift name
 - Brief description of why it's a good fit
 - Category (Electronics, Books, Fashion, Home, Experience, etc.)
 - Estimated price range

 Always suggest 3-5 gift options within the specified budget.
 Format your response as a structured list.");
 }

 public static AIAgent CreatePriceComparisonAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a price comparison specialist. Given a list of gift ideas,
 you research and compare prices from different online retailers.

 For each gift, provide:
 - Store name (Amazon, Best Buy, Target, Walmart, etc.)
 - Current price
 - Any available discounts or deals

 Always highlight the best deal for each item.
 Consider shipping costs and delivery times for Christmas.");
 }

 public static AIAgent CreateSummaryAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a gift recommendation summarizer. Take the gift ideas and price
 comparisons and create a final recommendation report.

 Your summary should:
 - Rank gifts by value (quality vs price)
 - Highlight the top pick with reasoning
 - Include total cost estimate
 - Add any tips for holiday shopping

 Make the summary cheerful and festive!");
 }
}

创建工作流程

现在到了有趣的部分，将我们的代理连接到顺序工作流程中。 Agent 框架提供了 WorkflowBuilder 和 AgentWorkflowBuilder 将代理组成不同的模式。

public static class ChristmasGiftWorkflow
{
 public static async Task RunAsync()
 {
 // Set up the Azure OpenAI client
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
 ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
 ?? "gpt-4o-mini";

 var chatClient = new AzureOpenAIClient(
 new Uri(endpoint),
 new DefaultAzureCredential())
 .GetChatClient(deploymentName)
 .AsIChatClient();

 // Create our specialized agents
 AIAgent giftIdeaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
 AIAgent priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
 AIAgent summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

 // Build a sequential workflow: Ideas -> Prices -> Summary
 var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftFinder",
 [giftIdeaAgent, priceAgent, summaryAgent]);

 // Define our gift recipient
 var recipient = new GiftRecipient
 {
 Name = "Mom",
 Age = 55,
 Interests = ["gardening", "cooking", "reading", "yoga"],
 Budget = 100
 };

 var prompt = $@"Find Christmas gifts for {recipient.Name},
 age {recipient.Age}, who enjoys {string.Join(", ", recipient.Interests)}.
 Budget: ${recipient.Budget}";

 // Execute the workflow with streaming
 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

 // Send the turn token to start processing
 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 // Watch for workflow events
 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is AgentRunUpdateEvent agentUpdate)
 {
 Console.Write(agentUpdate.Data);
 }
 else if (evt is WorkflowOutputEvent outputEvent)
 {
 Console.WriteLine("\n🎄 Final Recommendations:");
 Console.WriteLine(outputEvent.Data);
 }
 }
 }
}

同时运行代理

如果我们想同时为多人寻找礼物怎么办？ Agent框架支持并发执行，非常适合这种场景：

public static async Task FindGiftsForEveryoneAsync(IChatClient chatClient, List<GiftRecipient> recipients)
{
 // Create an agent for each recipient
 var agents = recipients.Select(r => new ChatClientAgent(
 chatClient,
 $@"Find the perfect Christmas gift for {r.Name} (age {r.Age}),
 who loves {string.Join(", ", r.Interests)}. Budget: ${r.Budget}.
 Provide one well-researched recommendation with price."
 )).ToList();

 // Build a concurrent workflow - all agents run in parallel
 var workflow = AgentWorkflowBuilder.BuildConcurrent(
 "FamilyGiftFinder",
 agents);

 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, "Find gifts now!"));

 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is WorkflowOutputEvent output)
 {
 Console.WriteLine("🎁 All gift recommendations ready!");
 Console.WriteLine(output.Data);
 }
 }
}

自定义执行器以实现更多控制对于更复杂的场景，您可以创建自定义执行器，以便对工作流程进行细粒度控制：

public sealed class GiftValidatorExecutor : Executor<List<ChatMessage>, List<ChatMessage>>
{
 public GiftValidatorExecutor() : base("GiftValidator") { }

 public override async ValueTask<List<ChatMessage>> HandleAsync(
 List<ChatMessage> messages,
 IWorkflowContext context,
 CancellationToken cancellationToken = default)
 {
 var lastMessage = messages.LastOrDefault()?.Text ?? "";

 // Validate that suggestions are within budget
 if (lastMessage.Contains("over budget", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine("⚠️ Some suggestions exceeded budget, filtering...");
 // Add validation logic here
 }

 Console.WriteLine("✅ Gift suggestions validated!");
 return messages;
 }
}

然后，您可以将此执行器插入到您的工作流程中：

var validator = new GiftValidatorExecutor();

var workflow = new WorkflowBuilder(giftIdeaAgent)
 .AddEdge(giftIdeaAgent, validator)
 .AddEdge(validator, priceAgent)
 .AddEdge(priceAgent, summaryAgent)
 .WithOutputFrom(summaryAgent)
 .Build();

使用 Bing 基础添加真实的 Web 搜索

到目前为止，我们的代理根据人工智能模型的知识生成响应。但是，如果我们想在网络上搜索实际产品价格和库存情况该怎么办？这就是 Grounding with Bing Search 的用武之地。它是 Microsoft Foundry（以前称为 Azure AI Foundry）中提供的工具，允许您的代理在生成响应时合并实时公共 Web 数据。

首先，您需要在 Azure 门户中创建 Grounding with Bing Search 资源。确保将其创建在与您的 AI 项目相同的资源组中。

使用 Bing 搜索设置基础

Grounding with Bing Search 的优点在于它直接与 Azure AI Agent 集成。代理根据用户的查询决定何时使用搜索工具，搜索网络，并使用结果生成接地响应。

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public static class BingGroundingSetup
{
 public static async Task<PersistentAgent> CreateAgentWithBingGroundingAsync(
 string projectEndpoint,
 string modelDeploymentName,
 string bingConnectionId)
 {
 // Create the Persistent Agents client
 var agentClient = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());

 // Configure the Bing Grounding tool
 var bingGroundingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(bingConnectionId)]
 )
 );

 // Create the agent with Bing Grounding enabled
 var agent = await agentClient.Administration.CreateAgentAsync(
 model: modelDeploymentName,
 name: "ChristmasPriceHunter",
 instructions: @"You are a Christmas gift price comparison specialist.

 When given gift ideas, use Bing to search for:
 - Current prices at major retailers (Amazon, Best Buy, Target, Walmart)
 - Available discounts and holiday deals
 - Shipping times to ensure delivery before Christmas

 Always provide URLs to the products you find.
 Highlight the best deals and recommend where to buy.",
 tools: [bingGroundingTool]
 );

 return agent;
 }
}

创建具有真实搜索的价格比较代理

现在让我们创建一个完整的价格比较代理，用于在网络上搜索真实的产品信息：

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public class ChristmasPriceAgent
{
 private readonly PersistentAgentsClient _client;
 private readonly string _modelDeployment;
 private readonly string _bingConnectionId;

 public ChristmasPriceAgent(string projectEndpoint, string modelDeployment, string bingConnectionId)
 {
 _client = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());
 _modelDeployment = modelDeployment;
 _bingConnectionId = bingConnectionId;
 }

 public async Task<string> FindGiftPricesAsync(string giftIdeas)
 {
 // Create agent with Bing Grounding
 var bingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(_bingConnectionId)]
 )
 );

 var agent = await _client.Administration.CreateAgentAsync(
 model: _modelDeployment,
 name: "PriceHunter",
 instructions: @"Search the web for current prices on the given gift ideas.
 For each gift, find prices from at least 2-3 different stores.
 Include direct links to the products.
 Note any Christmas sales or discounts available.",
 tools: [bingTool]
 );

 try
 {
 // Create a thread for the conversation
 var thread = await _client.Threads.CreateThreadAsync();

 // Add the gift ideas as a message
 await _client.Messages.CreateMessageAsync(
 thread.Id,
 MessageRole.User,
 $"Find current prices for these gift ideas: {giftIdeas}"
 );

 // Run the agent
 var run = await _client.Runs.CreateRunAsync(thread.Id, agent.Id);

 // Wait for completion
 do
 {
 await Task.Delay(500);
 run = await _client.Runs.GetRunAsync(thread.Id, run.Id);
 }
 while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

 // Get the response
 var messages = _client.Messages.GetMessages(thread.Id);
 var response = messages
 .Where(m => m.Role == MessageRole.Agent)
 .SelectMany(m => m.ContentItems)
 .OfType<MessageTextContent>()
 .FirstOrDefault();

 // Clean up
 await _client.Threads.DeleteThreadAsync(thread.Id);

 return response?.Text ?? "No results found.";
 }
 finally
 {
 // Clean up the agent
 await _client.Administration.DeleteAgentAsync(agent.Id);
 }
 }
}

将 Bing Grounding 集成到工作流程中

以下是如何在完整的礼品搜寻工作流程中使用 Bing 支持的价格代理：

public static async Task RunWithBingGroundingAsync()
{
 var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!;
 var modelDeployment = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
 var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID")!;
 // Connection ID format: /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection}

 Console.WriteLine("🔍 Searching the web for real prices with Bing Grounding...\n");

 var priceAgent = new ChristmasPriceAgent(projectEndpoint, modelDeployment, bingConnectionId);

 // First, generate gift ideas (could come from another agent)
 var giftIdeas = "1. Milwaukee cordless drill set, 2. Weber portable grill, 3. Carhartt beanie";

 // Search for real prices
 var priceResults = await priceAgent.FindGiftPricesAsync(giftIdeas);

 Console.WriteLine("📊 Price Comparison Results:");
 Console.WriteLine(priceResults);
 Console.WriteLine("\n🎁 Happy Shopping! 🎁");
}

处理来自 Bing 结果的引用

Bing 搜索扎根的一个重要方面是回复中包含带有源网站链接的引用。以下是提取和显示它们的方法：

public static void ProcessBingGroundingResponse(IEnumerable<PersistentThreadMessage> messages)
{
 foreach (var message in messages.Where(m => m.Role == MessageRole.Agent))
 {
 foreach (var content in message.ContentItems)
 {
 if (content is MessageTextContent textContent)
 {
 var response = textContent.Text;

 // Process URL citations
 if (textContent.Annotations != null)
 {
 foreach (var annotation in textContent.Annotations)
 {
 if (annotation is MessageTextUriCitationAnnotation uriAnnotation)
 {
 // Replace citation placeholder with markdown link
 response = response.Replace(
 uriAnnotation.Text,
 $" [{uriAnnotation.UriCitation.Title}]({uriAnnotation.UriCitation.Uri})"
 );
 }
 }
 }

 Console.WriteLine(response);
 }
 }
 }
}

现在，当价格比较代理运行时，它使用 Grounding with Bing Search 从实时网络中查找真实的产品列表、当前价格和可用交易。代理根据查询自动决定何时进行搜索，并返回带有正确引用的接地响应。

完整的程序

以下是 Program.cs 中所有内容的组合方式：

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

Console.WriteLine("🎄 Christmas Gift Finder - Powered by AI Agents 🎄\n");

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
 .GetChatClient(deployment)
 .AsIChatClient();

// Create the agent team
var ideaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
var priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
var summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

// Build the workflow
var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftWorkflow",
 [ideaAgent, priceAgent, summaryAgent]);

Console.Write("Who are you shopping for? ");
var recipientName = Console.ReadLine() ?? "Someone special";

Console.Write("What are their interests? ");
var interests = Console.ReadLine() ?? "general";

Console.Write("What's your budget? $");
var budget = Console.ReadLine() ?? "50";

var prompt = $"Find Christmas gifts for {recipientName} who enjoys {interests}. Budget: ${budget}";

Console.WriteLine("\n🔍 Searching for the perfect gifts...\n");

await using var run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (var evt in run.WatchStreamAsync())
{
 switch (evt)
 {
 case AgentRunUpdateEvent update:
 Console.Write(update.Update.Text);
 break;
 case WorkflowOutputEvent output:
 Console.WriteLine("\n\n🎁 Happy Shopping! 🎁");
 break;
 }
}

结论

Microsoft 的代理框架使构建多代理系统变得异常容易，其中每个代理专门从事特定任务。通过通过工作流程协调这些代理，我们可以以结构化且高效的方式解决圣诞节购物等复杂问题。

让它变得更加强大的是通过工具添加现实世界功能的能力。通过将 Grounding 与 Microsoft Foundry 的 Bing Search 集成，我们的价格比较代理实际上可以在网络上搜索当前价格、交易和库存情况，将简单的 AI 聊天机器人转变为具有正确引用的真正有用的购物助手。

该框架对顺序、并发和切换模式的支持意味着您可以设计符合您确切需求的代理系统。无论是寻找礼物、计划旅行还是任何其他多步骤任务，代理框架都提供了实现这些目标的构建块。这个假期，让人工智能代理来处理研究，而您则专注于包装礼物并享受与家人共度的时光！

源代码

本文中显示的概念基于官方代理框架示例。您可以在 Microsoft Agent Framework GitHub 存储库上探索更多示例。

节日快乐，编码愉快！ 🎄

构建人工智能驱动的 RSS 提要聚合器

Fri, 12 Dec 2025 00:00:00 +0000

作为一名 Microsoft MVP 和技术爱好者，我经常发现自己淹没在 Microsoft 开发博客上发布的令人惊叹的内容的海洋中。从 .NET 公告到 Visual Studio 更新，从 Azure 创新到语义内核深入研究 - Microsoft 生态系统中总是会发生一些令人兴奋的新事物。

问题？ 跟上这一切几乎是不可能的。

我想掌握最新公告并与我的网络分享它们，但手动检查七个不同的 RSS 源、阅读文章、制作引人入胜的社交媒体帖子以及跟踪我已经分享的内容本身就成为了一项全职工作。每天早上，我都会打开多个浏览器选项卡，浏览数十篇文章，尝试记住我已经分享过哪些文章，然后花宝贵的时间撰写引起我注意的文章。

所以我做了任何开发人员都会做的事情 – 我将其自动化。

在本综合指南中，我将向您介绍如何构建一个基于 AI 的 RSS 提要聚合器，该聚合器可监视多个 Microsoft DevBlogs RSS 提要的新内容、使用 Azure OpenAI 和 Semantic Kernel 分析文章并生成引人入胜的帖子、为每篇分析的文章创建详细的 Markdown 文档、通过 Telegram 发送通知以便我可以查看和共享内容、跟踪所有内容以避免重复帖子，并通过 GitHub Actions 自动运行。

让我们深入探讨该解决方案的各个方面。

这个项目背后的故事

生活在信息超载中

让我为您描绘一下我在构建这个工具之前的典型早晨。我会醒来，喝杯咖啡，打开笔记本电脑，查看微软开发者生态系统中的新内容。首先，我会导航到主要的 DevBlogs 站点，查看是否有任何重大公告。然后我会专门查看 .NET 博客，因为那是我的主要技术堆栈。之后，我会跳转到语义内核博客，因为人工智能变得越来越重要。 Visual Studio 博客排在第二位，因为 IDE 更新会显着影响我的日常工作流程。然后是有关 CI/CD 和 GitHub 相关新闻的 DevOps 博客，接着是有关云基础设施更新的 All Things Azure 博客，最后是有关数据库创新的 Azure SQL 博客。

有七个不同的提要需要检查。这些博客每周都会发布多篇文章，有时在 .NET Conf 或 Build 等重大公告期间每天会发布多篇文章。这可能需要跟踪、阅读和分享数十篇文章。事情是这样的——作为一个重视与社区分享知识的人，我不想只阅读这些文章。我想在 LinkedIn 上与我的网络分享最有价值的内容，帮助其他开发人员也了解最新情况。但制作一篇好的 LinkedIn 帖子需要时间。你需要彻底阅读这篇文章，理解要点，思考为什么它对你的读者很重要，写一个引人入胜的钩子，并很好地格式化所有内容。将其乘以每周几篇文章，您就会看到工作时间。

我真正想要的是什么

在处理这个问题几个月后，我坐下来思考理想的解决方案是什么样的。首先，我不想再错过重要的公告。系统应在新文章发布后立即自动捕获它们。我还希望通过让人工智能帮助制作引人入胜的帖子来节省内容创建的时间——不是完全取代我的声音，而是给我一个可以定制的坚实的起点。

一致性是另一个重要因素。我想定期分享内容，而不必记住每天手动执行。跟踪方面也至关重要 - 我需要一种方法来了解我已经分享的内容，以避免发布重复内容并惹恼我的关注者。最后，我想对我处理过的所有内容进行永久记录，保持井然有序，这样我就可以回顾并查看我涵盖了哪些主题。

解决方案已成型

我设想的解决方案将使用 GitHub Actions 按计划运行，完全免提。它会自动获取所有七个提要，而无需我打开单个浏览器选项卡。人工智能组件实际上会阅读并理解内容，然后以对我的观众有用的方式进行总结。我不必从头开始撰写帖子，而是创建可随时分享的社交媒体内容，我可以根据需要进行调整。所有内容都会发送到我的 Telegram 进行审核，这样我就可以快速浏览手机并决定分享哪些内容。当然，它会永久记录所有内容以供将来参考。

在我们开始构建之前

您的机器需要什么

要学习本教程，您需要在开发计算机上安装一些东西。最重要的是.NET SDK 9.0 或更高版本。这是我们的运行时，提供了我们需要的所有构建工具。如果您尚未安装，请访问 dot.net 并下载最新版本。在 Windows、macOS 或 Linux 上安装非常简单。

您还需要安装 Git 以进行版本控制。我们将把代码推送到 GitHub 并使用 GitHub Actions 实现自动化，因此在本地设置 Git 至关重要。任何最新版本都可以正常工作。

对于您的开发环境，我推荐 Visual Studio 或 VS Code。就我个人而言，我现在的大部分工作都使用 VS Code，因为它是轻量级的，并且通过 C# Dev Kit 扩展提供了出色的 C# 支持。但如果您更喜欢完整的 Visual Studio，那么它也可以完美工作。

您需要的服务和帐户除了本地工具之外，您还需要具有一些服务的帐户。最重要的是 Azure OpenAI，它为我们的 AI 分析提供支持。这是一种即用即付的服务，但该用例的成本很低——我们所说的是每篇分析文章的成本。如果没有 Azure 帐户，可以注册免费试用版，其中包含一些入门积分。

对于通知，我们将使用 Telegram 机器人。 Telegram 的伟大之处在于他们的机器人 API 完全免费使用。您可以根据需要创建任意数量的机器人并发送无限的消息。我将在本指南的后面部分引导您完成设置过程。

最后，您需要一个 GitHub 帐户来托管代码并运行 GitHub Actions。免费套餐对于这个项目来说已经足够了。 GitHub 在私有存储库上每月为您提供 2,000 分钟的 Actions 运行时间，在公共存储库上提供无限分钟的运行时间。

让这一切成为可能的图书馆

我们的项目依赖于三个主要的 NuGet 包，每个包都有特定的用途。

第一个是 HtmlAgilityPack，它是 .NET 中 HTML 解析的黄金标准。当我们从博客中获取文章时，我们会获取页面的完整 HTML，包括导航菜单、页脚、广告以及各种我们不关心的元素。 HtmlAgilityPack 让我们能够解析该 HTML 并仅提取我们需要的文章内容。

第二个包是Microsoft.SemanticKernel，它是微软用于将AI模型集成到应用程序中的SDK。将其视为 .NET 代码和 GPT-4 等大型语言模型之间的桥梁。它处理 API 调用、令牌管理和响应解析的所有复杂性，让您专注于希望 AI 实际执行的操作。

第三个包是 System.ServiceModel.Syndicate，它提供了对解析 RSS 和 Atom 提要的内置支持。 RSS 可能看起来像旧技术，但它仍然是从博客和新闻网站获取结构化更新的最佳方式。该包将原始 XML 源转换为易于使用的强类型 C# 对象。

理解架构

各部分如何组合在一起

在我们深入研究代码之前，让我解释一下所有组件如何协同工作。了解大局将使实施细节更加清晰。

在最高级别，我们有主 Program.cs 文件作为协调器。这是我们应用程序的入口点，它协调所有其他组件。当应用程序运行时，它首先从环境变量加载配置 - 例如 API 密钥和 Telegram 凭证。然后它会从所有七个 Microsoft DevBlogs 源中获取 RSS 源。在处理这些提要时，它会对文章进行重复数据删除，以处理同一篇文章出现在多个提要中的情况。它会根据我们的跟踪文件检查每篇文章，看看我们是否已经处理了它。对于新文章，它将交给人工智能分析器进行处理。ArticleAnalyzer 类是 AI 魔法发生的地方。该组件接收一篇文章并用它做一些事情。首先，它从文章的 URL 中获取完整的 HTML 内容。然后，它从该 HTML 中提取干净的文本，删除我们不需要的所有导航元素、脚本和样式。一旦获得干净的文本，它就会通过语义内核将其发送到 Azure OpenAI，并带有精心设计的提示。人工智能会分析文章并返回结构化响应，其中包括摘要、关键主题、相关性解释，以及最重要的即用型 LinkedIn 帖子。分析器解析此响应并返回包含所有这些信息的 ArticleAnalysis 对象。

MarkdownGenerator 类采用该 ArticleAnalysis 对象并创建它的永久记录。它生成一个格式良好的 Markdown 文件，其中包括所有文章元数据、人工智能的分析和生成的帖子。这些文件存储在 generated-posts 目录中，为您提供已处理的所有内容的可搜索存档。

最后，Telegram 集成将生成的帖子内容发送到您的手机。这是你作为人类可以审查人工智能的工作并决定是否分享它的时刻。机器人会向您发送一条包含帖子内容的消息，您可以将其直接复制到 LinkedIn 或先进行修改。

数据流

让我向您介绍在 .NET 博客上发布新文章时会发生什么情况。当 GitHub Actions 按计划触发我们的应用程序时（假设每六个小时），工作流程就开始了。应用程序唤醒并开始获取所有七个 RSS 源。每个提要都会返回一个 XML 文档，其中包含该博客的最新文章。

当我们解析每个提要时，我们提取单个文章并将它们存储在一个列表中。但这里有一个棘手的部分 - 主要的开发博客提要通常包含也出现在各个类别提要中的文章。因此，有关“.NET 10”的文章可能会同时出现在主提要和特定于 .NET 的提要中。我们通过跟踪 HashSet 中的 URL 来处理这个问题，这会自动防止重复。

一旦我们获得了重复数据删除的文章列表，我们就会将其过滤为最近的文章——通常是在最后一天左右发布的文章。我们不想处理在之前的运行中已经处理过的旧文章。然后我们根据跟踪文件检查每一篇最近的文章。如果我们已经处理并发布了一篇文章，我们会跳过它。

对于每一篇新文章，我们都会启动人工智能分析流程。分析器获取完整文章 HTML，对其进行清理，然后根据我们的提示将其发送到 GPT-4。人工智能会阅读这篇文章并生成全面的分析以及 LinkedIn 帖子。我们将此分析保存到 Markdown 文件中以供记录。分析完成后，我们格式化消息并通过 Telegram 发送。该消息包括生成的帖子内容以及附加的 URL 和主题标签。在我的手机上，我会收到一条通知，查看该帖子，如果我喜欢它，只需轻按几下即可将其复制并在 LinkedIn 上分享。

最后，我们更新跟踪文件以将本文标记为已处理，因此我们不会在以后的运行中再次处理它。如果创建或修改了任何文件，GitHub Actions 会将这些更改提交回存储库，使所有内容保持同步。

从头开始设置项目

创建解决方案结构

让我们开始构建吧。打开终端并导航到要创建项目的位置。我喜欢将我的项目组织在“开发”文件夹中，但您可以将其放在对您有意义的任何位置。

首先，我们将创建一个新的解决方案文件。在 .NET 中，解决方案是可以容纳多个项目的容器。尽管我们目前只有一个项目，但从解决方案开始可以更轻松地在以后需要时添加更多项目。运行命令 dotnet new sln -n vs-feed-linkedin 创建一个名为 vs-feed-linkedin 的解决方案。

接下来，我们需要创建控制台应用程序项目。我们将把它放在 src 子目录中以保持组织有序。运行 dotnet new console -n VsFeedLinkedin -o src 在 src 文件夹中创建一个名为 VsFeedLinkedin 的控制台项目。然后使用 dotnet sln add src/VsFeedLinkedin.csproj 将此项目添加到我们的解决方案中。

现在使用 cd src 导航到 src 目录。我们将在此处添加 NuGet 包并进行大部分开发。

添加所需的包

创建项目后，我们需要添加我之前提到的三个 NuGet 包。按顺序运行以下每个命令：

dotnet add package System.ServiceModel.Syndication --version 9.0.9
dotnet add package Microsoft.SemanticKernel --version 1.30.0
dotnet add package HtmlAgilityPack --version 1.11.72

运行这些命令后，您的项目文件应如下所示：

<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>
 <OutputType>Exe</OutputType>
 <TargetFramework>net9.0</TargetFramework>
 <ImplicitUsings>enable</ImplicitUsings>
 <Nullable>enable</Nullable>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="HtmlAgilityPack" Version="1.11.72" />
 <PackageReference Include="Microsoft.SemanticKernel" Version="1.30.0" />
 <PackageReference Include="System.ServiceModel.Syndication" Version="9.0.9" />
 </ItemGroup>

</Project>

项目文件告诉 .NET，我们正在构建一个可执行文件（OutputType 是 Exe），目标是 .NET 9.0，并使用现代 C# 功能，例如隐式使用和可为 null 的引用类型。 ItemGroup 部分列出了我们的三个包依赖项及其确切版本。

深入研究 RSS 源

RSS 到底是什么？

在我们开始编写代码来获取提要之前，让我们确保我们了解我们正在使用的内容。 RSS 代表“真正简单的聚合”，它是一种用于分发内容更新的标准化 XML 格式。这个想法很简单：您不需要用户访问您的网站来查看是否有新内容，而是发布一个列出您最近内容的机器可读文件。然后，应用程序可以定期轮询该文件以发现新文章。

RSS 自 20 世纪 90 年代末和 2000 年代初就已出现。您可能认为它是过时的技术，但实际上它仍然被广泛使用——尤其是博客、新闻网站和播客。 RSS 的美妙之处在于它的简单性。它只是具有已定义结构的 XML，任何应用程序都可以解析它。

开发博客提要的结构当您从 Microsoft DevBlogs 获取 RSS 源时，您会得到一个遵循特定结构的 XML 文档。在顶层，有一个 rss 元素，其中包含单个频道元素。该频道代表博客本身，并包含博客标题、URL 和描述等元数据。

在频道内，您会发现多个项目元素，每个元素代表一篇单独的博客文章。每一项都包含标题（文章的标题）、链接（可以在其中阅读全文的 URL）、pubDate（文章发布时间）、dc:creator 元素（作者姓名）、一个或多个类别元素（文章的标签）和说明（通常是文章的摘要或摘录）。

下面是一个简化的示例：

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
 <channel>
 <title>.NET Blog</title>
 <link>https://devblogs.microsoft.com/dotnet</link>
 <description>The latest news about .NET</description>
 <item>
 <title>Announcing .NET 10</title>
 <link>https://devblogs.microsoft.com/dotnet/announcing-dotnet-10</link>
 <pubDate>Mon, 10 Dec 2025 12:00:00 GMT</pubDate>
 <dc:creator>Microsoft</dc:creator>
 <category>Announcements</category>
 <category>.NET</category>
 <description>Article summary...</description>
 </item>
 </channel>
</rss>

.NET 的 System.ServiceModel.Synmination 包的伟大之处在于它为我们解析了所有这些。我们不必手动导航 XML 节点或担心不同的 RSS 版本。我们只需加载提要并返回强类型对象。

我们监控的七个提要

在我的实现中，我监视七个不同的 Microsoft DevBlogs 源。 devblogs.microsoft.com/feed 上的主要 DevBlogs feed 使我们能够全面了解 Microsoft 在其所有开发人员博客中发布的所有内容。 devblogs.microsoft.com/dotnet/feed 上的 .NET 特定源专门关注 .NET 版本、功能和最佳实践。 devblogs.microsoft.com/semantic-kernel/feed 上的语义内核源涵盖了人工智能编排和集成——随着人工智能成为现代发展的核心，它变得越来越重要。

devblogs.microsoft.com/visualstudio/feed 上的 Visual Studio feed 让我随时了解 IDE 改进和生产力功能的最新信息。 devblogs.microsoft.com/devops/feed 上的 DevOps 源涵盖了 Azure DevOps、GitHub 和 CI/CD 主题。 devblogs.microsoft.com/all-things-azure/feed 上的 All Things Azure 源重点关注云服务和体系结构模式。最后，devblogs.microsoft.com/azure-sql/feed 上的 Azure SQL 源涵盖了数据库创新和功能。

您可能想知道为什么我同时检查主要提要和单个类别提要。主要提要给了我广度——我会看到来自任何 Microsoft 开发人员博客的文章，包括我可能不知道的文章。类别提要给了我深度——它们确保我不会错过我感兴趣的核心领域中的任何重要内容，即使这些文章被更新的内容从主提要中挤出。

构建 RSS 获取逻辑

核心抓取功能

现在让我们编写一些代码。我们应用程序的基础是获取和解析 RSS 提要的能力。这是处理这个问题的函数：

static async Task<SyndicationFeed?> FetchRssFeedAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 var response = await httpClient.GetStringAsync(url);

 using var stringReader = new StringReader(response);

 var settings = new XmlReaderSettings
 {
 DtdProcessing = DtdProcessing.Parse,
 MaxCharactersFromEntities = 1024
 };

 using var xmlReader = XmlReader.Create(stringReader, settings);

 return SyndicationFeed.Load(xmlReader);
}

让我来看看这段代码的作用。我们首先创建一个 HttpClient，它是 .NET 用于发出 HTTP 请求的内置类。我们设置 User-Agent 标头是因为某些服务器会阻止无法识别自身身份的请求。即使服务器不需要它，也最好设置它。然后，我们向 feed URL 发出 GET 请求并接收字符串形式的响应。该字符串包含 RSS 源的原始 XML。

为了解析此 XML，我们创建一个 StringReader 来包装我们的响应字符串，然后配置一些 XmlReaderSettings。 DtdProcessing 设置很重要 - RSS 提要有时包含需要处理的 DTD（文档类型定义）声明。 MaxCharactersFromEntities 设置是一种安全措施，通过限制可以发生的实体扩展量来防止 XML 炸弹攻击。

最后，我们使用这些设置创建一个 XmlReader，并使用 SyndicateFeed.Load 将 XML 解析为强类型 SyndicateFeed 对象。这使我们能够通过良好的 C# 属性而不是原始 XML 导航来访问提要的元数据及其所有项目。

通过错误处理获取多个提要

在现实世界中，网络请求会失败。服务器宕机、连接超时、XML 格式可能错误。我们需要优雅地处理这些案件。以下是我们如何获取所有 feed，同时对故障具有弹性：

var allArticles = new List<(SyndicationItem item, string feedUrl)>();
var seenUrls = new HashSet<string>();

foreach (var feedUrl in feedUrls)
{
 try
 {
 Console.WriteLine($" 📡 Fetching {feedUrl}...");
 var feed = await FetchRssFeedAsync(feedUrl);

 if (feed?.Items != null && feed.Items.Any())
 {
 foreach (var item in feed.Items)
 {
 var itemUrl = item.Links.FirstOrDefault()?.Uri.ToString() ?? "";
 if (!string.IsNullOrEmpty(itemUrl) && seenUrls.Add(itemUrl))
 {
 allArticles.Add((item, feedUrl));
 }
 }
 }
 }
 catch (Exception ex)
 {
 Console.WriteLine($" ⚠️ Failed to fetch {feedUrl}: {ex.Message}");
 }
}

我们在这里维护两个集合。 allArticles 列表将包含我们找到的所有文章，以及它们来自哪个提要。 sawUrls HashSet 跟踪我们已经看过的文章 URL，帮助我们避免重复。

我们循环遍历每个 feed URL 并将 fetch 操作包装在 try-catch 块中。如果获取特定提要失败（可能是服务器暂时关闭），我们会记录一条警告并继续处理下一个提要。这样，一个提要出现问题就不会妨碍我们处理其他提要。

对于每个成功获取的提要，我们迭代其项目。我们从项目的 Links 集合中提取文章 URL。如果 URL 已在集合中，则 HashSet.Add 方法将返回 false，这非常适合我们的重复数据删除逻辑。我们仅将新文章添加到我们的列表中。

我们将提要 URL 与每篇文章一起存储，因为此信息稍后可能有用 - 例如，我们可能想知道文章来自哪个特定提要以用于调试或日志记录目的。

处理重复项和跟踪状态

重复数据删除挑战

正如我之前提到的，Microsoft DevBlogs 具有分层提要结构，这带来了有趣的挑战。当 .NET 团队成员发布一篇有关 .NET 10 性能改进的文章时，该文章可能会同时出现在主要 DevBlogs 提要和 .NET 特定提要中。有时，如果它与 IDE 功能相关，它甚至可能出现在 Visual Studio feed 中。

如果我们天真地处理每个提要中的每一篇文章，我们最终会多次分析和发布同一篇文章。这会浪费对 Azure OpenAI 的 API 调用，用重复的通知向我们的 Telegram 发送垃圾邮件，如果我们发布重复的通知，还可能会惹恼我们的关注者。解决方案是基于 URL 的重复数据删除。每篇文章都有一个唯一的 URL，因此我们可以将其用作标识符。 HashSet 数据结构非常适合此目的，因为它提供 O(1) 查找时间并自动防止重复。当我们尝试添加集合中已有的 URL 时，Add 方法只会返回 false，让我们知道应该跳过该文章。

使用 Markdown 持久化状态

重复数据删除可以处理单次运行中的重复项，但是跨运行时又如何呢？当我们的应用程序每六个小时运行一次时，我们需要记住我们已经处理过哪些文章，这样我们就不会再次处理它们。

我选择将此状态存储在名为 posts-articles.md 的 markdown 文件中。为什么要降价？有几个原因。首先，它是人类可读的。我可以打开文件并立即查看我共享了哪些文章。其次，它是版本控制的。由于该文件位于我们的 Git 存储库中，因此我拥有文章处理时间的完整历史记录。第三，它作为文档。任何查看存储库的人都可以看到应用程序做了什么。

该文件的格式很简单。它有一个标题、一个显示应用程序上次运行时间的时间戳，以及一个 Markdown 链接格式的文章列表：

# Posted Articles

*Last run: 2025-12-10 15:30:00*

List of articles posted to LinkedIn:

- [Announcing .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-10?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-10 15:30:00 (Published: 2025-12-10)
- [Visual Studio 2026 Preview](https://devblogs.microsoft.com/visualstudio/vs-2026-preview?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-09 10:15:00 (Published: 2025-12-09)

加载并解析跟踪文件

要检查我们是否已经处理了一篇文章，我们需要加载该文件并提取 URL。这是执行此操作的函数：

static HashSet<string> LoadPostedArticles(string filePath)
{
 var postedUrls = new HashSet<string>();

 if (!File.Exists(filePath))
 {
 return postedUrls;
 }

 var lines = File.ReadAllLines(filePath);
 foreach (var line in lines)
 {
 var match = System.Text.RegularExpressions.Regex.Match(line, @"\(([^)]+)\)");
 if (match.Success)
 {
 var url = match.Groups[1].Value;

 if (url.Contains("?wt.mc_id="))
 {
 url = url.Substring(0, url.IndexOf("?wt.mc_id="));
 }
 else if (url.Contains("?"))
 {
 url = url.Substring(0, url.IndexOf("?"));
 }

 url = url.TrimEnd('/');
 postedUrls.Add(url);
 }
 }

 return postedUrls;
}

该函数返回一个包含我们已经处理过的所有 URL 的 HashSet。我们首先检查文件是否存在 - 第一次运行时，它不会存在，因此我们返回一个空集。

对于文件中的每一行，我们使用正则表达式从 Markdown 链接格式中提取 URL。正则表达式 $([^)]+)$ 匹配括号内的任何内容，这是 Markdown 链接存储其 URL 的位置。

接下来是重要的一步：URL 规范化。同一篇文章的 URL 格式可能有所不同。 RSS 提要可能会给我们 https://devblogs.microsoft.com/dotnet/article，但我们保存的版本附加了一个跟踪参数：https://devblogs.microsoft.com/dotnet/article?wt.mc_id=DT-MVP-5004972。有些 URL 结尾有斜杠，有些则没有。

为了解决这个问题，我们删除所有查询参数（? 之后的所有内容）并删除尾部斜杠。这种规范化确保我们将文章识别为重复项，即使它们的 URL 在这些表面上有所不同。

保存新文章

当我们成功处理一篇文章时，我们需要将其添加到我们的跟踪文件中：

static void SavePostedArticle(string filePath, string url, string title, DateTimeOffset publishDate)
{
 var markdownEntry = $"- [{title}]({url}) - Posted on {DateTime.Now:yyyy-MM-dd HH:mm:ss} (Published: {publishDate:yyyy-MM-dd})\n";

 if (!File.Exists(filePath))
 {
 File.WriteAllText(filePath, "# Posted Articles\n\n*Last run: {DateTime.Now:yyyy-MM-dd HH:mm:ss}*\n\nList of articles posted:\n\n");
 }

 File.AppendAllText(filePath, markdownEntry);
}

此函数创建一个 Markdown 格式的条目，其中文章标题作为链接，后跟时间戳，显示我们发布该文章的时间以及最初发布的时间。如果该文件尚不存在，我们首先使用标头创建它。

AI 分析引擎

理解语义内核现在我们进入应用程序中最令人兴奋的部分——人工智能分析。 Semantic Kernel 是 Microsoft 的开源 SDK，用于将大型语言模型集成到应用程序中。它不仅仅是 API 调用的包装器。它提供了一个框架，用于构建具有插件、规划器和内存等功能的复杂人工智能应用程序。

对于我们的用例，我们使用语义内核的聊天完成功能。我们将向 Azure OpenAI 发送提示，该模型将分析我们的文章并生成响应。语义内核处理 API 身份验证、请求格式化和响应解析的所有复杂性。

设置文章分析器

让我们看看如何设置分析器类：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using HtmlAgilityPack;

namespace VsFeedLinkedin.Services;

public class ArticleAnalyzer
{
 private readonly Kernel _kernel;
 private readonly IChatCompletionService _chatService;

 public ArticleAnalyzer(string endpoint, string apiKey, string deploymentName)
 {
 var builder = Kernel.CreateBuilder();

 builder.AddAzureOpenAIChatCompletion(
 deploymentName: deploymentName,
 endpoint: endpoint,
 apiKey: apiKey
 );

 _kernel = builder.Build();
 _chatService = _kernel.GetRequiredService<IChatCompletionService>();
 }

语义内核使用构建器模式进行配置。我们创建一个 KernelBuilder，使用必要的凭据添加 Azure OpenAI 聊天完成服务，然后构建内核。从构建的内核中，我们检索 IChatCompletionService 接口，我们将使用该接口发送提示和接收响应。

构造函数采用三个参数：Azure OpenAI 终结点（例如 https://your-resource.openai.azure.com/）、API 密钥和部署名称（例如 gpt-4o）。这些是从环境变量传入的，确保我们的凭据安全。

制作完美的提示

我们发送给人工智能的提示至关重要。精心设计的提示可以产生一致、高质量的输出。模糊或结构不良的提示会产生不一致、平庸的结果。我花了相当多的时间迭代这个提示以获得我满意的输出：

var prompt = $"""
 You are a professional tech content analyst and LinkedIn content creator.
 Analyze the following Microsoft DevBlogs article and create an engaging LinkedIn post.

 Article Title: {title}
 Author: {author}
 URL: {url}
 Tags: {string.Join(", ", tags)}

 Article Content:
 {cleanContent}

 Please provide:
 1. A brief summary (2-3 sentences) of the key points
 2. The main technologies or topics covered
 3. Why this is relevant for developers/tech professionals
 4. An engaging LinkedIn post (max 1300 characters) that:
 - Starts with a hook or attention-grabbing statement
 - Highlights the key value for readers
 - Includes a call to action
 - Uses appropriate emojis (but not too many)
 - Maintains a professional yet approachable tone
 - DO NOT include hashtags in the post (they will be added separately)
 - DO NOT include the URL in the post (it will be added separately)

 Format your response as follows:
 ## Summary
 [Your summary here]

 ## Key Topics
 [List of main topics/technologies]

 ## Relevance
 [Why this matters]

 ## LinkedIn Post
 [Your engaging LinkedIn post here]
 """;

让我在这里解释一下设计决策。我们首先给人工智能一个明确的角色：“你是一名专业的技术内容分析师和 LinkedIn 内容创建者。”这使模型能够以适当的风格和声音做出反应。

我们提供 AI 所需的所有上下文：文章标题、作者、URL、RSS 提要中的标签以及完整的文章内容。我们提供的背景越多，分析就会越好。

然后我们准确指定我们想要返回的内容。我要求提供四件事：摘要、关键主题、相关性解释和 LinkedIn 帖子。具体来说，对于 LinkedIn 帖子，我给出了关于什么是好帖子的详细说明 - 它应该有一个钩子，突出价值，包括号召性用语，适当使用表情符号，并保持专业的语气。

负面指示同样重要。我明确告诉 AI 不要在帖子中包含主题标签或 URL。为什么？因为我是单独添加这些的，如果人工智能包含它们，我就会有重复的。这种明确的指示可以防止常见错误。

最后，我指定确切的输出格式。通过询问标有 ## 标头的部分，我可以轻松以编程方式解析响应。 AI 非常擅长遵循格式化指令，这种一致性使我们的解析代码更简单、更可靠。

执行分析

以下是我们将它们组合在一起的方式：

public async Task<ArticleAnalysis> AnalyzeArticleAsync(
 string title,
 string url,
 string htmlContent,
 string author,
 List<string> tags)
{
 var cleanContent = ExtractTextFromHtml(htmlContent);

 if (cleanContent.Length > 8000)
 {
 cleanContent = cleanContent.Substring(0, 8000) + "...";
 }

 var chatHistory = new ChatHistory();
 chatHistory.AddUserMessage(prompt);

 var response = await _chatService.GetChatMessageContentAsync(chatHistory);
 var responseText = response.Content ?? "";

 return ParseAnalysisResponse(responseText, title, url, author, tags);
}
```我们首先从 HTML 内容中提取干净的文本（我将在下一节中对此进行解释）。然后，如果内容太长，我们会截断内容。大型语言模型有令牌限制，很长的文章可能会超出它们。通过将字符数限制在 8000 个字符，我们确保在限制范围内，同时仍提供大量上下文。

我们创建一个 ChatHistory 对象并将提示添加为用户消息。这是语义内核对基于聊天的交互的抽象。我们将其发送到聊天完成服务并获取响应。最后，我们解析响应以提取各个部分。

### 解析 AI 响应

AI 将其响应返回为按照我们请求的结构格式化的文本。我们需要将其解析为单独的字段：

```csharp
private static ArticleAnalysis ParseAnalysisResponse(
 string response,
 string title,
 string url,
 string author,
 List<string> tags)
{
 var analysis = new ArticleAnalysis
 {
 Title = title,
 Url = url,
 Author = author,
 Tags = tags,
 RawAnalysis = response
 };

 var sections = response.Split("##", StringSplitOptions.RemoveEmptyEntries);

 foreach (var section in sections)
 {
 var lines = section.Trim().Split('\n', 2);
 if (lines.Length < 2) continue;

 var sectionTitle = lines[0].Trim().ToLower();
 var sectionContent = lines[1].Trim();

 switch (sectionTitle)
 {
 case "summary":
 analysis.Summary = sectionContent;
 break;
 case "key topics":
 analysis.KeyTopics = sectionContent;
 break;
 case "relevance":
 analysis.Relevance = sectionContent;
 break;
 case "linkedin post":
 analysis.LinkedInPost = sectionContent;
 break;
 }
 }

 return analysis;
}

我们通过 ## 标记分割响应，这给了我们每个部分。对于每个部分，我们用换行符分割以将标题与内容分开。然后，我们使用 switch 语句将每个部分的内容分配给适当的属性。

我们还存储原始的、未解析的响应。这对于调试很有用——如果解析出现问题，我们可以查看人工智能实际返回的内容。

从 HTML 中提取内容

为什么我们需要清理 HTML

当我们从博客中获取文章时，我们会获得该页面的完整 HTML。这不仅仅包括文章内容，还有导航菜单、页眉、页脚、侧边栏、相关文章小部件、评论部分、用于分析和跟踪的脚本、样式表以及各种其他元素。

如果我们将所有这些发送给人工智能，就会发生一些不好的事情。人工智能将不得不处理大量不相关的文本，浪费标记并可能使分析变得混乱。导航和页脚文本可能会包含在摘要中。脚本和 CSS 将被视为内容，进一步污染分析。

我们只需要提取文章内容——人类读者实际会阅读的部分。

使用 HtmlAgilityPack

HtmlAgilityPack 是一个强大的 .NET HTML 解析库。与 XML 不同，HTML 的格式通常是错误的——标签可能无法正确闭合，属性可能无法正确引用。 HtmlAgilityPack 优雅地处理了所有这些，为我们提供了一个可以查询和操作的类似 DOM 的结构。

这是我们的提取函数：

private static string ExtractTextFromHtml(string html)
{
 if (string.IsNullOrWhiteSpace(html))
 return string.Empty;

 var doc = new HtmlDocument();
 doc.LoadHtml(html);

 var nodesToRemove = doc.DocumentNode.SelectNodes("//script|//style|//nav|//footer|//header");
 if (nodesToRemove != null)
 {
 foreach (var node in nodesToRemove)
 {
 node.Remove();
 }
 }

 var text = doc.DocumentNode.InnerText;

 text = System.Text.RegularExpressions.Regex.Replace(text, @"\s+", " ");
 return text.Trim();
}

我们将 HTML 加载到 HtmlDocument 中，该文档将其解析为树结构。然后我们使用 XPath 选择所有要删除的节点。 XPath 表达式 //script|//style|//nav|//footer|//header 选择所有脚本元素（我们不需要的 JavaScript 代码）、样式元素（我们不需要的 CSS）、导航元素（导航菜单）、页脚元素和页眉元素。

删除这些节点后，我们得到了 InnerText 属性，该属性在剥离 HTML 标签的同时提取所有文本内容。这为我们提供了文章的纯文本。最后，我们清理空白。 HTML 通常有大量额外的空白用于格式化目的——多个空格、制表符、换行符。我们使用正则表达式将任何空白字符序列替换为单个空格，然后修剪结果。

获取全文

RSS 源仅向我们提供摘要，而不是完整的文章内容。要获取完整的文本，我们需要获取文章的网页：

public static async Task<string> FetchArticleContentAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 try
 {
 return await httpClient.GetStringAsync(url);
 }
 catch (Exception ex)
 {
 Console.WriteLine($"⚠️ Failed to fetch article content: {ex.Message}");
 return string.Empty;
 }
}

这很简单 – 我们向文章 URL 发出 HTTP GET 请求并返回 HTML 响应。我们将其包装在 try-catch 中，因为网络请求可能会失败，并且我们宁愿返回空字符串也不愿使整个应用程序崩溃。

创建永久文档

为什么生成 Markdown 文件

每次我们分析一篇文章时，我们都会生成一个详细的 Markdown 文件来记录该分析。这有几个目的。

首先，它创建一个可搜索的档案。随着时间的推移，您将建立一个分析文章的集合。您可以搜索这些文件以查找特定主题的过去内容。

其次，它提供透明度。您可以准确地看到人工智能为每篇文章生成的内容，包括完整的分析和 LinkedIn 帖子。

第三，它对于调试很有用。如果帖子出现问题，您可以查看 markdown 文件以了解发生了什么。

Markdown 生成器类

public class MarkdownGenerator
{
 private readonly string _outputDirectory;

 public MarkdownGenerator(string outputDirectory)
 {
 _outputDirectory = outputDirectory;

 if (!Directory.Exists(_outputDirectory))
 {
 Directory.CreateDirectory(_outputDirectory);
 }
 }

 public string GenerateMarkdownFile(ArticleAnalysis analysis)
 {
 var sb = new StringBuilder();

 var safeTitle = GenerateSafeFileName(analysis.Title);
 var fileName = $"{analysis.AnalyzedAt:yyyy-MM-dd}_{safeTitle}.md";
 var filePath = Path.Combine(_outputDirectory, fileName);

 sb.AppendLine($"# {analysis.Title}");
 sb.AppendLine();
 sb.AppendLine("## Article Information");
 sb.AppendLine();
 sb.AppendLine($"- **Author:** {analysis.Author}");
 sb.AppendLine($"- **URL:** [{analysis.Url}]({analysis.Url})");
 sb.AppendLine($"- **Published:** {analysis.PublishDate:yyyy-MM-dd}");
 sb.AppendLine($"- **Analyzed:** {analysis.AnalyzedAt:yyyy-MM-dd HH:mm:ss}");
 sb.AppendLine($"- **Tags:** {string.Join(", ", analysis.Tags)}");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## AI Analysis");
 sb.AppendLine();
 sb.AppendLine("### Summary");
 sb.AppendLine();
 sb.AppendLine(analysis.Summary);
 sb.AppendLine();
 sb.AppendLine("### Key Topics");
 sb.AppendLine();
 sb.AppendLine(analysis.KeyTopics);
 sb.AppendLine();
 sb.AppendLine("### Relevance for Developers");
 sb.AppendLine();
 sb.AppendLine(analysis.Relevance);
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## Generated LinkedIn Post");
 sb.AppendLine();
 sb.AppendLine("```");
 sb.AppendLine(analysis.LinkedInPost);
 sb.AppendLine("```");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("*This analysis was generated using AI (Semantic Kernel with Azure OpenAI)*");

 File.WriteAllText(filePath, sb.ToString());
 return filePath;
 }

构造函数采用输出目录路径，如果不存在则创建它。 GenerateMarkdownFile 方法采用 ArticleAnalysis 对象并生成格式良好的 Markdown 文档。

文件名包括日期和标题的清理版本。这使得文件易于按时间顺序排序并一目了然。

处理不安全的文件名

文章标题可以包含文件名中不允许的字符 - 例如冒号、斜杠、问号和引号。我们需要对这些进行消毒：

private static string GenerateSafeFileName(string title)
{
 var invalidChars = Path.GetInvalidFileNameChars();
 var safeTitle = new string(title
 .Where(c => !invalidChars.Contains(c))
 .ToArray());

 safeTitle = safeTitle.Replace(" ", "-").Replace("--", "-");

 if (safeTitle.Length > 50)
 {
 safeTitle = safeTitle.Substring(0, 50);
 }

 return safeTitle.TrimEnd('-').ToLowerInvariant();
}

我们使用 Path.GetInvalidFileNameChars() 来获取当前操作系统上的文件名中不能出现的字符列表。我们过滤掉这些内容，用连字符替换空格以提高可读性，将长度限制为 50 个字符，并转换为小写以保持一致性。

设置 Telegram 通知

为什么我选择 Telegram

对于通知组件，我考虑了几种选择——电子邮件、短信、Slack、Discord 和 Telegram。我最终选择 Telegram 有几个原因。

该 API 完全免费，对于合理使用没有速率限制。许多通知服务对您可以免费发送的消息数量有限制，但 Telegram 并不限制向个人用户发送机器人消息。

机器人 API 非常简单。它只是带有 JSON 负载的 HTTP 请求。没有复杂的身份验证流程，基本功能不需要 Webhook。Telegram 可以在任何地方使用——在我的手机上、在我的桌面上、在我的网络浏览器上。无论我身在何处，我都可以收到通知并立即回复。

消息支持丰富的格式。我可以使用粗体文本、斜体甚至代码块来使我的通知更具可读性。

创建您的 Telegram 机器人

设置 Telegram 机器人非常简单。打开 Telegram 并搜索 @BotFather – 这是 Telegram 的官方机器人，用于创建和管理机器人。与 BotFather 开始对话并发送命令 /newbot。 BotFather 会要求您提供机器人的名称（这是显示名称）和用户名（必须是唯一的并以“bot”结尾）。一旦您提供了这些信息，BotFather 将创建您的机器人并为您提供 API 令牌。这个令牌就像一个密码——保密并且不要将其提交到公共存储库。

要找到您的聊天 ID，以便机器人知道向何处发送消息，请通过搜索新机器人并按“开始”来开始与新机器人的对话。然后在浏览器中或使用curl访问URL https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates。在响应中查找 chat 对象 - id 字段是您的聊天 ID。

通过 API 发送消息

这是我们发送 Telegram 消息的函数：

static async Task SendToTelegramAsync(string botToken, string chatId, string message)
{
 using var httpClient = new HttpClient();

 var telegramApiUrl = $"https://api.telegram.org/bot{botToken}/sendMessage";

 var payload = new
 {
 chat_id = chatId,
 text = message,
 parse_mode = "HTML"
 };

 var jsonContent = JsonSerializer.Serialize(payload);
 var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

 var response = await httpClient.PostAsync(telegramApiUrl, content);

 if (!response.IsSuccessStatusCode)
 {
 var errorContent = await response.Content.ReadAsStringAsync();
 throw new Exception($"Telegram API error: {response.StatusCode} - {errorContent}");
 }
}

Telegram Bot API 基于 REST。我们向 sendMessage 端点发出一个 POST 请求，其中包含一个 JSON 正文，其中包含聊天 ID（发送位置）、消息文本（发送内容）以及可选的解析模式（用于格式化）。

将 parse_mode 设置为“HTML”可以让我们在消息中使用基本的 HTML 标签 - 例如 <b>bold</b> 和 <i>italic</i>。这可以使通知更具可读性，尽管对于我们当前的用例，我们发送纯文本。

如果请求失败，我们会抛出异常，并提供有关错误原因的详细信息。如果某些东西不起作用，这有助于调试。

配置应用程序

环境变量

我们的应用程序需要几条敏感信息 – API 密钥、机器人令牌和端点 URL。我们永远不应该对它们进行硬编码或将它们提交给版本控制。相反，我们使用环境变量，可以在应用程序运行的每个环境中安全地设置这些变量。

对于 Telegram，我们需要 TELEGRAM_BOT_TOKEN（BotFather 给您的令牌）和 TELEGRAM_CHAT_ID（应发送消息的聊天 ID）。

对于 Azure OpenAI，我们需要 AZURE_OPENAI_ENDPOINT（您的资源的 URL）、AZURE_OPENAI_API_KEY（您的 API 密钥）和 AZURE_OPENAI_DEPLOYMENT（您部署的模型的名称，例如“gpt-4o”）。

在代码中加载配置

以下是我们在应用程序启动时加载这些值的方式：

var telegramBotToken = Environment.GetEnvironmentVariable("TELEGRAM_BOT_TOKEN");
var telegramChatId = Environment.GetEnvironmentVariable("TELEGRAM_CHAT_ID");

var azureOpenAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
var azureOpenAiDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o";

var aiAnalysisEnabled = !string.IsNullOrWhiteSpace(azureOpenAiEndpoint) &&
 !string.IsNullOrWhiteSpace(azureOpenAiKey);

我们使用Environment.GetEnvironmentVariable来读取每个值。对于部署名称，如果未设置值，我们将提供默认值“gpt-4o”。

然后，我们通过验证是否拥有端点和 API 密钥来检查是否应启用 AI 分析。如果未配置 Azure OpenAI，这允许应用程序在降级模式下运行 - 它仍然会获取源并跟踪文章，只是没有 AI 分析。### 优雅的降级

优雅降级的概念很重要。我们不希望应用程序仅仅因为未配置一项可选功能而崩溃：

ArticleAnalyzer? articleAnalyzer = null;
MarkdownGenerator? markdownGenerator = null;

if (aiAnalysisEnabled)
{
 Console.WriteLine("🤖 AI Analysis enabled - Using Azure OpenAI with Semantic Kernel");
 articleAnalyzer = new ArticleAnalyzer(azureOpenAiEndpoint!, azureOpenAiKey!, azureOpenAiDeployment);
 markdownGenerator = new MarkdownGenerator(articlesOutputDir);
}
else
{
 Console.WriteLine("ℹ️ AI Analysis disabled - Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY to enable");
}

如果启用了人工智能，我们将创建分析器和降价生成器。如果没有，我们将它们留空并在处理过程中跳过与人工智能相关的步骤。即使没有人工智能增强，该应用程序仍然通过获取源和发送基本通知来提供价值。

使用 GitHub Actions 实现自动化

为什么选择 GitHub Actions

该解决方案的真正力量来自自动化。我们不想每隔几个小时手动运行一次应用程序——我们希望它在后台自动运行。

GitHub Actions 非常适合此目的。它内置于 GitHub 中，因此无需设置额外的服务。它对公共存储库免费，并为私人存储库提供大量免费分钟。它可以按计划运行，定期触发我们的应用程序。它具有内置的秘密管理功能，可以安全地存储我们的 API 密钥。它可以将更改提交回存储库，使我们的跟踪文件保持最新。

工作流程文件

在 .github/workflows/fetch-and-notify.yml 中创建一个包含以下内容的文件：

name: Fetch DevBlogs and Notify

on:
 schedule:
 - cron: '0 */6 * * *'
 workflow_dispatch:

jobs:
 fetch-and-notify:
 runs-on: ubuntu-latest

 steps:
 - name: Checkout repository
 uses: actions/checkout@v4

 - name: Setup .NET
 uses: actions/setup-dotnet@v4
 with:
 dotnet-version: '9.0.x'

 - name: Restore dependencies
 run: dotnet restore src/VsFeedLinkedin.csproj

 - name: Build
 run: dotnet build src/VsFeedLinkedin.csproj --no-restore

 - name: Run application
 env:
 TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
 TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
 AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
 AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
 AZURE_OPENAI_DEPLOYMENT: ${{ secrets.AZURE_OPENAI_DEPLOYMENT }}
 run: dotnet run --project src/VsFeedLinkedin.csproj

 - name: Commit and push changes
 run: |
 git config user.name "GitHub Actions Bot"
 git config user.email "actions@github.com"

 if [[ -n $(git status --porcelain posted-articles.md generated-posts/) ]]; then
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 git add posted-articles.md generated-posts/
 git commit -m "chore($TIMESTAMP): processed new articles"
 git push
 else
 echo "No changes to commit"
 fi

让我解释一下每个部分。 on 部分定义工作流程何时运行。计划触发器使用 cron 语法 - 0 */6 * * * 表示“每 6 小时的 0 分钟”。因此，工作流在午夜、上午 6 点、中午和下午 6 点（UTC）运行。 workflow_dispatch 触发器允许从 GitHub UI 手动运行，这对于测试很有用。

该作业在 ubuntu-latest（Linux 虚拟机）上运行。我们检查我们的存储库、设置 .NET 9、恢复 NuGet 包并构建项目。

运行应用程序步骤是奇迹发生的地方。我们使用 ${{ Secrets.SECRET_NAME }} 语法将机密作为环境变量传递。这些秘密安全地存储在 GitHub 中，并且永远不会在日志中公开。

最后，我们将所有更改提交回存储库。我们使用机器人身份配置 Git，检查我们的跟踪文件或生成的帖子目录是否有任何更改，如果有，则创建提交并推送它。

设置秘密

要将机密添加到 GitHub 存储库，请转到存储库的“设置”，然后转到“机密和变量”，然后转到“操作”。单击“新存储库机密”并添加每个环境变量。这些名称必须与我们在工作流程文件中引用的名称完全匹配。

总结

我们已经构建了什么

回顾我们所涵盖的所有内容，我们构建了一个全面的、由人工智能驱动的 RSS 提要聚合器，可以自动执行过去繁琐的手动流程。该应用程序自动监视七个 Microsoft DevBlogs 源，在每一篇新文章发布后立即捕获它。它处理重复数据删除的复杂性，识别同一篇文章何时出现在多个提要中。由 Semantic Kernel 和 Azure OpenAI 提供支持的 AI 分析可以自动读取和理解文章内容、生成摘要、识别关键主题并解释相关性。最重要的是，它创建了引人入胜的 LinkedIn 帖子，我可以通过最少的编辑来分享这些帖子。

Telegram 集成意味着每当有新内容需要查看时我都会在手机上收到通知。我可以浏览该消息，决定是否要分享它，然后立即采取行动。

而且因为它按计划在 GitHub Actions 上运行，所以我不必记住做任何事情。该系统在后台运行，只有当有值得分享的东西时我才会参与。

使之成为可能的技术

该项目汇集了多种技术，每种技术都发挥着至关重要的作用。 .NET 9 以其现代语言功能和出色的性能提供了坚实的基础。语义内核使 AI 集成变得简单，处理 API 调用和响应管理的所有复杂性。 Azure OpenAI 提供了智能——真正理解和分析技术内容的能力。 HtmlAgilityPack 解决了从网页中提取干净文本的混乱问题。 System.ServiceModel.Syndicate 使 RSS 解析变得轻而易举。 Telegram Bot API 为我们提供了免费、可靠的通知。 GitHub Actions 将这一切与自动化、预定的执行结合在一起。

考虑成本

您可能会问的一个问题是：运行该程序需要多少钱？答案是：一点也不多。

Telegram 完全免费 - 通过机器人发送消息无需付费。

GitHub Actions 对公共存储库免费。对于私有存储库，您每月可以使用 2,000 分钟的免费套餐，这对于我们的用例来说绰绰有余。

Azure OpenAI 是唯一付费组件，而且成本极低。使用 GPT-4o 分析一篇典型的博客文章的成本约为 1 到 3 美分。即使您每月处理数十篇文章，您所看到的人工智能成本也不足一美元。

接下来你可以去哪里

虽然这个解决方案非常适合我的需求，但您可以通过多种方式扩展它。您可以添加对多个社交平台的支持 - 除了 LinkedIn 之外，还可以发布到 Twitter/X、Mastodon 或 Bluesky。您可以实施情绪分析来跟踪一段时间内文章的基调并发现趋势。您可以为不同的提要允许不同的提示模板，为不同的主题生成不同风格的帖子。您可以构建一个 Web 仪表板来查看和管理帖子，而不是使用 Telegram。您可以跟踪已发布内容的参与度指标，以了解哪些主题最能引起受众的共鸣。

最后的想法我最喜欢这个项目的是，它体现了我坚信的哲学：自动化应该处理繁琐的部分，同时将创造性和决策部分留给人类。该系统完成了所有繁琐的工作——获取、解析、分析、生成——但我仍然在分享之前检查所有内容。人工智能生成的帖子是我可以定制和个性化的起点。

通过结合 .NET、Semantic Kernel 和 Azure OpenAI 的强大功能，我们创建了一个工具，可以每周节省数小时的手动工作，同时保持质量和一致性。这是一种真正改变日常生活的实用自动化。

如果您构建了类似的东西或有改进的想法，我很想听听。请随时通过 LinkedIn 联系我们！

编码快乐，圣诞快乐！ 🎄

使用微软代理框架构建多代理人工智能系统

Mon, 01 Dec 2025 00:00:00 +0000

简介

我们已经进入了多智能体人工智能系统的时代。该行业不再是单一的单一人工智能处理所有事情，而是转向协作解决复杂问题的专业代理——就像组织良好的专家团队一样。一名代理人进行研究，另一名代理人进行分析，第三名代理人进行写作，一名协调员让每个人都步入正轨。

如果您使用过大型语言模型，您可能已经达到了单个提示功能的上限。上下文窗口被填满，指令变得混乱，质量下降。多代理架构通过将复杂的任务分解为集中的职责来解决这个问题，其中每个代理都是一件事的专家。

Microsoft 的代理框架是更广泛的语义内核生态系统的一部分，它为 .NET 开发人员提供了用于构建此类系统的一流工具包。在这篇文章中，我们将从零开始构建一个完全工作的多代理管道，涵盖核心概念、编排模式和入门所需的实用代码。

什么是微软的代理框架？

Agent Framework 是 Microsoft 在 .NET 中构建、编排和部署 AI 代理和多代理系统的解决方案。它与语义内核并存，并与之深度集成，语义内核自 2023 年以来一直是微软用于 AI 编排的开源 SDK。

可以这样想：语义内核为您提供原语（内核、插件、内存、规划器），而代理框架为您提供专门为代理到代理通信和协调而设计的更高级别的抽象。

该框架支持多个模型提供程序，包括 Azure OpenAI、OpenAI 以及 Azure AI Foundry 上托管的模型。它在设计上与模型无关，但与 Azure 生态系统深度集成，这使得它对于企业场景特别有吸引力。

主要能力包括：

多种代理类型：针对不同后端的 ChatCompletionAgent、OpenAIAssistantAgent 和 AzureAIAgent
编排模式：顺序、并发、切换和群聊工作流程
插件生态系统：使用本机 C# 函数、OpenAPI 规范和模型上下文协议 (MCP) 工具扩展代理
会话管理：内置线程、历史管理和终止策略
可观察性：与 OpenTelemetry 集成以跟踪代理交互

关键概念

在编写任何代码之前，让我们先建立词汇表。代理框架围绕一些核心抽象展开。

代理

代理是由 AI 模型支持的实体，配置有特定指令（系统提示）、名称以及可选的一组插件或工具。每个代理都是专家——您可以定义它知道什么、可以做什么以及应该如何表现。

聊天完成代理最直接的代理类型。它包装聊天完成端点（Azure OpenAI、OpenAI 等）并维护对话。它在调用之间是无状态的——您提供历史记录，它就会做出响应。这使得它变得轻量且易于推理。

ChatCompletionAgent agent = new()
{
 Name = "Reviewer",
 Instructions = "You are a senior code reviewer. Analyze the provided code for bugs, security issues, and style violations. Be concise and actionable.",
 Kernel = kernel
};

OpenAIAssistantAgent

此代理类型利用 OpenAI Assistants API，该 API 提供服务器端对话状态、文件处理和代码解释。它更重量级，但为您提供持久线程和内置工具，例如代码解释器和文件搜索。

OpenAIAssistantAgent agent = await OpenAIAssistantAgent.CreateAsync(
 clientProvider: clientProvider,
 definition: new OpenAIAssistantDefinition("gpt-4o")
 {
 Name = "DataAnalyst",
 Instructions = "You analyze datasets and produce statistical summaries."
 }
);

代理群组聊天

这是协调器。 AgentGroupChat 管理多个代理之间的多轮对话，控制下一个发言者、对话何时结束以及如何共享历史记录。这就是多智能体协作的神奇之处。

编排模式

该框架支持四种主要的编排模式，每种模式适合不同的问题。

顺序

代理按照定义的顺序依次执行。代理 A 的输出馈送到代理 B，代理 B 的输出馈送到代理 C。这对于管道来说是理想的：草稿 → 审查 → 编辑 → 发布。

// Conceptual flow
var draft = await writerAgent.InvokeAsync("Write a blog post about .NET 9");
var reviewed = await reviewerAgent.InvokeAsync($"Review this: {draft}");
var edited = await editorAgent.InvokeAsync($"Edit based on feedback: {reviewed}");

并发

多个代理同时处理同一输入。您将工作展开，然后汇总结果。非常适合获得不同的观点——比如让三个审阅者查看同一个拉取请求。

切换

代理根据对话上下文决定将控制权转移给另一个代理。这模仿了客户服务团队的工作方式：一线代理处理基本查询并在需要时升级为专家。

群聊

多个代理参与公开对话，根据选择策略轮流进行。 AgentGroupChat 类通过可配置的轮流和终止逻辑来实现此模式。

构建你的第一个代理

让我们实际一点吧。以下是如何逐步构建您的第一个代理。

先决条件

你需要：

.NET 9 SDK
具有已部署模型的 Azure OpenAI 资源（例如 gpt-4o）
Visual Studio 或 VS Code

设置项目

创建一个新的控制台应用程序并安装所需的包：

dotnet new console -n AgentDemo
cd AgentDemo
dotnet add package Microsoft.SemanticKernel --prerelease
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

创建一个简单的代理

首先，使用 Azure OpenAI 配置设置内核：

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);

Kernel kernel = builder.Build();

现在创建一个代理并调用它：

ChatCompletionAgent agent = new()
{
 Name = "TechWriter",
 Instructions = """
 You are a technical writer specializing in software documentation.
 Write clear, concise content aimed at experienced developers.
 Use code examples when appropriate.
 Always structure your output with headings and bullet points.
 """,
 Kernel = kernel
};

ChatHistory history = new();
history.AddUserMessage("Explain dependency injection in .NET in 200 words.");

await foreach (ChatMessageContent response in agent.InvokeAsync(history))
{
 Console.WriteLine(response.Content);
}

就是这样。你有一个工作代理人。但真正的力量来自于特工们的共同努力。

使用 AgentGroupChat 进行多代理编排

让我们构建一些更有趣的东西——多个代理协作的群聊。 AgentGroupChat 类管理对话流，包括谁接下来发言以及何时停止。

定义代理

我们将创建三个代理：作家、审阅者和编辑。

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a content writer. When given a topic, produce a well-structured
 draft. Focus on clarity and technical accuracy.
 When you receive feedback from the Reviewer, incorporate it into a
 revised draft.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a content reviewer. Analyze drafts for technical accuracy,
 clarity, and completeness. Provide specific, actionable feedback.
 Do NOT rewrite the content — only provide feedback.
 When the content meets your standards, respond with: APPROVED
 """,
 Kernel = kernel
};

ChatCompletionAgent editor = new()
{
 Name = "Editor",
 Instructions = """
 You are an editor. Once content is approved by the Reviewer,
 polish it for grammar, tone, and formatting.
 Output only the final polished version.
 When you have produced the final version, respond with: COMPLETE
 """,
 Kernel = kernel
};

设置群聊

AgentGroupChat 需要两个关键配置：选择策略（下一个发言者）和终止策略（何时停止）。

AgentGroupChat chat = new(writer, reviewer, editor)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [editor],
 MaximumIterations = 12
 }
 }
};

自定义终止策略终止策略定义对话何时结束。这是一个查找“COMPLETE”关键字的自定义：

class ApprovalTerminationStrategy : TerminationStrategy
{
 protected override Task<bool> ShouldAgentTerminateAsync(
 Agent agent,
 IReadOnlyList<ChatMessageContent> history,
 CancellationToken cancellationToken = default)
 {
 bool isComplete = history
 .Last()
 .Content?
 .Contains("COMPLETE", StringComparison.OrdinalIgnoreCase) ?? false;

 return Task.FromResult(isComplete);
 }
}

运行对话

通过用户消息开始对话并让代理进行协作：

chat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User,
 "Write a 300-word technical overview of gRPC vs REST for microservices.")
);

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
 Console.WriteLine("---");
}

流程将如下所示：

作者起草草稿
审稿人提供反馈
作者根据反馈进行修改
审阅者说“已批准”
编辑润色并说“完成”
通话结束

这种来回自动继续，直到满足终止条件或达到 MaximumIterations。

插件和工具

当代理能够与外部系统交互时，它们就会变得真正强大。 Agent框架支持三种主要的扩展机制。

本机函数（内核插件）

您可以让代理访问 C# 方法作为工具。当代理确定需要这些函数时，它将调用这些函数：

public class ContentToolsPlugin
{
 [KernelFunction("word_count")]
 [Description("Counts the number of words in the provided text.")]
 public int WordCount([Description("The text to count words in")] string text)
 {
 return text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 }

 [KernelFunction("check_readability")]
 [Description("Calculates a readability score for the given text.")]
 public string CheckReadability([Description("The text to analyze")] string text)
 {
 var words = text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 var sentences = text.Split(['.', '!', '?'], StringSplitOptions.RemoveEmptyEntries).Length;

 if (sentences == 0) return "Unable to calculate — no sentences found.";

 double avgWordsPerSentence = (double)words / sentences;

 return avgWordsPerSentence switch
 {
 < 15 => $"Easy to read (avg {avgWordsPerSentence:F1} words/sentence)",
 < 25 => $"Moderate difficulty (avg {avgWordsPerSentence:F1} words/sentence)",
 _ => $"Difficult to read (avg {avgWordsPerSentence:F1} words/sentence). Consider shorter sentences."
 };
 }
}

在创建代理之前在内核上注册插件：

kernel.Plugins.AddFromType<ContentToolsPlugin>();

ChatCompletionAgent analyst = new()
{
 Name = "ContentAnalyst",
 Instructions = "Analyze content using available tools. Report word count and readability.",
 Kernel = kernel,
 Arguments = new KernelArguments(
 new PromptExecutionSettings
 {
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 })
};

模型上下文协议 (MCP)

MCP 是一种用于将 AI 模型连接到外部工具和数据源的开放标准。代理框架支持 MCP，这意味着您的代理可以使用任何符合 MCP 的服务器公开的工具。这为文件系统、数据库、API 等打开了大门——所有这些都通过标准化接口实现。

// Example: Adding an MCP server for file operations
kernel.Plugins.AddFromMcpServer("filesystem",
 new Uri("http://localhost:3000/mcp"));

这是特别令人兴奋的，因为这意味着您的代理不仅限于您构建的内容 - 他们可以利用其他人开发和共享的 MCP 工具生态系统。

真实示例：内容审核流程

让我们将所有内容与实际场景结合起来。想象一下，您正在构建一个内部工具，可以自动为文档团队进行内容审查。该管道有四个阶段：

研究员 — 收集相关技术信息
作家 — 根据研究撰写草稿
审阅者 — 检查准确性和完整性
发布者 — 格式化并准备最终输出

这是一个精简的实现：

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

// Build the kernel
var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);
Kernel kernel = builder.Build();

// Define specialized agents
ChatCompletionAgent researcher = new()
{
 Name = "Researcher",
 Instructions = """
 You are a technical researcher. Given a topic, identify the key
 concepts, recent developments, and important details that should
 be covered. Output a structured research brief.
 """,
 Kernel = kernel
};

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a technical writer. Using the research brief provided,
 write a comprehensive, well-structured article. Include code
 examples where relevant. Target audience: experienced developers.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a senior technical reviewer. Check the article for:
 - Technical accuracy
 - Completeness relative to the research brief
 - Code correctness
 - Clarity and structure
 If everything looks good, respond with APPROVED.
 Otherwise, provide specific feedback for revision.
 """,
 Kernel = kernel
};

ChatCompletionAgent publisher = new()
{
 Name = "Publisher",
 Instructions = """
 You are a content publisher. Once the article is approved,
 format it with proper markdown, add a summary at the top,
 and ensure consistent formatting throughout.
 End your response with COMPLETE.
 """,
 Kernel = kernel
};

// Configure the group chat
AgentGroupChat chat = new(researcher, writer, reviewer, publisher)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [publisher],
 MaximumIterations = 15
 }
 }
};

// Start the pipeline
chat.AddChatMessage(new ChatMessageContent(
 AuthorRole.User,
 "Create a technical article about implementing health checks in ASP.NET Core microservices."
));

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.ForegroundColor = message.AuthorName switch
 {
 "Researcher" => ConsoleColor.Cyan,
 "Writer" => ConsoleColor.Green,
 "Reviewer" => ConsoleColor.Yellow,
 "Publisher" => ConsoleColor.Magenta,
 _ => ConsoleColor.White
 };

 Console.WriteLine($"\n{'='new string('=', 60)}");
 Console.WriteLine($"[{message.AuthorName}]");
 Console.WriteLine(new string('=', 60));
 Console.WriteLine(message.Content);
}

Console.ResetColor();

该流程通过代理协作生成一篇经过充分研究、撰写、审查和格式化的文章。每个代理都专注于自己最擅长的事情，AgentGroupChat 协调工作流程。

最佳实践

在构建了多个多代理系统之后，以下是我发现最有价值的模式和实践。

错误处理

始终在终止策略中设置 MaximumIterations。如果没有它，代理可能会进入无限循环——尤其是当审稿人不断发现问题而作者不断修改而没有改进时。

TerminationStrategy = new ApprovalTerminationStrategy()
{
 MaximumIterations = 12 // Safety net
}

将代理调用包装在 try-catch 块中。 API 速率限制、网络问题和模型错误都是生产系统的现实：

try
{
 await foreach (var message in chat.InvokeAsync(cancellationToken))
 {
 // Process messages
 }
}
catch (HttpOperationException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
{
 // Implement retry with exponential backoff
 await Task.Delay(TimeSpan.FromSeconds(30), cancellationToken);
}

可观察性代理框架与 OpenTelemetry 集成，这意味着您可以跟踪每个代理交互、工具调用和令牌使用情况。这对于调试多代理工作流程至关重要，因为在这种情况下，哪个代理导致问题并不总是很明显。

通过添加语义内核遥测包并配置您的首选导出器（Application Insights、Jaeger 等）来设置基本遥测：

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing =>
 {
 tracing.AddSource("Microsoft.SemanticKernel*");
 tracing.AddOtlpExporter();
 });

成本管理

多代理系统会增加您的 API 成本 - 每个代理轮次都是一次 API 调用，而群聊可以产生多次轮次。控制成本的一些策略：

使用更便宜的模型来实现更简单的代理：并非每个代理都需要 GPT-4o。审稿人可能会使用较小的模型来很好地工作，而只有作者需要重磅模型。
限制历史记录：在执行设置中使用 ReducedHistoryCount 来限制每个代理接收的对话上下文数量。
设置严格的迭代限制：使用合理的 MaximumIterations 值防止失控对话。
尽可能缓存：如果代理重复执行相同的查找，则将结果缓存在插件中。

代理设计

保持指令集中：每个代理都应该有一个单一、明确的职责。宽泛的指令会导致所有任务的表现平庸。
明确输出格式：准确地告诉代理如何构建他们的响应。这使得下游解析可靠。
使用终止关键字：定义代理用来表明他们已完成的明确信号（例如“批准”或“完成”）。这使得终止策略变得简单且可预测。

结论

多智能体人工智能系统代表了我们构建智能应用程序方式的根本转变。我们可以将问题分解为专门的角色并让代理进行协作，而不是纠结于单一提示来处理所有事情。

Microsoft 的代理框架使这对于.NET 开发人员来说非常实用。抽象是干净的——代理、群聊、选择和终止策略——而且它们自然组成。结合语义内核的插件生态系统和 Azure 的模型托管，您将拥有用于构建生产级多代理系统的完整堆栈。

该框架仍在不断发展（许多包都处于预览状态），但核心模式很扎实，方向也很明确。如果您正在 .NET 中构建人工智能驱动的应用程序，那么现在是开始尝试多代理架构的时候了。

从小事做起——构建两个代理来协作完成一个简单的任务。一旦您看到单代理方法的质量改进，您就会希望将所有内容分解为代理团队。

快乐编码！

使用 MarkupString 在 Blazor 中渲染原始 HTML

Sat, 22 Nov 2025 00:00:00 +0000

有一天，我正在构建一个组件，需要渲染一些来自 CMS 的 HTML。我将 HTML 字符串放在一个变量中，然后将其放入模板中，例如 @myHtml。当然，Blazor 转义了所有内容并将实际标签呈现为页面上的文本。不是我想要的。

问题

默认情况下，Blazor 对您在模板中呈现的任何字符串进行编码。所以如果你有：

@code {
 private string content = "<strong>Hello</strong> <em>world</em>";
}

你这样做：

<div>@content</div>

您将在页面上看到文字文本 <strong>Hello</strong> <em>world</em>，而不是 Hello world。 Blazor 这样做的目的是为了防止 XSS 攻击，这是正确的默认行为。

解决方案：MarkupString

如果您确实需要渲染原始 HTML，请将字符串包装在 MarkupString 中：

<div>@((MarkupString)content)</div>

就是这样！现在 Blazor 会将 HTML 呈现为实际标记。您还可以将其分配给变量：

@code {
 private string rawHtml = "<strong>Hello</strong> <em>world</em>";
 private MarkupString HtmlContent => (MarkupString)rawHtml;
}

<div>@HtmlContent</div>

一个现实世界的例子

我从 API 中提取博客内容，并需要在预览组件中呈现它。内容包含各种 HTML——标题、代码块、链接、图像。大概是这样的：

@inject HttpClient Http

@if (article is not null)
{
 <article>
 <h1>@article.Title</h1>
 <div class="content">
 @((MarkupString)article.HtmlBody)
 </div>
 </article>
}

@code {
 [Parameter]
 public int ArticleId { get; set; }

 private ArticleDto? article;

 protected override async Task OnInitializedAsync()
 {
 article = await Http.GetFromJsonAsync<ArticleDto>($"api/articles/{ArticleId}");
 }
}

工作完美。来自 API 的 HTML 被呈现为实际标记。

小心不受信任的内容

这很重要：MarkupString 不会**清理 HTML。它会渲染您提供的任何内容，包括 <script> 标签。因此，如果内容来自用户输入或不受信任的来源，您需要首先对其进行清理。

Blazor 中没有内置的 HTML 清理程序，但您可以使用 HtmlSanitizer 等库：

using Ganss.Xss;

@code {
 private HtmlSanitizer sanitizer = new();

 private MarkupString SafeHtml(string html)
 {
 var clean = sanitizer.Sanitize(html);
 return (MarkupString)clean;
 }
}

<div>@SafeHtml(untrustedContent)</div>

这会去除危险元素，例如 <script>、onclick 处理程序以及您不希望从用户提供的内容中呈现的其他内容。

何时使用它

我使用 MarkupString 来：

CMS 内容或 markdown 已转换为 HTML 服务器端
富文本编辑器输出
电子邮件模板预览
来自可信来源的任何预构建 HTML

对于来自用户输入的任何内容，始终首先进行清理。安全总比后悔好。

希望你喜欢这篇文章！请随时通过任何社交媒体与我联系：@emimontesdeoca。

资源

EF Core 9 中的新增功能：您需要了解的功能

Tue, 18 Nov 2025 00:00:00 +0000

Entity Framework Core 9 于 2024 年 11 月与 .NET 9 一起发布，在花了大量时间在多个项目中使用它之后，我可以说它是一段时间内最有意义的版本之一。不是因为它重新发明了轮子，而是因为它完善了 EF Core 历史上造成最大摩擦的领域——查询翻译、性能以及使用现代数据模式。

在这篇文章中，我将介绍对我的日常工作影响最大的功能。如果您仍在使用 EF Core 8（甚至 7），这应该可以让您清楚地了解升级的另一边等待您的是什么。

.NET 9 生态系统中的 EF Core 9

EF Core 9 针对 .NET 8 和 .NET 9，这意味着您不一定需要将整个应用程序升级到 .NET 9 才能利用其中大部分功能。也就是说，一些 AOT 和性能改进与 .NET 9 运行时更改紧密结合，因此您可以通过一路走来充分利用它。

该版本遵循 Microsoft 制定的奇数/偶数节奏：奇数版本（如 .NET 9）是标准期限支持 (STS)，提供 18 个月的支持，而偶数版本（如 .NET 8）是长期支持 (LTS)。在规划升级时间表时请记住这一点。

LINQ 翻译改进

这是大多数开发人员会立即感受到差异的地方。 EF Core 9 在将 LINQ 表达式转换为真正有意义的 SQL 方面取得了重大进展。

更好的 GroupBy 翻译

如果您曾经在 EF Core 中编写过 GroupBy 查询并最终收到客户端评估警告或奇怪的 SQL，您就会知道这种痛苦。 EF Core 9 直接在 SQL 中处理更广泛的 GroupBy 场景。

var salesByCategory = await context.Products
 .GroupBy(p => p.Category.Name)
 .Select(g => new
 {
 Category = g.Key,
 TotalRevenue = g.Sum(p => p.Price * p.UnitsSold),
 AveragePrice = g.Average(p => p.Price),
 ProductCount = g.Count()
 })
 .OrderByDescending(x => x.TotalRevenue)
 .ToListAsync();

在以前的版本中，涉及 GroupBy 内导航属性聚合的查询有时会回退到客户端评估。 EF Core 9 将其干净地转换为具有 GROUP BY、SUM、AVG 和 COUNT 的单个 SQL 查询。

复杂的投影和子查询

嵌套子查询和复杂投影也得到了重大升级。考虑这样的事情：

var orderSummaries = await context.Customers
 .Select(c => new CustomerSummaryDto
 {
 Name = c.FullName,
 TotalOrders = c.Orders.Count(),
 MostRecentOrder = c.Orders
 .OrderByDescending(o => o.OrderDate)
 .Select(o => new OrderBriefDto
 {
 Id = o.Id,
 Date = o.OrderDate,
 Total = o.LineItems.Sum(li => li.Quantity * li.UnitPrice)
 })
 .FirstOrDefault(),
 TopCategory = c.Orders
 .SelectMany(o => o.LineItems)
 .GroupBy(li => li.Product.Category.Name)
 .OrderByDescending(g => g.Count())
 .Select(g => g.Key)
 .FirstOrDefault()
 })
 .ToListAsync();

EF Core 9 现在可以将整个表达式转换为 SQL，而无需触发客户端计算。生成的查询在适当的情况下使用相关子查询和横向联接，并且 SQL 计划比早期版本生成的计划要高效得多。

参数化原始集合

突出的 LINQ 改进之一是能够将原始值集合直接传递到查询中：

var statusFilter = new List<string> { "Active", "Pending", "Review" };

var filteredOrders = await context.Orders
 .Where(o => statusFilter.Contains(o.Status))
 .ToListAsync();

在 EF Core 8 中，这是使用带有内联值的 IN 子句进行转换的，这意味着列表更改时无法重用查询计划缓存。 EF Core 9 正确参数化这些集合，将它们作为结构化参数发送。这对于 SQL Server 和 PostgreSQL 上的查询计划缓存来说是一件大事。## 批量操作 — ExecuteUpdate 和 ExecuteDelete

ExecuteUpdate 和 ExecuteDelete 是在 EF Core 7 中引入的，但 EF Core 9 以有意义的方式扩展了您可以使用它们执行的操作。

更复杂的更新表达式

您现在可以在 ExecuteUpdate 中使用更复杂的表达式，包括通过导航属性引用其他表：

await context.Products
 .Where(p => p.Category.IsDiscontinued)
 .ExecuteUpdateAsync(setters => setters
 .SetProperty(p => p.IsAvailable, false)
 .SetProperty(p => p.DiscontinuedDate, DateTimeOffset.UtcNow)
 .SetProperty(p => p.Price, p => p.Price * 0.5m));

这会生成一个带有 JOIN 到类别表的 UPDATE 语句 — 不需要将实体加载到内存中，也没有更改跟踪开销。

使用子查询进行条件批量删除

现在完全支持使用子查询过滤器进行批量删除：

await context.AuditLogs
 .Where(log => log.CreatedAt < DateTime.UtcNow.AddYears(-2))
 .Where(log => !context.ProtectedRecords
 .Any(pr => pr.AuditLogId == log.Id))
 .ExecuteDeleteAsync();

这将转换为带有 NOT EXISTS 子查询的 DELETE，这正是您手写的内容。没有加载实体，没有往返。

JSON 列增强功能

JSON 列是最近 EF Core 版本中最令人兴奋的功能之一，而 EF Core 9 更进一步。

查询 JSON 内部

您现在可以通过更好的翻译支持从 JSON 列中过滤和投影数据：

public class Order
{
 public int Id { get; set; }
 public string CustomerName { get; set; }
 public ShippingAddress Address { get; set; } // Stored as JSON
 public List<OrderNote> Notes { get; set; } // Stored as JSON
}

public class ShippingAddress
{
 public string Street { get; set; }
 public string City { get; set; }
 public string State { get; set; }
 public string ZipCode { get; set; }
 public string Country { get; set; }
}

public class OrderNote
{
 public DateTime CreatedAt { get; set; }
 public string Text { get; set; }
 public string Author { get; set; }
}

您的 DbContext 中的配置：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Order>(builder =>
 {
 builder.OwnsOne(o => o.Address, ab =>
 {
 ab.ToJson();
 });

 builder.OwnsMany(o => o.Notes, nb =>
 {
 nb.ToJson();
 });
 });
}

现在您可以直接查询 JSON：

var newYorkOrders = await context.Orders
 .Where(o => o.Address.State == "NY")
 .OrderByDescending(o => o.Notes.Count)
 .Select(o => new
 {
 o.CustomerName,
 o.Address.City,
 LatestNote = o.Notes
 .OrderByDescending(n => n.CreatedAt)
 .Select(n => n.Text)
 .FirstOrDefault()
 })
 .ToListAsync();

EF Core 9 在 SQL Server（或其他提供程序上的等效项）上生成正确的 JSON_VALUE 和 JSON_QUERY 调用，并且转换涵盖了比以前更广泛的 JSON 元素 LINQ 操作。

更新 JSON 属性

EF Core 8 中的摩擦点之一是更新 JSON 列内的单个属性会导致整个 JSON 文档被重写。 EF Core 9 通过对 JSON 映射类型进行更精细的更改跟踪来改进这一点，并在可能的情况下生成更有针对性的更新。

var order = await context.Orders.FindAsync(orderId);
order.Address.ZipCode = "10001";
await context.SaveChangesAsync();

在受支持的提供程序上，这可以生成更有针对性的 JSON 修改，而不是重写整个 blob。

复杂类型——没有标识的值对象

复杂类型是领域驱动设计实践者一直在等待的功能之一。与自有类型不同，复杂类型没有身份——它们是纯值对象。

[ComplexType]
public record Money(decimal Amount, string Currency);

[ComplexType]
public record DateRange(DateTime Start, DateTime End);

public class Project
{
 public int Id { get; set; }
 public string Name { get; set; }
 public Money Budget { get; set; }
 public DateRange Timeline { get; set; }
}

这些作为平展列存储在父表中 - Budget_Amount、Budget_Currency、Timeline_Start、Timeline_End - 不需要单独的表或任何类型的键。

与自有类型的主要区别：复杂类型是按值比较，而不是按引用比较。具有相同 Amount 和 Currency 的两个 Money 实例被视为相等，无论它们属于哪个实体。

var expensiveProjects = await context.Projects
 .Where(p => p.Budget.Amount > 100_000m && p.Budget.Currency == "USD")
 .OrderByDescending(p => p.Budget.Amount)
 .ToListAsync();

这直接转化为对展平列的过滤——干净、高效，并且正是您所期望的。

SQL Server 的 HierarchyId 支持

如果您曾经使用过 SQL Server 中的分层数据（组织结构图、类别树、文件系统），您就会知道 HierarchyId 是其内置类型。 EF Core 9 为其带来了一流的支持。

public class Employee
{
 public int Id { get; set; }
 public string Name { get; set; }
 public string Title { get; set; }
 public HierarchyId PathFromCeo { get; set; }
}

现在可以直接查询层次关系：

var managerId = HierarchyId.Parse("/1/3/");

// All direct and indirect reports
var allReports = await context.Employees
 .Where(e => e.PathFromCeo.IsDescendantOf(managerId))
 .Where(e => e.PathFromCeo != managerId) // exclude the manager
 .OrderBy(e => e.PathFromCeo)
 .ToListAsync();

// Direct reports only (one level down)
var directReports = await context.Employees
 .Where(e => e.PathFromCeo.GetAncestor(1) == managerId)
 .ToListAsync();

// Get an employee's depth in the hierarchy
var employeesWithDepth = await context.Employees
 .Select(e => new
 {
 e.Name,
 e.Title,
 Level = e.PathFromCeo.GetLevel()
 })
 .OrderBy(e => e.Level)
 .ToListAsync();
```所有这些都转换为 SQL Server 的本机 `HierarchyId` 方法。如果您一直在使用自引用外键和递归 CTE 来实现树结构，那么这是一种更简洁的方法。

## 编译模型和 AOT 支持

注重性能的开发人员将欣赏对编译模型和提前 (AOT) 编译支持的持续投资。

### 编译模型

编译模型会预先生成 EF Core 通常在启动时构建的模型元数据。对于大型模型（考虑数百个实体），这可以显着减少冷启动时间。

```bash
dotnet ef dbcontext optimize --output-dir CompiledModels --namespace MyApp.CompiledModels

然后连线：

builder.Services.AddDbContext<AppDbContext>(options =>
 options
 .UseSqlServer(connectionString)
 .UseModel(MyApp.CompiledModels.AppDbContextModel.Instance));

在 EF Core 9 中，编译的模型更加完整 - 它们支持更多映射功能并生成更小的输出。对于具有大约 400 个实体的模型，启动时间可以从几秒缩短到接近瞬时。

AOT编译进度

对 EF Core 的完整本机 AOT 支持仍在进行中，但 EF Core 9 取得了重大进展。许多反射密集型代码路径已被重构为修剪友好型，编译模型是 AOT 故事的关键部分。如果你的目标是 Azure Functions 或微服务等冷启动很重要的场景，那么这些改进是直接相关的。

Cosmos DB 提供程序更新

Azure Cosmos DB 提供程序通过 EF Core 9 不断成熟。一些值得注意的改进：

分区键处理

该提供程序现在支持分层分区键并更智能地处理分区键过滤器：

public class TenantDocument
{
 public string Id { get; set; }
 public string TenantId { get; set; } // Partition key
 public string Region { get; set; } // Sub-partition key
 public string Content { get; set; }
}

// This query now correctly uses the partition key for routing
var docs = await context.TenantDocuments
 .Where(d => d.TenantId == "tenant-42" && d.Region == "us-east")
 .Where(d => d.Content.Contains("important"))
 .ToListAsync();

改进了 LINQ 到 NoSQL 的转换

更多 LINQ 操作现在转换为 Cosmos DB 的 SQL 方言，包括对 Contains、Any、嵌套数组操作和数学函数的更好支持。以前退回到客户端评估的查询现在由服务器端处理。

矢量搜索支持

EF Core 9 引入了对 Cosmos DB 向量相似性搜索的早期支持，如果您正在构建与嵌入或 AI 驱动的搜索集成的应用程序，这将非常有用：

var results = await context.Documents
 .OrderBy(d => EF.Functions.VectorDistance(d.Embedding, queryVector))
 .Take(10)
 .ToListAsync();

迁移改进

迁移带来了一些生活质量的改善，这使得在团队环境中与他们一起工作不再那么痛苦。

迁移中的时态表

迁移现在可以更优雅地处理时态表配置，并适当支持周期列和历史表命名：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Employee>()
 .ToTable("Employees", b => b.IsTemporal(t =>
 {
 t.HasPeriodStart("ValidFrom");
 t.HasPeriodEnd("ValidTo");
 t.UseHistoryTable("EmployeeHistory");
 }));
}

幂等脚本

默认情况下，Script-Migration 命令（及其 CLI 等效项）会生成更好的幂等脚本，并改进了对依赖于某些状态中存在的数据的模式更改的边缘情况的处理。

迁移包

迁移捆绑包将迁移打包成独立的可执行文件以进行部署，在 EF Core 9 中更加可靠，具有更好的错误报告和针对暂时性故障的重试逻辑。

dotnet ef migrations bundle --self-contained -r linux-x64

这会生成一个可以在 CI/CD 管道中运行的二进制文件，而无需在部署目标上安装 .NET SDK。

性能基准以下是我自己测试的一些粗略基准。这些来自一个包含大约 200 个实体的项目，针对 SQL Server 2022 运行，并使用 BenchmarkDotNet 进行测量。您的数字会有所不同，但相对改进应该相似。

场景	EF Core 8	EF Core 9	改进
模型构建（冷启动）	1,850 毫秒	320 毫秒	速度提高约 5.8 倍（编译）
简单查询（单实体PK）	0.42 毫秒	0.38 毫秒	快约 10%
复杂查询（连接+聚合）	3.1 毫秒	2.4 毫秒	快约 23%
批量更新（10k 行）	145 毫秒	118 毫秒	快约 19%
JSON列查询	2.8 毫秒	1.9 毫秒	快约 32%
SaveChanges（100 个实体）	48 毫秒	41 毫秒	快约 15%

编译模型的改进是最显着的，但全面的稳定改进加起来 - 特别是在每秒执行数千个查询的高吞吐量场景中。

从 EF Core 8 升级

如果您使用 EF Core 8，升级路径相对顺利。这是一个清单：

1.更新您的软件包：

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />

2.检查重大更改。 与某些以前的版本相比，EF Core 9 的列表相对较短。最值得注意的是：

一些以前过时的 API 已被删除
某些 GroupBy 查询的翻译方式发生变化（它们现在转到服务器端，如果您依赖客户端评估，这会改变行为）
迁移脚手架输出的微小变化

**3.如果您正在使用编译模型，请重新生成它们。格式已更改，因此旧的编译模型将无法与 EF Core 9 一起使用。

4.运行您的测试套件。 特别注意之前在客户端上评估的查询 - 它们现在可能在服务器上评估，这通常更好，但可能会出现数据差异。

5.如果您正在使用该提供商，请检查您的 Cosmos DB 查询。改进的翻译意味着某些查询将以不同的方式执行（通常更快），但值得验证结果是否相同。

典型项目的最小升级如下所示：

dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.0
dotnet build
dotnet test

如果一切都编译并且测试通过，那么您可能处于良好状态。如果您遇到问题，EF Core 9 重大更改文档为每个更改提供了详细的迁移指南。

总结

EF Core 9 不是一个革命性的版本 - 它是一个进化的版本，而这正是它所需要的。仅 LINQ 改进就足以证明大多数项目的升级是合理的，并且 JSON 列增强、复杂类型和 HierarchyId 等功能支持以前难以或不可能的开放模式。

如果我必须选择对我的项目影响最大的三个功能：

参数化原始集合 - 因为查询计划缓存效率在规模上很重要
JSON 列改进 — 因为混合关系文档模式非常有用
编译模型——因为启动时间直接影响开发人员的生产力和部署速度自 EF Core 5 以来，EF Core 团队一直走在坚实的轨道上，版本 9 延续了这一趋势。如果您已经使用 EF Core 8，则升级风险低、回报高。如果您正在使用较旧的产品，那么现在就是跳跃的最佳时机。

快乐的编码和快乐的查询。

语义内核入门：C# 中的 AI 编排

Sun, 05 Oct 2025 00:00:00 +0000

如果您一直在构建 .NET 应用程序并关注 AI 领域的发展，您可能想知道：将大型语言模型集成到我的 C# 项目中而不会将我的代码库变成意大利面条的最佳方法是什么？ 这正是 Microsoft 的语义内核解决的问题，在去年用它构建生产应用程序之后，我可以告诉您它已成为我的开发人员工具包中最重要的工具之一。

在这篇文章中，我将引导您完成开始使用语义内核所需的一切 - 从理解核心概念到构建现实世界的人工智能助手。无论您是刚刚涉足 AI 开发，还是正在寻找一种结构化方法来编排现有 .NET 应用程序中的 LLM 调用，本指南都能满足您的需求。

什么是语义内核？

Semantic Kernel (SK) 是 Microsoft 的开源 SDK，充当应用程序代码和大型语言模型（如 GPT-4o、Azure OpenAI 或其他 AI 服务）之间的编排层。将其视为一种轻量级中间件，可让您以干净、可组合的方式将传统 C# 代码与 AI 功能结合起来。

但为什么不直接调用 OpenAI API 呢？你绝对可以——对于简单的用例来说，这很好。但此时你需要：

让人工智能根据用户输入决定调用哪些函数
将多个人工智能调用与管道中的传统代码相结合
添加记忆和上下文，以便人工智能记住之前的交互
构建多步骤代理，通过复杂的任务进行推理

…你会发现自己在重新发明轮子。 Semantic Kernel 为您提供开箱即用的所有功能，具有一流的 .NET 支持、依赖项注入集成以及对任何 C# 开发人员来说都很自然的插件架构。

该项目位于 GitHub 上的 microsoft/semantic-kernel 存储库下，并具有适用于 C#、Python 和 Java 的 SDK。 C# SDK 是最成熟的，也是我们在此重点关注的。

核心概念

在编写任何代码之前，让我们先了解一下构建块。

内核

Kernel 是语义内核中的中心对象。它是协调器——将你的人工智能服务、插件和配置联系在一起的东西。您创建一个，在其上注册您的服务和插件，然后使用它来执行提示或调用函数。如果您熟悉 ASP.NET Core 中的依赖注入，那么内核会感觉非常熟悉——它本质上是一个具有 AI 超能力的服务容器。

插件和功能

插件是内核可以调用的相关函数的集合。函数有两种类型：

提示函数 — 定义为发送到 LLM 的自然语言模板
本机函数 — 用内核可以发现和调用的属性修饰的常规 C# 方法

例如，您可能有一个带有本机函数 GetCurrentWeather(string city) 的 WeatherPlugin 和一个以友好方式汇总天气数据的提示函数。### 人工智能连接器

连接器是语义内核与人工智能服务对话的方式。最常见的是：

AzureOpenAIChatCompletion — 用于 Azure OpenAI 服务
OpenAIChatCompletion — 直接用于 OpenAI 的 API
用于矢量搜索和存储的嵌入连接器

您在启动时将这些注册到内核上，其他一切都可以正常工作。

设置您的项目

让我们动手吧。首先创建一个新的控制台应用程序：

dotnet new console -n SemanticKernelDemo
cd SemanticKernelDemo

现在添加语义内核 NuGet 包：

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI

如果您直接使用 OpenAI 而不是 Azure OpenAI：

dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

对于内存和嵌入支持（我们稍后将使用它）：

dotnet add package Microsoft.SemanticKernel.Plugins.Memory
dotnet add package Microsoft.Extensions.VectorData.Abstractions

您的 .csproj 应面向 .NET 8 或更高版本。 Semantic Kernel 的最新版本充分利用了现代 .NET 功能。

你的第一个内核

让我们从最简单的示例开始 - 创建一个内核，将其连接到人工智能服务，并向其提出问题。

using Microsoft.SemanticKernel;

// Build the kernel with Azure OpenAI
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();

// Invoke a simple prompt
var result = await kernel.InvokePromptAsync(
 "Explain dependency injection in C# in three sentences."
);

Console.WriteLine(result);

如果您直接使用 OpenAI，请交换服务注册：

builder.AddOpenAIChatCompletion(
 modelId: "gpt-4o",
 apiKey: "your-openai-api-key"
);

就是这样。运行它，您将得到依赖注入的简明解释。但这只是表面现象。

使用提示模板

提示模板允许您使用 Handlebars 样式语法通过变量参数化提示：

var prompt = """
 You are a technical writer. Write a brief summary of {{$topic}}
 aimed at developers with {{$experienceLevel}} experience.
 Keep it under 200 words.
 """;

var function = kernel.CreateFunctionFromPrompt(prompt);

var arguments = new KernelArguments
{
 ["topic"] = "gRPC in .NET",
 ["experienceLevel"] = "intermediate"
};

var result = await kernel.InvokeAsync(function, arguments);
Console.WriteLine(result);

这就是语义内核开始发挥作用的地方 - 您可以定义可重用的提示模板，对其进行版本控制，并将它们组合成更大的工作流程。

插件和本机函数

插件是 Semantic Kernel 弥合 AI 和现有 C# 代码之间差距的地方。本机函数只是您向内核公开的常规方法。

using Microsoft.SemanticKernel;
using System.ComponentModel;

public class TimePlugin
{
 [KernelFunction("get_current_time")]
 [Description("Gets the current date and time in UTC")]
 public string GetCurrentTime()
 {
 return DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss UTC");
 }

 [KernelFunction("get_time_in_timezone")]
 [Description("Gets the current time in a specific timezone")]
 public string GetTimeInTimezone(
 [Description("The IANA timezone identifier, e.g. 'America/New_York'")] string timezone)
 {
 var tz = TimeZoneInfo.FindSystemTimeZoneById(timezone);
 var time = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
 return time.ToString("yyyy-MM-dd HH:mm:ss");
 }
}

请注意 [KernelFunction] 和 [Description] 属性。这些很重要——人工智能会读取描述来了解何时以及如何调用您的函数。良好的描述可以区分有效使用你的工具的人工智能和混乱的人工智能。

在您的内核上注册插件：

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();

var kernel = builder.Build();

您还可以构建更复杂的插件来注入服务。由于语义内核与 Microsoft.Extensions.DependencyInjection 集成，您的插件可以像任何其他服务一样接收构造函数依赖项：

public class OrderPlugin
{
 private readonly IOrderRepository _repository;

 public OrderPlugin(IOrderRepository repository)
 {
 _repository = repository;
 }

 [KernelFunction("get_order_status")]
 [Description("Retrieves the status of an order by its ID")]
 public async Task<string> GetOrderStatus(
 [Description("The order ID to look up")] string orderId)
 {
 var order = await _repository.GetByIdAsync(orderId);
 return order is null
 ? $"No order found with ID {orderId}"
 : $"Order {orderId}: {order.Status}, placed on {order.CreatedAt:d}";
 }
}

函数调用和自动调用

这就是事情变得非常有趣的地方。通过函数调用（也称为工具调用），您可以让 AI 模型根据对话上下文决定要调用哪些已注册的函数。该模型不执行代码 - 它返回一个结构化请求，表示“我想使用这些参数调用函数 X”，并且内核处理实际的调用。

以下是启用自动函数调用的方法：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();
builder.Plugins.AddFromType<WeatherPlugin>();

var kernel = builder.Build();

// Enable automatic function calling
var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

var result = await kernel.InvokePromptAsync(
 "What time is it in Tokyo and what's the weather like there?",
 new KernelArguments(settings)
);

Console.WriteLine(result);

使用 FunctionChoiceBehavior.Auto()，内核将：

将您的提示以及所有可用功能的描述发送给 AI
AI 决定需要调用 get_time_in_timezone 和 get_weather
内核自动执行那些函数 4.结果回传给AI
AI 使用函数结果组成自然语言响应这个循环可以在一次调用中发生多次——人工智能可能会按顺序调用多个函数来收集它需要的所有信息。您还可以使用 FunctionChoiceBehavior.Required() 强制 AI 调用至少一个函数，或提供允许使用的特定函数列表。

聊天完成与历史记录

对于会话应用程序，您需要直接将 ChatCompletionService 与 ChatHistory 对象一起使用：

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a helpful developer assistant. You have access to tools
 for checking the time and weather. Be concise and friendly.
 """);

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();
 if (string.IsNullOrWhiteSpace(input)) break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 history.AddAssistantMessage(response.Content ?? "");
 Console.WriteLine($"Assistant: {response.Content}");
}

这为您提供了一个完全交互式的聊天机器人，它可以维护对话历史记录并可以根据需要调用您的插件。

内存和嵌入

人工智能应用程序中最强大的模式之一是检索增强生成（RAG） - 通过将数据嵌入向量空间并在查询时检索相关块，让人工智能访问您自己的数据。

语义内核提供了用于向量存储和嵌入的抽象。以下是如何设置内存中向量存储以进行开发：

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.SemanticKernel.Embeddings;

#pragma warning disable SKEXP0010

// Create an embedding generation service
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-ada-002",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Generate embeddings for your documents
var documents = new[]
{
 "Semantic Kernel is an open-source SDK for AI orchestration.",
 "Azure OpenAI provides enterprise-grade AI models.",
 "Plugins in SK allow you to expose C# methods to AI models."
};

var embeddings = await embeddingService.GenerateEmbeddingsAsync(documents);

对于生产场景，您可以将这些嵌入存储在专用矢量数据库中，例如 Azure AI Search、Qdrant 或 Pinecone。语义内核通过 Microsoft.Extensions.VectorData 抽象提供了所有这些的连接器。

典型的 RAG 流程如下所示：

摄取：对文档进行分块，生成嵌入，将它们存储在矢量数据库中
检索：当用户提出问题时，嵌入查询并找到最相似的文档
生成：将检索到的文档作为上下文以及用户的问题传递给 LLM

[KernelFunction("search_knowledge_base")]
[Description("Searches the internal knowledge base for relevant information")]
public async Task<string> SearchKnowledgeBase(
 [Description("The search query")] string query)
{
 var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);

 var results = await _vectorStore.SearchAsync(queryEmbedding, limit: 3);

 return string.Join("\n\n", results.Select(r => r.Text));
}

通过将 RAG 管道公开为内核函数，人工智能可以自动决定何时需要搜索您的知识库 - 保持编排干净并让模型做它最擅长的事情。

策划者和代理人

随着您的人工智能应用程序变得越来越复杂，您将需要人工智能规划和执行多步骤任务。这就是语义内核代理框架的用武之地。

基础知识：聊天完成代理

最简单的代理类型使用指令和插件包装聊天完成模型：

using Microsoft.SemanticKernel.Agents;

#pragma warning disable SKEXP0110

var agent = new ChatCompletionAgent
{
 Name = "DevAssistant",
 Instructions = """
 You are a senior .NET developer assistant. Help users with code
 reviews, architecture decisions, and debugging. Always provide
 code examples when relevant. Use your available tools to look up
 current information when needed.
 """,
 Kernel = kernel,
 Arguments = new KernelArguments(settings)
};

var history = new ChatHistory();

history.AddUserMessage("How should I structure a clean architecture project in .NET 8?");

await foreach (var message in agent.InvokeAsync(history))
{
 Console.WriteLine(message.Content);
 history.Add(message);
}

多代理协作

当您有多个代理一起工作时，事情就会变得真正强大。语义内核支持群聊模式，其中不同专业的代理进行协作：

#pragma warning disable SKEXP0110

var codeReviewer = new ChatCompletionAgent
{
 Name = "CodeReviewer",
 Instructions = """
 You review C# code for bugs, performance issues, and best practices.
 Be specific about what you find and suggest concrete fixes.
 """,
 Kernel = kernel
};

var securityAuditor = new ChatCompletionAgent
{
 Name = "SecurityAuditor",
 Instructions = """
 You focus exclusively on security vulnerabilities in code.
 Look for injection attacks, authentication issues, data exposure,
 and OWASP Top 10 violations.
 """,
 Kernel = kernel
};

var groupChat = new AgentGroupChat(codeReviewer, securityAuditor)
{
 ExecutionSettings = new AgentGroupChatSettings
 {
 TerminationStrategy = new MaximumIterationTerminationStrategy(4)
 }
};

groupChat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User, "Review this code: ...")
);

await foreach (var message in groupChat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
}

这种模式对于需要权衡不同观点或专业领域的复杂任务非常有用。每个代理都使用自己的系统提示进行操作，并且可以拥有自己的一组插件。

真实示例：构建项目文档助手

让我们用一个实际的例子将所有内容联系在一起——一个人工智能助手，可以通过阅读文件和回答问题来帮助开发人员理解代码库。

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.ComponentModel;

// Define our plugins
public class FileSystemPlugin
{
 private readonly string _rootPath;

 public FileSystemPlugin(string rootPath)
 {
 _rootPath = rootPath;
 }

 [KernelFunction("read_file")]
 [Description("Reads the contents of a file from the project directory")]
 public async Task<string> ReadFile(
 [Description("Relative path to the file")] string path)
 {
 var fullPath = Path.Combine(_rootPath, path);

 if (!File.Exists(fullPath))
 return $"File not found: {path}";

 var content = await File.ReadAllTextAsync(fullPath);

 // Truncate very large files
 if (content.Length > 8000)
 content = content[..8000] + "\n... [truncated]";

 return content;
 }

 [KernelFunction("list_files")]
 [Description("Lists files in a directory, optionally filtered by extension")]
 public string ListFiles(
 [Description("Relative directory path")] string directory,
 [Description("File extension filter like '.cs' or '.json'")] string? extension = null)
 {
 var fullPath = Path.Combine(_rootPath, directory);

 if (!Directory.Exists(fullPath))
 return $"Directory not found: {directory}";

 var files = Directory.GetFiles(fullPath, "*.*", SearchOption.AllDirectories)
 .Select(f => Path.GetRelativePath(_rootPath, f))
 .Where(f => extension is null || f.EndsWith(extension))
 .Take(50);

 return string.Join("\n", files);
 }
}

public class DocumentationPlugin
{
 [KernelFunction("generate_summary")]
 [Description("Generates a structured markdown summary for documentation")]
 public string GenerateSummaryTemplate(
 [Description("Name of the component")] string componentName,
 [Description("Brief description")] string description,
 [Description("Key responsibilities as comma-separated values")] string responsibilities)
 {
 var items = responsibilities.Split(',', StringSplitOptions.TrimEntries);
 var bullets = string.Join("\n", items.Select(r => $"- {r}"));

 return $"""
 ## {componentName}

 {description}

 ### Responsibilities
 {bullets}

 ---
 *Generated documentation — review and expand as needed.*
 """;
 }
}

// Wire it all up
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromObject(new FileSystemPlugin("./src"));
builder.Plugins.AddFromType<DocumentationPlugin>();

var kernel = builder.Build();

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a codebase documentation assistant. You help developers understand
 projects by reading source files and explaining architecture, patterns,
 and design decisions.

 When asked about code, use your tools to read the actual files rather
 than guessing. Be specific and reference actual code when possible.
 Generate documentation artifacts when asked.
 """);

var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

Console.WriteLine("Documentation Assistant ready. Ask me about your codebase!");
Console.WriteLine("Type 'exit' to quit.\n");

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();

 if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
 break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 Console.WriteLine($"\nAssistant: {response.Content}\n");
 history.AddAssistantMessage(response.Content ?? "");
}

该助理可以：- 从项目目录中列出并读取文件

通过阅读实际的源文件来回答有关代码库的问题
生成 Markdown 格式的文档
维持对话上下文，以便后续问题自然有效

AI 根据您的要求自动决定何时调用 read_file、list_files 或 generate_summary。问它“OrderService 是做什么的？”它会读取文件，分析它并解释它。要求它“为身份验证模块生成文档”，它将探索文件、了解结构并生成格式化摘要。

制作技巧

在发布语义内核应用程序之前，我通过艰难的方式学到了一些东西：

正确使用依赖注入。 在 ASP.NET Core 应用程序中，在 DI 容器中注册内核和服务，而不是内联创建它们：

builder.Services.AddKernel()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: configuration["AzureOpenAI:Endpoint"]!,
 apiKey: configuration["AzureOpenAI:ApiKey"]!
 )
 .Plugins.AddFromType<TimePlugin>()
 .AddFromType<OrderPlugin>();

妥善处理错误。 LLM 调用可能会失败、超时或返回意外结果。将您的调用包装在 try-catch 块中，并使用 Polly 或内置弹性功能实施重试策略。

监控token使用情况。 每一个提示、每一个功能描述、每一条聊天记录都会消耗token。使用过滤器来记录和跟踪使用情况：

kernel.FunctionInvocationFilters.Add(new LoggingFilter());

**保持函数描述准确。**模糊的描述会导致AI错误地调用函数。通过询问以下问题来测试您的描述：“如果我只阅读描述，我能准确地知道何时以及如何使用此功能吗？”

结论

语义内核是从根本上改变您构建应用程序的想法的库之一。它不仅仅是一个 API 包装器，它还是一个编排框架，可让您以可维护、可测试和生产就绪的方式将 AI 功能与传统代码组合在一起。

我最喜欢它的是它尊重 .NET 生态系统。它使用您已经知道的模式——依赖注入、属性、异步/等待、接口——并将它们扩展到人工智能世界。您不必学习全新的范式；您只需将人工智能添加为工具包中的另一项功能即可。

如果您正在构建 .NET 应用程序并且尚未探索语义内核，那么现在正是时候。 SDK 稳定，社区活跃，其支持的模式（从简单的提示编排到多代理协作）正在成为现代开发人员的基本技能。

从小处开始。创建一个内核，注册一个插件，然后观看 AI 调用您的代码。一旦点击，您将开始看到在应用程序中随处添加智能的机会。

官方文档和 GitHub 存储库是继续您的旅程的优秀资源。快乐建设！

Blazor 中的继承组件

Thu, 04 Sep 2025 00:00:00 +0000

我正在构建一个具有一堆表单页面的项目，每个表单页面都有相同的加载状态逻辑、相同的错误处理和相同的 toast 通知。复制粘贴所有这些感觉都是错误的，因此我研究了 Blazor 中的组件继承。事实证明，这非常简单，因为 Blazor 组件只是 C# 类。

基础知识

默认情况下，每个 Blazor 组件都继承自 ComponentBase。您可以创建自己的扩展 ComponentBase 的基类，然后让您的组件继承它。

假设我们的大多数页面都需要加载状态和错误处理。我们可以创建一个基类：

using Microsoft.AspNetCore.Components;

public abstract class PageBase : ComponentBase
{
 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected async Task LoadDataAsync(Func<Task> action)
 {
 try
 {
 IsLoading = true;
 ErrorMessage = null;
 await action();
 }
 catch (Exception ex)
 {
 ErrorMessage = ex.Message;
 }
 finally
 {
 IsLoading = false;
 StateHasChanged();
 }
 }
}

使用基类

现在在任何页面组件中，我们不是从 ComponentBase 继承，而是从 PageBase 继承：

@page "/users"
@inherits PageBase

@if (IsLoading)
{
 <div class="spinner"></div>
}
else if (ErrorMessage is not null)
{
 <div class="alert alert-danger">@ErrorMessage</div>
}
else
{
 <ul>
 @foreach (var user in users)
 {
 <li>@user.Name</li>
 }
 </ul>
}

@code {
 private List<User> users = new();

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 users = await Http.GetFromJsonAsync<List<User>>("api/users");
 });
 }
}

@inherits PageBase 指令是关键。它告诉 Blazor 使用我们的基类而不是默认的 ComponentBase。现在，我们在继承它的每个页面中免费获得 IsLoading、ErrorMessage 和 LoadDataAsync()。

在基类中注入服务

您还可以在基类中注入服务，以便所有子组件都可以使用它们：

public abstract class PageBase : ComponentBase
{
 [Inject]
 protected NavigationManager Navigation { get; set; } = default!;

 [Inject]
 protected IToastService Toast { get; set; } = default!;

 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected void NavigateBack() => Navigation.NavigateTo("javascript:history.back()");

 protected void ShowSuccess(string message) => Toast.ShowSuccess(message);
}

从 PageBase 继承的每个组件现在都可以访问 Navigation、Toast、NavigateBack() 和 ShowSuccess()，而无需注入任何内容。

深入了解通用基类

您甚至可以为常见的 CRUD 模式创建通用基类：

public abstract class CrudPageBase<T> : PageBase
{
 protected List<T> Items { get; set; } = new();
 protected T? SelectedItem { get; set; }

 protected abstract Task<List<T>> FetchItems();
 protected abstract Task DeleteItem(T item);

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 Items = await FetchItems();
 });
 }

 protected async Task OnDelete(T item)
 {
 await LoadDataAsync(async () =>
 {
 await DeleteItem(item);
 Items = await FetchItems();
 ShowSuccess("Item deleted.");
 });
 }
}

然后你的实际页面变得超级干净：

@page "/products"
@inherits CrudPageBase<Product>

@* just the markup, all logic lives in the base class *@

@code {
 protected override Task<List<Product>> FetchItems()
 => Http.GetFromJsonAsync<List<Product>>("api/products");

 protected override Task DeleteItem(Product item)
 => Http.DeleteAsync($"api/products/{item.Id}");
}

何时使用、何时不使用

组件继承非常适合共享行为，例如加载状态、错误处理、身份验证检查或 CRUD 模式。但不要过度使用深层继承层次结构 - 如果您发现自己的深度超过两层，那么组合可能会更好（就像上一篇文章中的 LoadingComponent 方法）。

我通常将其保留为每个“类型”页面的一个基类：PageBase 用于常规页面，FormPageBase 用于表单，仅此而已。

希望你喜欢这篇文章！请随时通过任何社交媒体与我联系：@emimontesdeoca。

资源

ASP.NET Core Razor 组件继承

.NET Aspire：以正确的方式构建云原生应用程序

Wed, 20 Aug 2025 00:00:00 +0000

如果您曾经在 .NET 中构建过分布式应用程序，那么您就知道该怎么做。您启动一个 Web API，添加一个后台工作程序，添加 Redis 进行缓存，使用 PostgreSQL 进行持久化，也许使用 RabbitMQ 进行消息传递 — 突然之间，您花在连接基础设施上的时间比编写业务逻辑的时间还多。连接字符串分散在 appsettings.json 文件中，您忘记配置的运行状况检查，可观察性始终是“下一个冲刺的问题”。

我去过那里。比我愿意承认的次数还要多。

这正是 .NET Aspire 旨在解决的问题。在生产中运行了几个月后，我想分享我所学到的东西——好的、伟大的和陷阱。

什么是 .NET Aspire？

.NET Aspire 是一个固执己见的堆栈，用于使用 .NET 构建可观察的、可用于生产的分布式应用程序。它不是传统意义上的框架 - 它不会取代 ASP.NET Core 或强迫您采用新的编程模型。相反，它建立在您已知的知识之上，并填补了构建云原生应用程序时一直存在的空白。

Aspire 的核心为您提供四件事：

AppHost — 定义整个分布式应用程序拓扑的项目。存在哪些服务、它们依赖什么以及它们如何连接。
服务默认值 — 一个共享项目，可为您的所有服务一次性配置健康检查、弹性策略和 OpenTelemetry 等横切关注点。
组件 — NuGet 包，提供与 Redis、PostgreSQL、RabbitMQ、Azure 存储等支持服务的标准化集成。
开发人员仪表板 — 一个实时 UI，显示本地开发期间整个分布式应用程序的日志、跟踪和指标。

这个理念很简单：如果每个 .NET 云应用程序都需要这些东西，为什么我们每次都从头开始实现它们？

设置您的第一个 Aspire 项目

入门非常简单。您需要 .NET 8 或更高版本并安装 Aspire 工作负载：

dotnet workload update
dotnet workload install aspire

现在创建一个新的 Aspire 入门项目：

dotnet new aspire-starter -n MyCloudApp

这会生成一个包含四个项目的解决方案：

MyCloudApp.AppHost — 协调器
MyCloudApp.ServiceDefaults — 共享配置
MyCloudApp.ApiService — 示例 Web API
MyCloudApp.Web — Blazor 前端

运行 AppHost，您将立即看到 Aspire 仪表板在浏览器中打开，显示您的所有服务、日志及其运行状况。没有 Docker Compose 文件。无需手动端口管理。它就是有效的。

dotnet run --project MyCloudApp.AppHost

第一次经历让我着迷。不到一分钟的时间，您就拥有了一个完全精心编排的分布式应用程序，并且具有可观察性。

AppHost 模式

AppHost 是神奇之处。它是一个小型控制台应用程序，使用构建器模式来定义分布式应用程序的拓扑 - 存在哪些资源以及服务如何连接到它们。

现实的 AppHost 是这样的：

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var postgres = builder.AddPostgres("postgres")
 .WithPgAdmin()
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache");

var rabbitmq = builder.AddRabbitMQ("messaging")
 .WithManagementPlugin();

// Application services
var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReference(rabbitmq);

var orderApi = builder.AddProject<Projects.OrderApi>("order-api")
 .WithReference(postgres)
 .WithReference(rabbitmq);

var frontend = builder.AddProject<Projects.WebFrontend>("frontend")
 .WithExternalHttpEndpoints()
 .WithReference(catalogApi)
 .WithReference(orderApi);

builder.Build().Run();
```大声读出该代码。它实际上记录了自己。 “目录 API 引用了 PostgreSQL、Redis 和 RabbitMQ。前端引用了目录 API 和订单 API。”这就是您的架构，用代码表达。

有几点值得注意：

- **`WithReference`** 承担繁重的工作。它通过环境变量和配置自动将连接字符串和服务 URL 注入到使用项目中。您的服务不需要知道 Redis 在“哪里”运行 — Aspire 会处理它。
- **`WithPgAdmin()`** 和 **`WithManagementPlugin()`** 在实际服务旁边启动 PostgreSQL 和 RabbitMQ 的管理 UI。在开发过程中，这些都是无价的。
- **`WithExternalHttpEndpoints()`** 将服务标记为可外部访问，这在部署时很重要。

### 资源配置

您可以通过细粒度控制来配置资源：

```csharp
var postgres = builder.AddPostgres("postgres")
 .WithEnvironment("POSTGRES_MAX_CONNECTIONS", "200")
 .WithDataVolume("postgres-data")
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache")
 .WithDataVolume("redis-data");

数据量确保您的本地开发数据在容器重新启动后仍然存在。小细节，大生活质量改善。

服务默认值：无名英雄

ServiceDefaults 项目是 Aspire 最被低估的部分。它是一个共享库，解决方案中的每个服务都会引用它，并且它配置了您可能会忘记或不一致实现的所有横切关注点。

ServiceDefaults 中的典型 Extensions.cs 如下所示：

public static class Extensions
{
 public static IHostApplicationBuilder AddServiceDefaults(
 this IHostApplicationBuilder builder)
 {
 builder.ConfigureOpenTelemetry();
 builder.AddDefaultHealthChecks();
 builder.Services.AddServiceDiscovery();

 builder.Services.ConfigureHttpClientDefaults(http =>
 {
 http.AddStandardResilienceHandler();
 http.AddServiceDiscovery();
 });

 return builder;
 }

 public static IHostApplicationBuilder ConfigureOpenTelemetry(
 this IHostApplicationBuilder builder)
 {
 builder.Logging.AddOpenTelemetry(logging =>
 {
 logging.IncludeFormattedMessage = true;
 logging.IncludeScopes = true;
 });

 builder.Services.AddOpenTelemetry()
 .WithMetrics(metrics =>
 {
 metrics.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddRuntimeInstrumentation();
 })
 .WithTracing(tracing =>
 {
 tracing.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddGrpcClientInstrumentation();
 });

 builder.AddOpenTelemetryExporters();
 return builder;
 }

 public static IHostApplicationBuilder AddDefaultHealthChecks(
 this IHostApplicationBuilder builder)
 {
 builder.Services.AddHealthChecks()
 .AddCheck("self", () => HealthCheckResult.Healthy(),
 ["live"]);

 return builder;
 }
}

然后在每个服务的 Program.cs 中，一行就完成了这一切：

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// Your service-specific configuration...

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

单个 AddServiceDefaults() 调用将为您提供：

OpenTelemetry 具有结构化日志记录、指标和分布式跟踪
健康检查以及活性和就绪端点
服务发现，以便服务可以通过名称找到彼此
针对所有传出 HTTP 调用的弹性策略（重试、断路器、超时）

这是将“在我的机器上运行”演示与生产就绪系统区分开来的东西。 Aspire 将其设为默认设置，而不是事后添加。

Aspire 组件

Aspire 组件是 NuGet 包，可标准化您的服务连接到支持基础设施的方式。它们不仅仅是客户端库，还包括运行状况检查、日志记录、跟踪和开箱即用的可配置弹性。

Redis

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddRedisDistributedCache("cache");

就是这样。连接字符串通过 WithReference 来自 AppHost。该组件注册由 Redis 支持的 IDistributedCache，并已连接健康检查和 OpenTelemetry 仪器。

您还可以使用 Redis 进行输出缓存：

builder.AddRedisOutputCache("cache");

带有 Entity Framework Core 的 PostgreSQL

builder.AddNpgsqlDbContext<CatalogDbContext>("catalogdb", settings =>
{
 settings.DisableRetry = false;
});

这会将您的 DbContext 注册为与 AppHost 中定义的 catalogdb 数据库的连接。它包括连接池、健康检查和重试策略。

RabbitMQ

builder.AddRabbitMQClient("messaging");

从 RabbitMQ 客户端库注册 IConnection，已完全配置并进行运行状况检查。

Azure 集成

Aspire 还拥有用于 Azure 服务的一流组件：

// Azure Blob Storage
builder.AddAzureBlobClient("blobs");

// Azure Service Bus
builder.AddAzureServiceBusClient("servicebus");

// Azure Key Vault
builder.AddAzureKeyVaultClient("secrets");
```模式始终相同：AppHost 中的一行用于定义资源，消费服务中的一行用于使用它。连接详细信息会自动流动。

## 开发者仪表板

Aspire 仪表板是那些看起来很不错的功能之一，直到您真正使用它为止，然后您就无法想象没有它会如何工作。

当您在本地运行 AppHost 时，仪表板将启动并为您提供：

- **资源概览** — 您的所有服务和基础设施一目了然，并带有状态指示器
- **结构化日志** — 来自每个服务的实时日志流，可过滤和可搜索
- **分布式跟踪** - 跨越多个服务的端到端请求跟踪，可视化为火焰图
- **指标** — 实时 HTTP 请求率、错误率、延迟和自定义指标
- **控制台日志** - 来自每个容器和项目的原始 stdout/stderr

分布式追踪尤其有价值。当请求到达您的前端、流经目录 API、触及 Redis 和 PostgreSQL 时，您会看到整个链以及每个跃点的时间。不再猜测瓶颈在哪里。

我发现仪表板在调试过程中最有用。一切都集中在一处，并通过关联 ID 跨服务链接相关事件，而不是跟踪多个终端窗口或在日志文件之间跳转。

仪表板还可以作为独立容器使用，这意味着您可以在临时环境或 CI 管道中使用它：

```bash
docker run --rm -p 18888:18888 \
 mcr.microsoft.com/dotnet/aspire-dashboard:latest

部署

Aspire 在开发过程中有所帮助，但在生产过程中呢？这就是事情变得实用的地方。

Azure 容器应用程序

最直接的部署路径是 Azure 容器应用程序 (ACA)，它具有一流的 Aspire 支持。您可以直接使用 Azure 开发人员 CLI 进行部署：

azd init
azd up

azd init 命令检测您的 Aspire AppHost 并生成必要的基础设施即代码。 azd up 根据您的 AppHost 拓扑提供一切内容 — 容器注册表、容器应用程序、数据库、Redis 实例。

您的 AppHost 本质上成为您的部署清单。定义“catalog-api 依赖于 PostgreSQL 和 Redis”的相同代码驱动基础设施配置。

库伯内特斯

对于 Kubernetes 部署，Aspire 不会直接生成清单，但您的 AppHost 拓扑会清晰地映射到 Kubernetes 资源。社区工具 aspirate (Aspir8) 可以从您的 AppHost 生成 Helm 图表或 Kubernetes 清单：

dotnet tool install -g aspirate
aspirate generate
aspirate apply

部署注意事项

需要记住以下几点：- 连接字符串在环境之间发生变化。 在本地，Aspire 会启动容器并自动注入连接字符串。在生产中，您将指向托管服务。 Aspire 使用标准 .NET 配置，因此环境变量和 Azure Key Vault 按预期工作。

AppHost 不在生产环境中运行。 它是一个开发和部署编排工具。在生产中，您的服务独立运行，通过环境变量和协调器进行配置。
基础设施资源成为托管服务。 您的本地 PostgreSQL 容器成为 Azure Database for PostgreSQL。本地 Redis 容器将成为 Azure Redis 缓存。消费代码不会改变。

现实世界的技巧

在生产中运行 Aspire 一段时间后，以下是节省我们时间的经验教训：

1. 使用自定义资源生命周期检查

不要仅仅依靠容器启动来确定资源是否准备好。 PostgreSQL 可能会在实际准备好提供查询服务之前接受 TCP 连接。

var postgres = builder.AddPostgres("postgres")
 .AddDatabase("catalogdb")
 .WithHealthCheck();

Aspire 可以对资源运行运行状况检查并保留相关服务，直到它们真正准备好为止。

2. 将常见模式提取到扩展中

如果多个服务共享相似的配置，请创建扩展方法：

public static class AppHostExtensions
{
 public static IResourceBuilder<ProjectResource> AddWorkerService(
 this IDistributedApplicationBuilder builder,
 string name,
 IResourceBuilder<IResourceWithConnectionString> db,
 IResourceBuilder<IResourceWithConnectionString> messaging)
 {
 return builder.AddProject<Projects.WorkerService>(name)
 .WithReference(db)
 .WithReference(messaging)
 .WithReplicas(3);
 }
}

3. 利用 WithReplicas 进行负载测试

var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReplicas(5);

WithReplicas 在本地启动服务的多个实例。这非常适合测试负载平衡、并发错误和分布式缓存行为，而无需部署到集群。

4. 对敏感值使用参数

即使对于本地开发，也不要硬编码凭据：

var dbPassword = builder.AddParameter("db-password", secret: true);

var postgres = builder.AddPostgres("postgres", password: dbPassword)
 .AddDatabase("catalogdb");

在本地运行时，Aspire 将提示输入该值或从用户机密中读取该值。在 CI/CD 中，它来自环境变量。

5. 集成测试变得微不足道

Aspire 包含一个测试包，可以使分布式应用程序的集成测试变得非常简单：

[Fact]
public async Task CatalogApiReturnsProducts()
{
 var appHost = await DistributedApplicationTestingBuilder
 .CreateAsync<Projects.MyCloudApp_AppHost>();

 await using var app = await appHost.BuildAsync();
 await app.StartAsync();

 var httpClient = app.CreateHttpClient("catalog-api");
 var response = await httpClient.GetAsync("/api/products");

 response.EnsureSuccessStatusCode();

 var products = await response.Content
 .ReadFromJsonAsync<List<Product>>();
 Assert.NotEmpty(products);
}

这会启动您的“整个”分布式应用程序（包括数据库和消息代理），针对它运行测试，然后将其拆除。在 CI 管道中针对真实基础设施进行真正的集成测试。没有嘲笑。

6. 本地监控资源使用情况

在本地运行多个容器时，请密切关注资源消耗。具有管理 UI 的 PostgreSQL、Redis 和 RabbitMQ 实例可以轻松消耗 2-3 GB RAM。如果您使用的是受限计算机，请考虑使用较轻的资源配置：

var redis = builder.AddRedis("cache")
 .WithContainerRuntimeArgs("--memory=256m");

结论

.NET Aspire 从根本上改变了我构建分布式应用程序的方式。并不是因为它引入了革命性的概念——健康检查、OpenTelemetry 和容器编排并不是什么新鲜事。但因为它使它们成为“默认”。它需要您通常必须做出的数百个小决定，使用合理的默认值来实现它们，并允许您在需要时覆盖它们。在我看来，AppHost 模式是最大的胜利。将分布式应用程序拓扑表示为代码（而不是分散在 Docker Compose 文件、Kubernetes 清单和 README 文档中）使系统易于理解。新团队成员可以在AppHost中打开Program.cs并在几分钟内了解整个架构。

如果您正在使用 .NET 构建分布式应用程序，请认真考虑一下 Aspire。从 aspire-starter 模板开始，探索仪表板，并根据需要逐步采用组件。您不必在第一天就全力以赴——Aspire 的设计就是附加的。

花费第一次冲刺来连接基础设施样板的日子已经结束了。让 Aspire 处理管道，以便您可以专注于真正重要的事情：您的应用程序。

Blazor 中的身份验证和授权：实用指南

Sat, 12 Jul 2025 00:00:00 +0000

如果您使用过 ASP.NET MVC 或 Razor Pages，您可能对身份验证的工作原理有一个心理模型：中间件拦截请求，检查 cookie 或令牌，填充 HttpContext.User，然后您就可以开始比赛了。 Blazor 以微妙但重要的方式改变了这种心理模型 - 如果您不尽早理解这些差异，您最终会调试感觉不可能的身份验证问题。

在这篇文章中，我想介绍 Blazor 中身份验证和授权的实际工作原理，涵盖服务器和 WebAssembly 托管模型。我们将从基础知识一直讲到自定义提供程序、外部 OAuth 以及我所看到的甚至经验丰富的 .NET 开发人员也会遇到的陷阱。

为什么 Blazor 中的身份验证不同

在传统的 ASP.NET 中，每个用户交互都是一个 HTTP 请求。服务器验证凭据，设置 cookie，并且每个后续请求都携带该 cookie。身份验证管道是线性且可预测的。

Blazor 服务器通过持久 SignalR 连接运行。初始 HTTP 请求加载页面后，所有后续交互都通过 WebSocket 进行。每次单击按钮都不会产生新的 HTTP 请求，因此中间件不会在每次交互时重新执行。 HttpContext 在初始连接期间可用，但在电路的整个生命周期中依赖它会导致错误。

Blazor WebAssembly 完全在浏览器中运行。根本没有服务器端 HttpContext。身份验证状态必须从 API 获取、存储在客户端，并通过令牌（通常是 JWT）进行管理。服务器仅在令牌验证进行时才信任客户端。

这意味着 Blazor 需要自己的身份验证状态抽象，无论托管模型如何，该抽象都可以工作。这个抽象就是 AuthenticationStateProvider。

身份验证状态：基金会

Blazor 身份验证系统的核心是 AuthenticationStateProvider。这是一个抽象类，公开了一个关键方法：

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

AuthenticationState 对象包装了 ClaimsPrincipal — 整个 .NET 使用的相同身份模型。组件不直接与 cookie 或令牌对话；他们向 AuthenticationStateProvider 询问当前状态。

为了使此状态可用于整个组件树，Blazor 提供了 CascadingAuthenticationState。您通常将路由器包裹在 App.razor 或您的布局中：

<CascadingAuthenticationState>
 <Router AppAssembly="@typeof(App).Assembly">
 <Found Context="routeData">
 <AuthorizeRouteView RouteData="@routeData"
 DefaultLayout="@typeof(MainLayout)">
 <NotAuthorized>
 <p>You're not authorized to view this page.</p>
 </NotAuthorized>
 </AuthorizeRouteView>
 </Found>
 <NotFound>
 <LayoutView Layout="@typeof(MainLayout)">
 <p>Page not found.</p>
 </LayoutView>
 </NotFound>
 </Router>
</CascadingAuthenticationState>

AuthorizeRouteView 在这里承担双重职责：它在呈现匹配的页面组件之前检查用户是否经过身份验证和授权，并在未经过身份验证和授权时提供后备 UI。

在具有统一 Blazor 模型的 .NET 8 及更高版本中，您将在 App.razor 中进行配置，并且当您在服务注册中使用 AddCascadingAuthenticationState() 时，框架会自动处理级联参数。

ASP.NET 身份集成

对于大多数项目，您不需要从头开始构建身份验证。 ASP.NET Identity 为您提供开箱即用的用户管理、密码哈希、双因素身份验证和帐户确认。使用 Blazor 进行设置从 Program.cs 开始：

builder.Services.AddDbContext<ApplicationDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddDefaultIdentity<IdentityUser>(options =>
 {
 options.SignIn.RequireConfirmedAccount = true;
 options.Password.RequireDigit = true;
 options.Password.RequiredLength = 8;
 })
 .AddRoles<IdentityRole>()
 .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddAuthentication(options =>
 {
 options.DefaultScheme = IdentityConstants.ApplicationScheme;
 options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
 });

通过 .NET 8+ 中的 Blazor Web App 模板，脚手架的 Identity UI 直接使用 Razor 组件。您将获得与 Blazor 应用程序的其余部分自然集成的登录、注册和帐户管理页面，不再需要 Razor 页面和 Blazor 组件的尴尬组合。

ApplicationDbContext 继承自 IdentityDbContext，您需要运行迁移来创建身份表：

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
 public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
 : base(options) { }
}

dotnet ef migrations add InitialIdentity
dotnet ef database update

AuthorizeView 组件

一旦身份验证状态流经组件树，AuthorizeView 就可以让您有条件地渲染 UI：

<AuthorizeView>
 <Authorized>
 <p>Welcome, @context.User.Identity?.Name!</p>
 <a href="/account/manage">Manage Account</a>
 <form method="post" action="/account/logout">
 <button type="submit">Log Out</button>
 </form>
 </Authorized>
 <NotAuthorized>
 <a href="/account/login">Log In</a>
 <a href="/account/register">Register</a>
 </NotAuthorized>
</AuthorizeView>

<Authorized> 内的 context 参数使您可以访问 AuthenticationState，因此您可以直接在标记中检查声明、角色和用户身份。

您还可以将 AuthorizeView 与角色和策略一起使用：

<AuthorizeView Roles="Admin,Moderator">
 <Authorized>
 <button @onclick="DeletePost">Delete Post</button>
 </Authorized>
</AuthorizeView>

<AuthorizeView Policy="CanEditArticles">
 <Authorized>
 <button @onclick="EditArticle">Edit</button>
 </Authorized>
</AuthorizeView>

要记住一件事：AuthorizeView 是 UI 问题。它隐藏或显示元素，但不保护底层逻辑。如果有人可以直接调用您的 API 端点或调用您的方法，他们将完全绕过 AuthorizeView。始终在服务器端强制执行授权。

[授权] 属性

要保护整个页面，请应用 [Authorize] 属性：

@page "/admin/dashboard"
@attribute [Authorize(Roles = "Admin")]

<h1>Admin Dashboard</h1>
<p>Only administrators can see this page.</p>

当未经身份验证的用户导航到此页面时，AuthorizeRouteView 启动并呈现您之前定义的 <NotAuthorized> 模板。您可以通过使用导航处理 NotAuthorized 情况来重定向到登录页面：

<NotAuthorized>
 @if (!context.User.Identity?.IsAuthenticated ?? true)
 {
 <RedirectToLogin />
 }
 else
 {
 <p>You don't have permission to access this page.</p>
 }
</NotAuthorized>

一个简单的 RedirectToLogin 组件可能如下所示：

@inject NavigationManager Navigation

@code {
 protected override void OnInitialized()
 {
 var returnUrl = Uri.EscapeDataString(Navigation.Uri);
 Navigation.NavigateTo($"/account/login?returnUrl={returnUrl}", forceLoad: true);
 }
}

forceLoad: true 在这里很重要 - 您需要一个实际的 HTTP 导航，以便服务器端身份验证中间件可以正确处理登录流程。

基于角色和基于策略的授权

角色是最简单的模型：将用户分配到“管理员”或“编辑者”等组，然后检查成员资格。但政策给了你更大的灵活性。

在 Program.cs 中注册策略：

builder.Services.AddAuthorizationCore(options =>
{
 options.AddPolicy("CanPublish", policy =>
 policy.RequireClaim("Permission", "Publish"));

 options.AddPolicy("MinimumAge", policy =>
 policy.Requirements.Add(new MinimumAgeRequirement(18)));

 options.AddPolicy("PremiumUser", policy =>
 policy.RequireRole("Premium")
 .RequireClaim("Subscription", "Active"));
});

自定义需求需要一个处理程序：

public class MinimumAgeRequirement : IAuthorizationRequirement
{
 public int MinimumAge { get; }
 public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
}

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context,
 MinimumAgeRequirement requirement)
 {
 var dateOfBirthClaim = context.User.FindFirst("DateOfBirth");

 if (dateOfBirthClaim is null)
 return Task.CompletedTask;

 var dateOfBirth = DateOnly.Parse(dateOfBirthClaim.Value);
 var age = DateOnly.FromDateTime(DateTime.Today).Year - dateOfBirth.Year;

 if (age >= requirement.MinimumAge)
 context.Succeed(requirement);

 return Task.CompletedTask;
 }
}

注册处理程序：

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

在组件中，当需要动态逻辑时，您还可以通过编程方式检查授权：

@inject IAuthorizationService AuthorizationService
@inject AuthenticationStateProvider AuthStateProvider

@code {
 private bool canPublish;

 protected override async Task OnInitializedAsync()
 {
 var authState = await AuthStateProvider.GetAuthenticationStateAsync();
 var result = await AuthorizationService.AuthorizeAsync(
 authState.User, "CanPublish");
 canPublish = result.Succeeded;
 }
}

外部 OAuth 提供商

使用 ASP.NET 身份验证中间件，支持“使用 Google 登录”或“使用 GitHub 登录”非常简单。这些是在服务器端配置的，因为 OAuth 流程需要 HTTP 重定向。

builder.Services.AddAuthentication()
 .AddGoogle(options =>
 {
 options.ClientId = builder.Configuration["Auth:Google:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Google:ClientSecret"]!;
 options.Scope.Add("profile");
 })
 .AddMicrosoftAccount(options =>
 {
 options.ClientId = builder.Configuration["Auth:Microsoft:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Microsoft:ClientSecret"]!;
 })
 .AddGitHub(options =>
 {
 options.ClientId = builder.Configuration["Auth:GitHub:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:GitHub:ClientSecret"]!;
 });

对于 GitHub，您需要 AspNet.Security.OAuth.GitHub NuGet 包，因为它不包含在默认 ASP.NET 库中。

然后，登录 UI 会提供触发外部质询的链接：

@page "/account/external-login"

<h2>Sign in with an external provider</h2>

<form method="post" action="/api/auth/external-login">
 <button type="submit" name="provider" value="Google">
 Sign in with Google
 </button>
 <button type="submit" name="provider" value="Microsoft">
 Sign in with Microsoft
 </button>
 <button type="submit" name="provider" value="GitHub">
 Sign in with GitHub
 </button>
</form>

API端点触发质询并处理回调：

app.MapPost("/api/auth/external-login", (string provider, HttpContext context) =>
{
 var properties = new AuthenticationProperties
 {
 RedirectUri = "/api/auth/external-callback"
 };
 return Results.Challenge(properties, [provider]);
});

Blazor 中的外部身份验证始终需要完整页面导航 - 如果不通过服务器，您无法在 SignalR 电路或 WebAssembly 应用程序内完成 OAuth 重定向。

框架提供 AuthorizationMessageHandler 自动附加令牌：

builder.Services.AddHttpClient("API",
 client => client.BaseAddress = new Uri("https://api.example.com"))
 .AddHttpMessageHandler<AuthorizationMessageHandler>();

builder.Services.AddScoped(sp =>
 sp.GetRequiredService<IHttpClientFactory>().CreateClient("API"));

对于根据自己的 API 进行身份验证的独立 Blazor WASM 应用程序，您将实现一个解析 JWT 的自定义 AuthenticationStateProvider：

public class JwtAuthenticationStateProvider : AuthenticationStateProvider
{
 private readonly ILocalStorageService _localStorage;
 private readonly HttpClient _httpClient;

 public JwtAuthenticationStateProvider(
 ILocalStorageService localStorage,
 HttpClient httpClient)
 {
 _localStorage = localStorage;
 _httpClient = httpClient;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var token = await _localStorage.GetItemAsync<string>("authToken");

 if (string.IsNullOrWhiteSpace(token))
 return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));

 _httpClient.DefaultRequestHeaders.Authorization =
 new AuthenticationHeaderValue("Bearer", token);

 var claims = ParseClaimsFromJwt(token);
 var identity = new ClaimsIdentity(claims, "jwt");

 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void NotifyAuthStateChanged()
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 private IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
 {
 var payload = jwt.Split('.')[1];

 var padded = payload.Length % 4 switch
 {
 2 => payload + "==",
 3 => payload + "=",
 _ => payload
 };

 var bytes = Convert.FromBase64String(padded);
 var json = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(bytes);

 return json?.Select(kvp => new Claim(kvp.Key, kvp.Value.ToString()))
 ?? Enumerable.Empty<Claim>();
 }
}

成功登录后，您存储令牌并通知身份验证状态：

public class AuthService
{
 private readonly HttpClient _httpClient;
 private readonly ILocalStorageService _localStorage;
 private readonly JwtAuthenticationStateProvider _authStateProvider;

 public AuthService(
 HttpClient httpClient,
 ILocalStorageService localStorage,
 AuthenticationStateProvider authStateProvider)
 {
 _httpClient = httpClient;
 _localStorage = localStorage;
 _authStateProvider = (JwtAuthenticationStateProvider)authStateProvider;
 }

 public async Task<bool> LoginAsync(string email, string password)
 {
 var response = await _httpClient.PostAsJsonAsync("/api/auth/login",
 new { Email = email, Password = password });

 if (!response.IsSuccessStatusCode)
 return false;

 var result = await response.Content
 .ReadFromJsonAsync<LoginResponse>();

 await _localStorage.SetItemAsync("authToken", result!.Token);
 _authStateProvider.NotifyAuthStateChanged();

 return true;
 }

 public async Task LogoutAsync()
 {
 await _localStorage.RemoveItemAsync("authToken");
 _authStateProvider.NotifyAuthStateChanged();
 }
}

需要注意的是：将 JWT 存储在 localStorage 中会使它们遭受 XSS 攻击。对于安全性更高的应用程序，请考虑仅将令牌保留在内存中并使用刷新令牌，或者采用后端换前端 (BFF) 模式，其中服务器管理令牌而客户端使用仅 HTTP 的 cookie。

Blazor 服务器与 WebAssembly：安全注意事项

托管模型从根本上改变您的安全状况。

Blazor 服务器 将所有组件逻辑保留在服务器上。客户端只能通过 SignalR 看到渲染的 HTML 差异。这意味着：

敏感逻辑永远不会离开服务器
您可以直接从组件访问数据库和内部服务
身份验证状态来自初始连接时服务器的 HttpContext
电路可以比身份验证 cookie 的寿命更长 — 如果用户的 cookie 过期，电路将保持活动状态直到断开连接
您应该优雅地处理电路断开并在重新连接时重新验证身份验证状态

Blazor WebAssembly 完全在浏览器中运行。这意味着：

您的所有组件代码均可下载和检查
切勿将机密、连接字符串或敏感业务逻辑放入 WASM 组件中
身份验证仅在客户端上强制执行以实现用户体验；真正的执行必须发生在 API 层
代币管理是您的责任
考虑使用托管模型，其中服务器项目处理身份验证并为 WASM 应用程序提供服务

我为 WebAssembly 应用程序推荐的一种模式是将每个组件视为“不受信任的 UI”，并将每个 API 端点视为由未知客户端调用。无论客户端检查什么，都在服务器端验证所有内容。

构建自定义 AuthenticationStateProvider

有时内置提供程序不适合您的架构。也许您正在与旧版身份验证系统集成，或者您需要轮询身份验证状态更改。以下是 Blazor Server 的更完整的自定义提供程序：

public class CustomAuthStateProvider : AuthenticationStateProvider
{
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IUserService _userService;

 public CustomAuthStateProvider(
 IHttpContextAccessor httpContextAccessor,
 IUserService userService)
 {
 _httpContextAccessor = httpContextAccessor;
 _userService = userService;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var httpContext = _httpContextAccessor.HttpContext;

 if (httpContext?.User?.Identity?.IsAuthenticated != true)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var userId = httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier);

 if (userId is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var user = await _userService.GetUserWithClaimsAsync(userId);

 if (user is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var claims = new List<Claim>
 {
 new(ClaimTypes.NameIdentifier, user.Id),
 new(ClaimTypes.Name, user.DisplayName),
 new(ClaimTypes.Email, user.Email)
 };

 claims.AddRange(user.Roles.Select(r => new Claim(ClaimTypes.Role, r)));
 claims.AddRange(user.Permissions.Select(p => new Claim("Permission", p)));

 var identity = new ClaimsIdentity(claims, "Custom");
 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void MarkUserAsAuthenticated(string userId)
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 public void MarkUserAsLoggedOut()
 {
 var anonymous = new ClaimsPrincipal(new ClaimsIdentity());
 var authState = Task.FromResult(new AuthenticationState(anonymous));
 NotifyAuthenticationStateChanged(authState);
 }
}

将其注册到Program.cs中：

builder.Services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
builder.Services.AddScoped<CustomAuthStateProvider>();

这里的关键见解是 NotifyAuthenticationStateChanged — 调用它会触发级联参数进行更新，从而重新评估组件树中的每个 AuthorizeView 和 AuthorizeRouteView。这就是让 UI 对登录/注销事件做出反应而无需刷新整个页面的方法。

常见陷阱和解决方案

在多个项目中使用 Blazor 身份验证后，以下是我最常看到的问题：

1. 在 Blazor 服务器组件中使用 HttpContext`HttpContext` 在初始 HTTP 请求期间可用，但在 SignalR 交互期间它是 `null` 或过时的。不要将 `IHttpContextAccessor` 注入到初始渲染后运行的组件中。

解决方案： 在初始化期间从 HttpContext 捕获您需要的内容并将其存储在作用域服务中：

public class UserContext
{
 public string? UserId { get; set; }
 public string? AccessToken { get; set; }
}

// In a component that renders during the initial HTTP request:
@inject IHttpContextAccessor HttpContextAccessor
@inject UserContext UserContext

@code {
 protected override void OnInitialized()
 {
 var context = HttpContextAccessor.HttpContext;
 UserContext.UserId = context?.User.FindFirstValue(ClaimTypes.NameIdentifier);
 UserContext.AccessToken = context?.Request.Headers.Authorization
 .ToString().Replace("Bearer ", "");
 }
}

2.登录后身份验证状态不更新

您调用登录 API，它成功了，但 UI 仍然显示“登录”。

解决方案： 身份验证状态更改后，您必须在 AuthenticationStateProvider 上调用 NotifyAuthenticationStateChanged。该框架不会神奇地检测到令牌已存储或 cookie 已设置。

3. 授权属性不适用于组件

您将 [Authorize] 添加到组件，但它不会阻止未经身份验证的用户。

解决方案： 确保您在 App.razor 中使用 AuthorizeRouteView 而不是普通的 RouteView。标准 RouteView 完全忽略授权属性。

4. 预渲染破坏身份验证状态

在 Blazor WebAssembly 中的服务器端预呈现期间，没有可用的身份验证令牌。组件呈现为未经身份验证，然后在 WASM 加载后闪烁到经过身份验证的状态。

解决方案： 使用 @rendermode InteractiveWebAssembly 禁用对身份验证敏感页面的预渲染（无需预渲染），或者优雅地处理加载状态：

<AuthorizeView>
 <Authorized>
 <p>Welcome back, @context.User.Identity?.Name</p>
 </Authorized>
 <Authorizing>
 <p>Loading...</p>
 </Authorizing>
 <NotAuthorized>
 <a href="/login">Sign in</a>
 </NotAuthorized>
</AuthorizeView>

5. 长时间运行的电路中的令牌过期

Blazor 服务器电路可以保持活动状态数小时。如果您的令牌或会话过期，用户在 UI 中保持“经过身份验证”，但 API 调用开始失败。

解决方案： 实施定期检查或使用 RevalidatingServerAuthenticationStateProvider：

public class RevalidatingAuthStateProvider
 : RevalidatingServerAuthenticationStateProvider
{
 private readonly IServiceScopeFactory _scopeFactory;

 public RevalidatingAuthStateProvider(
 ILoggerFactory loggerFactory,
 IServiceScopeFactory scopeFactory)
 : base(loggerFactory)
 {
 _scopeFactory = scopeFactory;
 }

 protected override TimeSpan RevalidationInterval => TimeSpan.FromMinutes(30);

 protected override async Task<bool> ValidateAuthenticationStateAsync(
 AuthenticationState authenticationState, CancellationToken cancellationToken)
 {
 await using var scope = _scopeFactory.CreateAsyncScope();
 var userManager = scope.ServiceProvider
 .GetRequiredService<UserManager<IdentityUser>>();

 var user = await userManager.GetUserAsync(authenticationState.User);
 return user is not null;
 }
}

这会每 30 分钟验证一次用户是否仍然存在（并且其安全标记未更改）。

结论

Blazor 中的身份验证和授权需要转变传统请求-响应 ASP.NET 的思维方式。 AuthenticationStateProvider 抽象是理解它们如何组合在一起的关键——一旦你内化了它，剩下的就自然而然了。

对于大多数应用程序，从 ASP.NET Identity 和内置模板开始。它们处理用户管理、密码散列和令牌生成的繁重工作。随着您的需求的增长，分层策略和基于声明的授权。在用户需要时添加外部 OAuth 提供商。

托管模型很重要：Blazor Server 为您提供更传统的安全态势，其中代码保留在服务器上，而 WebAssembly 则推动您采用 API 优先的思维，其中客户端在设计上不受信任。两者本质上都不是更安全——它们只是有不同的威胁模型。

无论您选择哪种方法，请记住黄金法则：**用户界面中的授权是为了用户体验，服务器上的授权是为了安全。**始终强制执行两者。

Blazor 中的独立 JavaScript 与并置的 JS 文件

Wed, 18 Jun 2025 00:00:00 +0000

如果您以前使用过 Blazor 和 JS Interop，那么您可能最终会得到一个巨大的 app.js 文件，其中充满了不同组件的随机函数。它有效，但很快就会变得混乱。幸运的是，有一种更简洁的方法：并置 JavaScript 文件。

这个想法

就像 CSS 隔离一样，Blazor 允许您在组件旁边放置一个 .razor.js 文件。 JavaScript 模块仅在组件实际需要时按需加载。无全局脚本，无污染。

设置它

假设我们有一个 Clipboard.razor 组件将文本复制到剪贴板。在其旁边创建一个名为 Clipboard.razor.js 的文件：

export function copyToClipboard(text) {
 navigator.clipboard.writeText(text).then(() => {
 console.log("Copied to clipboard!");
 });
}

请注意 export 关键字 - 这很重要。 Blazor 将其作为标准 ES 模块加载。

在 Blazor 中加载模块

在您的组件中，您使用 IJSRuntime 导入模块。该路径遵循约定：./_content/{ASSEMBLY_NAME}/{COMPONENT_PATH}.razor.js 对于库，或者只是当前项目的相对路径。

@inject IJSRuntime JS
@implements IAsyncDisposable

<button @onclick="Copy">Copy to clipboard</button>

@code {
 [Parameter]
 public string Text { get; set; }

 private IJSObjectReference? module;

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 module = await JS.InvokeAsync<IJSObjectReference>(
 "import", "./Components/Clipboard.razor.js");
 }
 }

 private async Task Copy()
 {
 if (module is not null)
 {
 await module.InvokeVoidAsync("copyToClipboard", Text);
 }
 }

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

这里有几点需要注意：

我们在 OnAfterRenderAsync 中加载模块，因为 JS Interop 在服务器端预渲染期间不可用
我们用 IJSObjectReference 保留对模块的引用
我们实现 IAsyncDisposable 在组件被销毁时清理模块

为什么这样更好

之前，我习惯将所有内容转储到一个 wwwroot/js/app.js 中。它有效，但查找函数很痛苦，而且每个页面都加载了它不需要的 JavaScript。使用并置的 JS 文件：

每个组件都有自己的JavaScript
模块仅在需要时才延迟加载
没有全局函数名称冲突
更容易维护和删除——当你删除组件时，你也删除了它的JS

路径问题

您传递给 import 的路径取决于您是在独立的 Blazor 应用程序中还是在 Razor 类库中。对于常规 Blazor 应用程序，该路径是相对于 wwwroot 的。 .razor.js 文件在构建时被复制到那里，因此您可以从项目中组件的位置引用它。

如果加载模块时遇到 404，请仔细检查路径并确保文件以 .razor.js 结尾，而不仅仅是 .js。

希望你喜欢这篇文章！请随时通过任何社交媒体与我联系：@emimontesdeoca。

资源

ASP.NET Core Blazor JavaScript 与并置 JS

.NET 9 和 .NET 10 中的 Blazor 交互：完整指南

Sun, 15 Jun 2025 00:00:00 +0000

如果您在过去几年中一直使用 Blazor 构建 Web 应用程序，您就会知道该框架已经取得了“长”的进步。最初是在 Blazor Server 和 Blazor WebAssembly 之间进行选择，现已发展成为统一、灵活的渲染模型，让您可以为应用程序中的每个组件选择正确的交互策略。

在 .NET 8 中，我们实现了根本性的转变——引入渲染模式和默认的静态服务器端渲染 (SSR)。现在，.NET 9 和 .NET 10 建立在该基础之上，并进行了改进，使开发人员体验更流畅，最终用户体验更快。

在这篇文章中，我想向您介绍 Blazor 交互性的全貌：渲染模式如何工作、流式 SSR 带来了什么、增强的导航和表单处理如何改变游戏，以及最新版本中的新增功能。如果您正在计划一个新的 Blazor 项目或考虑升级，那么当我开始深入研究这一切时，我希望我能拥有这本指南。

快速回顾：我们是如何走到这一步的

在 .NET 8 之前，您必须在项目级别致力于托管模型。 Blazor 服务器意味着一切都通过 SignalR 连接在服务器上运行。 Blazor WebAssembly 意味着一切都在浏览器中运行。每种方法都需要权衡，混合它们是痛苦的。

.NET 8 通过引入统一这两种模型的单个项目模板（Blazor Web App）改变了游戏规则。关键概念是渲染模式：您决定每个组件它应该如何渲染以及交互发生在哪里。默认设置为静态 SSR，这意味着组件在服务器上渲染并将纯 HTML 发送到浏览器 - 没有 SignalR，没有 WebAssembly，只有快速 HTML。

.NET 9 完善了这些概念，改善了开发人员体验并优化了性能。 .NET 10 通过更好的重新连接处理、跨渲染模式的持久组件状态以及对 Blazor 脚本本身交付方式的改进，进一步实现了这一点。

让我们把这一切分解一下。

.NET 9 中的渲染模式

现代 Blazor 的核心是渲染模式的概念。您应该了解四种模式：

1.静态SSR（默认）

创建新的 Blazor Web 应用程序时，组件默认在服务器上静态呈现。服务器处理 Razor 组件，生成 HTML，并将其发送到浏览器。没有持久连接，没有 WebAssembly 运行时——只有传统的请求/响应。

这非常适合内容丰富的页面、主要显示数据的仪表板或任何不需要实时交互的页面。

@page "/products"

<h1>Our Products</h1>

@foreach (var product in products)
{
 <div class="product-card">
 <h3>@product.Name</h3>
 <p>@product.Description</p>
 <span class="price">@product.Price.ToString("C")</span>
 </div>
}

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await ProductService.GetAllAsync();
 }
}

该组件在服务器上呈现，生成 HTML，仅此而已。没有持续的连接。初始加载速度快，非常适合 SEO，服务器资源使用量最少。

2. 交互服务器当您需要实时交互（处理按钮点击、处理用户输入、动态更新 UI）时，您可以选择交互服务器模式。这会在浏览器和服务器之间建立 SignalR 连接，并通过该连接进行 UI 更新。

@page "/counter"
@rendermode InteractiveServer

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

@rendermode InteractiveServer 指令就足够了。该组件最初在服务器上呈现，然后建立 SignalR 连接来处理后续交互。您的 C# 事件处理程序在服务器上运行，并且 UI 差异将发送到浏览器。

何时使用它： 当您需要交互性时，您的组件需要访问服务器端资源（数据库、API、文件系统），并且您希望快速初始加载而无需等待 WebAssembly 下载。

3. 交互式 WebAssembly

如果您希望在不维护服务器连接的情况下进行交互，则交互式 WebAssembly 使用 .NET WebAssembly 运行时直接在浏览器中运行组件逻辑。

@page "/search"
@rendermode InteractiveWebAssembly

<h1>Product Search</h1>

<input @bind="searchTerm" @bind:event="oninput" placeholder="Search products..." />

@if (filteredProducts.Any())
{
 <ul>
 @foreach (var product in filteredProducts)
 {
 <li>@product.Name — @product.Price.ToString("C")</li>
 }
 </ul>
}

@code {
 private string searchTerm = string.Empty;
 private List<Product> allProducts = new();
 private IEnumerable<Product> filteredProducts => allProducts
 .Where(p => p.Name.Contains(searchTerm, StringComparison.OrdinalIgnoreCase));

 protected override async Task OnInitializedAsync()
 {
 allProducts = await Http.GetFromJsonAsync<List<Product>>("api/products") ?? new();
 }
}

权衡：.NET 运行时和程序集需要初始下载成本。但一旦加载，该组件就完全在浏览器中运行，无需与服务器进行 UI 交互交互。

何时使用它： 对于延迟很重要的高度交互组件（例如：富文本编辑器、绘图工具、实时过滤），当您想要减少服务器负载时，或者当您构建渐进式 Web 应用程序 (PWA) 时。

4. 互动汽车

这是务实的中间立场，也是我最喜欢的功能之一。 Interactive Auto 首次加载时通过 SignalR 进行服务器端渲染，然后在后台静默下载 WebAssembly 运行时。在后续访问中，该组件在 WebAssembly 上运行。

@page "/dashboard"
@rendermode InteractiveAuto

<h1>Dashboard</h1>

<DashboardWidget Title="Sales" Value="@salesTotal" />
<DashboardWidget Title="Users" Value="@activeUsers" />

<button @onclick="RefreshData">Refresh</button>

@code {
 private decimal salesTotal;
 private int activeUsers;

 protected override async Task OnInitializedAsync()
 {
 await RefreshData();
 }

 private async Task RefreshData()
 {
 var data = await DashboardService.GetSummaryAsync();
 salesTotal = data.SalesTotal;
 activeUsers = data.ActiveUsers;
 }
}

这为您提供了两全其美的优势：快速首次渲染（无需等待 WASM 下载），并且最终组件在客户端运行。用户不会注意到这种转变。

何时使用它： 当您想要快速初始加载和最终客户端执行时。对于许多交互式组件来说，它是一个很好的默认选择。

流式 SSR：两全其美

流式 SSR 是听起来很简单但在感知性能方面产生巨大差异的功能之一。其想法是：服务器不会在发送任何 HTML 之前等待所有数据加载，而是立即发送页面 shell，然后在数据可用时流内容更新。

@page "/reports"
@attribute [StreamRendering]

<h1>Monthly Reports</h1>

@if (reports is null)
{
 <div class="loading-spinner">
 <p>Loading reports...</p>
 </div>
}
else
{
 <table class="table">
 <thead>
 <tr>
 <th>Month</th>
 <th>Revenue</th>
 <th>Growth</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var report in reports)
 {
 <tr>
 <td>@report.Month</td>
 <td>@report.Revenue.ToString("C")</td>
 <td class="@(report.Growth >= 0 ? "text-success" : "text-danger")">
 @report.Growth.ToString("P1")
 </td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private List<MonthlyReport>? reports;

 protected override async Task OnInitializedAsync()
 {
 // This might take a couple of seconds
 reports = await ReportService.GetMonthlyReportsAsync();
 }
}

使用 [StreamRendering] 属性，会发生以下情况：

服务器立即使用加载微调器发送 HTML。
OnInitializedAsync 运行并获取数据。
当数据到达时，服务器将更新后的 HTML（表）传输到浏览器。
浏览器在不重新加载整页的情况下修补 DOM。

用户“立即”看到带有加载指示器的页面，然后内容就会填充。不需要 JavaScript 框架。没有 WebSocket 连接。只是巧妙地利用了 HTTP 流。何时使用它： 在渲染期间获取数据的任何静态 SSR 页面。产品列表页面、仪表板、报告——任何初始数据加载可能需要超过几百毫秒的地方。

何时不使用它： 如果数据加载速度极快（低于 100 毫秒），则流式传输开销不值得。此外，流式 SSR 无法为您提供持续的交互性 - 为此，您仍然需要交互式渲染模式。

增强的导航和表单处理

现代 Blazor 中微妙但强大的改进之一是增强的导航。默认情况下，Blazor 会拦截内部链接点击和表单提交，通过 fetch 获取新页面内容并修补 DOM，而不是执行完整的浏览器导航。

这意味着在静态 SSR 页面之间导航感觉就像 SPA — 没有整页闪烁，可以保留滚动位置，并且体验如丝般流畅。

它是如何运作的

加载 Blazor 脚本 (blazor.web.js) 时，它会自动拦截内部链接的点击。它不是传统的浏览器导航，而是：

向目标 URL 发出 fetch 请求。
接收 HTML 响应。
将新内容合并到现有 DOM 中。 4.更新浏览器的URL和历史记录。

您无需执行任何操作即可启用此功能 - 默认情况下它是打开的。但你可以控制它：

<!-- Disable enhanced navigation for a specific link -->
<a href="/legacy-page" data-enhance-nav="false">Legacy Page</a>

<!-- Force a full page reload for external-like behavior -->
<a href="/downloads/report.pdf" data-enhance-nav="false">Download Report</a>

增强的表单处理

表单得到相同的处理。当您在 Blazor 的表单处理中使用 EditForm 或标准 <form> 元素时，提交内容将通过 fetch 拦截和处理：

@page "/contact"

<EditForm Model="contactModel" OnValidSubmit="HandleSubmit" FormName="contact" Enhance>
 <DataAnnotationsValidator />

 <div class="mb-3">
 <label for="name">Name</label>
 <InputText id="name" @bind-Value="contactModel.Name" class="form-control" />
 <ValidationMessage For="() => contactModel.Name" />
 </div>

 <div class="mb-3">
 <label for="email">Email</label>
 <InputText id="email" @bind-Value="contactModel.Email" class="form-control" />
 <ValidationMessage For="() => contactModel.Email" />
 </div>

 <div class="mb-3">
 <label for="message">Message</label>
 <InputTextArea id="message" @bind-Value="contactModel.Message" class="form-control" />
 <ValidationMessage For="() => contactModel.Message" />
 </div>

 <button type="submit" class="btn btn-primary">Send</button>
</EditForm>

@code {
 [SupplyParameterFromForm]
 private ContactModel contactModel { get; set; } = new();

 private async Task HandleSubmit()
 {
 await ContactService.SubmitAsync(contactModel);
 contactModel = new ContactModel();
 }
}

EditForm 上的 Enhance 属性告诉 Blazor 拦截表单提交。表单发送到服务器，服务器对其进行处理并重新呈现页面，然后将更新的 HTML 传回 - 所有这些都不需要完整的页面导航。它感觉是交互式的，但它完全是服务器渲染的。

请注意 [SupplyParameterFromForm] 属性 - 这是 Blazor 在静态 SSR 场景中将发布的表单数据绑定到模型的方式。它是传统表单柱和 Blazor 组件模型之间的桥梁。

每页面和每个组件的交互性

新模型最强大的方面之一是您可以在单个应用程序中混合渲染模式。您的产品列表页面可以是静态 SSR，您的购物车可以是交互式服务器，您的产品配置器可以是交互式 WebAssembly——所有这些都在同一个应用程序中。

在组件级别设置渲染模式

您可以使用 @rendermode 指令直接在组件上设置渲染模式：

@* This component is interactive via Server *@
@rendermode InteractiveServer

<h3>Live Chat</h3>
<!-- chat UI here -->

或者您可以在使用父组件时设置它：

@page "/product/{Id:int}"

<h1>@product?.Name</h1>
<p>@product?.Description</p>

<!-- This child component gets its own interactive render mode -->
<ProductConfigurator Product="product" @rendermode="InteractiveWebAssembly" />

<!-- This stays static -->
<ProductReviews ProductId="Id" />

@code {
 [Parameter] public int Id { get; set; }
 private Product? product;

 protected override async Task OnInitializedAsync()
 {
 product = await ProductService.GetByIdAsync(Id);
 }
}

在此示例中，页面本身是静态 SSR。 ProductConfigurator 组件在 WebAssembly 上运行，以实现丰富的客户端交互性。 ProductReviews 组件保持静态，因为它只是显示数据。

全局设置渲染模式

如果你希望所有页面默认都是交互式的，你可以在App.razor中的根级别设置渲染模式：

<Routes @rendermode="InteractiveServer" />
```这使得每个页面都通过服务器渲染进行交互。如果需要，单个组件仍然可以覆盖它。

### 需要记住的重要规则

混合渲染模式时需要记住一些限制：

- **子组件不能具有比其父组件“更具交互性”的渲染模式。** 如果父组件是静态的，则子组件可以是静态的或交互式的。但是，如果父级是 Interactive Server，则子级不能是 Interactive WebAssembly（它需要是 Server 或 Auto）。
- **交互式组件不能直接使用静态父级的作用域服务。** 如果组件在 WebAssembly 上运行，它无法直接访问服务器端 `DbContext` 实例 - 您将需要一个 API 层。
- **状态不会在渲染模式之间自动传输。** 如果组件在服务器上预渲染然后切换到 WebAssembly，则需要显式处理状态持久性 - 有关更多信息，请参阅 .NET 10 部分。

## .NET 10 中的新增功能

.NET 10 继续采用增量改进方法，重点关注可靠性和开发人员体验。以下是 Blazor 交互性的亮点：

### 改进重连体验

如果您在生产中使用过交互式服务器模式，您可能遇到过重新连接覆盖 - SignalR 连接断开并且用户看到“正在重新连接...”消息的那一刻。在 .NET 10 中，这种体验明显改善。

重新连接逻辑现在对于重试更加智能。它没有使用固定的重试间隔，而是使用适应情况的退避策略。重新连接期间的 UI 也更加精美，并且您有更好的钩子来自定义体验：

```razor
<!-- In your App.razor or layout -->
<div id="components-reconnect-modal">
 <div class="reconnect-visible">
 <p>Connection lost. Attempting to reconnect...</p>
 <div class="spinner"></div>
 </div>
 <div class="reconnect-failed">
 <p>Could not reconnect to the server.</p>
 <button onclick="location.reload()">Reload</button>
 </div>
 <div class="reconnect-rejected">
 <p>Your session has expired.</p>
 <a href="/">Return to Home</a>
 </div>
</div>

该框架现在还在瞬态故障上更积极地尝试重新连接，并且可以更可靠地恢复电路状态。这意味着您的用户将减少“请重新加载页面”的时刻。

跨渲染模式的持久组件状态

这是一件大事。在 .NET 9 中，当组件在服务器上预渲染然后转换到 WebAssembly（或在渲染模式之间切换）时，组件状态会丢失。该组件会有效地重新初始化，这可能会导致重复的数据获取和 UI 闪烁。

.NET 10 改进了 PersistentComponentState 服务，以便在渲染模式转换之间更加无缝地工作：

@page "/weather"
@rendermode InteractiveWebAssembly
@inject PersistentComponentState ApplicationState

<h1>Weather Forecast</h1>

@if (forecasts is null)
{
 <p>Loading...</p>
}
else
{
 @foreach (var forecast in forecasts)
 {
 <div class="forecast-card">
 <h4>@forecast.Date.ToShortDateString()</h4>
 <p>@forecast.Summary — @forecast.TemperatureC°C</p>
 </div>
 }
}

@code {
 private List<WeatherForecast>? forecasts;
 private PersistingComponentStateSubscription persistingSubscription;

 protected override async Task OnInitializedAsync()
 {
 persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

 if (!ApplicationState.TryTakeFromJson<List<WeatherForecast>>(
 "weather-forecasts", out var restored))
 {
 // Data wasn't persisted from prerendering — fetch it
 forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("api/weather");
 }
 else
 {
 forecasts = restored;
 }
 }

 private Task PersistData()
 {
 ApplicationState.PersistAsJson("weather-forecasts", forecasts);
 return Task.CompletedTask;
 }

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

随着 .NET 10 的改进，此模式的工作更加可靠。当组件在交互模式下初始化时，预渲染期间序列化的状态可以正确使用，从而避免双重数据获取和用户可能会看到的短暂闪烁。

Blazor 脚本作为静态 Web 资产

在以前的版本中，Blazor JavaScript 文件 (blazor.web.js) 由框架的内部端点提供。在 .NET 10 中，它作为静态 Web 资产提供。这听起来可能是一个很小的改变，但它有实际的好处：- 更好的缓存： 静态 Web 资源获得正确的缓存标头和指纹 URL，因此浏览器可以更有效地缓存它们。

CDN 友好： 由于它是常规静态文件，CDN 可以从边缘位置缓存并提供服务。
压缩： 静态 Web 资源压缩会自动应用，从而减少线路上的脚本大小。

您无需更改引用它的方式 - 框架会自动处理更新的路径。

最佳实践：选择正确的渲染模式

在多个项目中使用所有这些模式之后，这是我的决策框架：

从静态 SSR 开始

将静态 SSR 设置为默认值。大多数应用程序中的大多数页面主要用于显示数据。产品页面、博客文章、用户个人资料、设置页面——这些不需要实时交互。静态 SSR 为您提供最佳性能、最低资源使用率和最简单的思维模型。

仅在需要的地方添加交互性

确定需要实时响应用户交互的特定组件。 “喜欢”按钮、聊天小部件、拖放界面——这些都需要交互性。但它们周围的页面可能没有。

使用交互式自动作为您的首选交互模式

当您确实需要交互性时，交互式自动通常是最佳默认选择。它为您提供快速的初始加载（服务器渲染）和最终的客户端执行（WebAssembly）。用户可以两全其美，而您只需编写一次代码。

为特定情况预留交互服务器

在以下情况下使用交互式服务器：

您的组件需要直接访问服务器资源（数据库、文件系统、内部 API）。
WebAssembly 下载大小是一个问题，您不能使用自动。
出于安全原因（例如，处理敏感数据），您需要该组件始终在服务器上运行。

慷慨地使用流式 SSR

如果您的静态 SSR 页面获取任何数据，请添加 [StreamRendering]。成本是最低的，并且感知到的性能改进是显着的。用户看到的内容逐渐出现，而不是盯着空白页面。

小心处理状态转换

如果您使用 Interactive Auto 或将预渲染与 WebAssembly 混合，请始终使用 PersistentComponentState 以避免重复数据提取。您的用户会感谢您没有闪烁的内容。

牢记组件树

记住渲染模式层次结构规则。规划您的组件树，以便交互边界有意义。一种常见的模式是采用静态布局，并在需要的地方嵌入交互式“岛”：

@* Layout: Static SSR *@
<header>
 <NavMenu />
 <UserMenu @rendermode="InteractiveServer" /> @* Needs real-time auth state *@
</header>

<main>
 @Body
</main>

<footer>
 <ChatWidget @rendermode="InteractiveAuto" /> @* Rich interactivity *@
</footer>

结论

.NET 9 和 .NET 10 中的 Blazor 交互模型代表了一种成熟的、经过深思熟虑的构建 Web 应用程序的方法。为每个组件选择渲染模式的能力、无缝增强的导航、流式 SSR 以及重新连接和状态管理的持续改进使其成为各种应用程序的引人注目的选择。关键的见解是交互性是一个范围，而不是二元选择。您的大部分应用程序可以是静态的。有些部分需要服务器驱动的交互性。有些可能会受益于在浏览器中运行。 Blazor 现在允许您以最细粒度（单个组件）做出选择，而无需与框架冲突。

如果您要开始一个新项目，我的建议很简单：创建一个 Blazor Web 应用程序，从静态 SSR 开始，将 [StreamRendering] 添加到数据密集的页面，并仅在需要时将各个组件提升为交互模式。您最终将得到一个快速、高效且可扩展的应用程序。

祝您编码愉快，一如既往，如果您有疑问，请随时与我们联系！

.NET 中的最少 API：构建轻量级 HTTP API

Thu, 10 Apr 2025 00:00:00 +0000

如果您已经使用 ASP.NET Core 构建 API 一段时间，您可能非常熟悉基于控制器的方法：创建一个控制器类，用属性装饰它，通过构造函数注入您的服务，并连接您的路由。它有效，而且效果很好——但有时感觉就像你在写很多仪式，相当于“接受这个请求，做一些事情，返回一个响应”。

这正是 Minimal API 想要解决的问题。 .NET 6 中引入的最小 API 允许您使用很少的样板文件定义 HTTP 端点。没有控制器，没有属性，没有启动类杂耍——只是以干净、函数式的方式直接路由到处理程序映射。

在这篇文章中，我想引导您了解有关最小 API 的所有信息：从第一个端点一直到组织大型应用程序、处理身份验证、验证、OpenAPI 文档和性能注意事项。让我们开始吧。

为什么要使用最少的 API？

在我们开始之前，让我们先谈谈为什么您会选择最小 API 而不是传统的基于控制器的方法。

当您需要一个结构化的、固执己见的框架时，控制器非常有用。它们为您提供模型绑定、过滤器、内容协商以及开箱即用的清晰的关注点分离。对于拥有数十名开发人员的大型企业应用程序，控制器强制执行的一致性可能是一个真正的好处。

另一方面，最少的 API 在您需要时会大放异彩：

更少样板 — 没有控制器类，没有 [ApiController] 属性，没有单独的启动配置。
更快的启动 — 启动时基于反射的操作更少。
更简单的心理模型 - 路线直接映射到处理程序。就是这样。
微服务友好 - 当您的 API 有 5-10 个端点时，完整的控制器设置可能会让人觉得大材小用。

好消息是，这不是一个非此即彼的决定。您可以在同一项目中混合使用控制器和 Minimal API。但是，一旦您适应了最低限度的方法，您可能会发现自己使用它的频率比您预期的要高。

开始使用

让我们从头开始创建一个 Minimal API。如果您安装了 .NET SDK，则非常简单：

dotnet new web -n MyMinimalApi
cd MyMinimalApi

这会给你一个看起来像这样的 Program.cs：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

就是这样。这是一个有效的 API。没有 Startup.cs，没有控制器类，没有路由配置。你运行 dotnet run，点击 http://localhost:5000，然后你会得到“Hello World!”后退。这里的简单性就是重点。

让我们用经典的 todo API 让它变得更有用：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var todos = new List<Todo>();

app.MapGet("/todos", () => todos);

app.MapGet("/todos/{id:int}", (int id) =>
 todos.FirstOrDefault(t => t.Id == id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound());

app.MapPost("/todos", (Todo todo) =>
{
 todos.Add(todo);
 return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapDelete("/todos/{id:int}", (int id) =>
{
 var todo = todos.FirstOrDefault(t => t.Id == id);
 if (todo is null) return Results.NotFound();
 todos.Remove(todo);
 return Results.NoContent();
});

app.Run();

record Todo(int Id, string Title, bool IsComplete);

我们在 30 行以内拥有完整的 CRUD。这就是最小方法的力量。

路由处理程序

路由处理程序是当请求与路由匹配时执行的函数。您有多种定义它们的选项。

Lambda 表达式

最常见的方法以及您将在大多数示例中看到的内容：

app.MapGet("/hello", () => "Hello!");
app.MapGet("/hello/{name}", (string name) => $"Hello, {name}!");

方法组

对于更复杂的逻辑，您可以指向命名方法：

app.MapGet("/products", GetProducts);
app.MapPost("/products", CreateProduct);

static IResult GetProducts(AppDbContext db)
 => Results.Ok(db.Products.ToList());

static IResult CreateProduct(Product product, AppDbContext db)
{
 db.Products.Add(product);
 db.SaveChanges();
 return Results.Created($"/products/{product.Id}", product);
}
```对于除了一句台词之外的任何事情，这是我的首选方法。它使您的路由映射部分保持干净和可读 - 您可以一目了然地看到存在哪些端点，而无需费力地了解实现细节。

### 局部函数

您还可以使用本地函数，当您想让处理程序靠近其路由定义时，这非常有用：

```csharp
app.MapGet("/health", CheckHealth);

IResult CheckHealth()
{
 // Some health check logic
 return Results.Ok(new { Status = "Healthy", Timestamp = DateTime.UtcNow });
}

参数绑定

我真正欣赏 Minimal API 的原因之一是参数绑定的直观性。该框架根据上下文和类型确定从哪里提取值。

路由参数

app.MapGet("/users/{id:int}", (int id) => $"User {id}");
app.MapGet("/files/{*path}", (string path) => $"File: {path}"); // catch-all

查询字符串参数

app.MapGet("/search", (string? query, int page = 1, int pageSize = 20) =>
 Results.Ok(new { query, page, pageSize }));

可空类型成为可选参数。默认值完全按照您的预期工作。

请求正文

app.MapPost("/orders", (Order order) =>
{
 // 'order' is automatically deserialized from the JSON body
 return Results.Created($"/orders/{order.Id}", order);
});

标头和服务绑定

app.MapGet("/protected", (
 [FromHeader(Name = "X-Api-Key")] string apiKey,
 [FromServices] ILogger<Program> logger) =>
{
 logger.LogInformation("Request with API key: {Key}", apiKey[..4] + "****");
 return Results.Ok("Authorized");
});

HttpContext 和 HttpRequest

当您需要较低级别的访问权限时：

app.MapGet("/info", (HttpContext context) =>
{
 var userAgent = context.Request.Headers.UserAgent.ToString();
 var ip = context.Connection.RemoteIpAddress?.ToString();
 return Results.Ok(new { userAgent, ip });
});

使用 BindAsync 进行自定义绑定

对于复杂类型，您可以实现静态 BindAsync 方法：

public record PaginationParams(int Page, int PageSize)
{
 public static ValueTask<PaginationParams?> BindAsync(HttpContext context)
 {
 int.TryParse(context.Request.Query["page"], out var page);
 int.TryParse(context.Request.Query["pageSize"], out var pageSize);

 var result = new PaginationParams(
 Page: page > 0 ? page : 1,
 PageSize: pageSize > 0 ? Math.Min(pageSize, 100) : 20
 );

 return ValueTask.FromResult<PaginationParams?>(result);
 }
}

app.MapGet("/items", (PaginationParams pagination, AppDbContext db) =>
{
 var items = db.Items
 .Skip((pagination.Page - 1) * pagination.PageSize)
 .Take(pagination.PageSize)
 .ToList();

 return Results.Ok(items);
});

这是非常强大的。您定义一次绑定逻辑，然后在所有端点上重复使用它。

验证

与控制器相比，Minimal API 无法提供开箱即用的功能，其中一个领域是模型验证。没有自动 [Required] 或 [StringLength] 强制执行。但有一些干净的模式可以处理它。

手动验证

最简单的方法 - 只需在处理程序中验证：

app.MapPost("/users", (CreateUserRequest request) =>
{
 if (string.IsNullOrWhiteSpace(request.Email))
 return Results.BadRequest(new { Error = "Email is required" });

 if (request.Name?.Length > 100)
 return Results.BadRequest(new { Error = "Name must be 100 characters or less" });

 // Create user...
 return Results.Created($"/users/{request.Email}", request);
});

使用验证库

对于任何重要的事情，我建议使用 FluentValidation 或类似的库：

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
 public CreateUserValidator()
 {
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}

您可以通过端点过滤器将其连接到您的端点，这将我们带到下一部分。

端点过滤器

端点过滤器是 Minimal API 的最佳功能之一。将它们视为中间件，但范围仅限于特定端点而不是整个管道。它们是在 .NET 7 中引入的，对于横切关注点来说它们非常有用。

基本过滤器

app.MapPost("/todos", (Todo todo) =>
{
 // Handle the request
 return Results.Created($"/todos/{todo.Id}", todo);
})
.AddEndpointFilter(async (context, next) =>
{
 var todo = context.GetArgument<Todo>(0);

 if (string.IsNullOrEmpty(todo.Title))
 {
 return Results.BadRequest(new { Error = "Title is required" });
 }

 return await next(context);
});

使用 FluentValidation 验证过滤器

这就是它真正强大的地方——可重用的验证过滤器：

public class ValidationFilter<T> : IEndpointFilter where T : class
{
 private readonly IValidator<T> _validator;

 public ValidationFilter(IValidator<T> validator)
 {
 _validator = validator;
 }

 public async ValueTask<object?> InvokeAsync(
 EndpointFilterInvocationContext context,
 EndpointFilterDelegate next)
 {
 var model = context.Arguments
 .OfType<T>()
 .FirstOrDefault();

 if (model is null)
 return Results.BadRequest(new { Error = "Request body is required" });

 var result = await _validator.ValidateAsync(model);

 if (!result.IsValid)
 {
 var errors = result.Errors
 .GroupBy(e => e.PropertyName)
 .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());

 return Results.ValidationProblem(errors);
 }

 return await next(context);
 }
}

// Usage
app.MapPost("/users", (CreateUserRequest request) =>
{
 // Only reached if validation passes
 return Results.Created($"/users/{request.Email}", request);
})
.AddEndpointFilter<ValidationFilter<CreateUserRequest>>();

日志过滤器

app.MapGet("/products", (AppDbContext db) => db.Products.ToList())
 .AddEndpointFilter(async (context, next) =>
 {
 var logger = context.HttpContext
 .RequestServices.GetRequiredService<ILogger<Program>>();

 var sw = Stopwatch.StartNew();
 var result = await next(context);
 sw.Stop();

 logger.LogInformation("Endpoint executed in {Elapsed}ms", sw.ElapsedMilliseconds);

 return result;
 });

您可以链接多个过滤器，它们按照添加的顺序执行 - 就像中间件一样。

OpenAPI / Swagger 集成

良好的 API 文档不再是可选的。值得庆幸的是，Minimal API 通过 Microsoft.AspNetCore.OpenApi 包对 OpenAPI 提供一流的支持。

基本设置

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos", () => new List<Todo>())
 .WithName("GetTodos")
 .WithDescription("Retrieves all todo items")
 .WithTags("Todos");

app.Run();

丰富的端点元数据

您可以提供有关端点的详细信息：

app.MapPost("/todos", (Todo todo) =>
{
 return Results.Created($"/todos/{todo.Id}", todo);
})
.WithName("CreateTodo")
.WithDescription("Creates a new todo item")
.WithTags("Todos")
.Accepts<Todo>("application/json")
.Produces<Todo>(StatusCodes.Status201Created)
.Produces(StatusCodes.Status400BadRequest)
.ProducesValidationProblem();

使用 WithOpenApi 进行定制

为了对生成的 OpenAPI 文档进行细粒度控制：

app.MapGet("/todos/{id:int}", (int id) => Results.Ok(new Todo(id, "Sample", false)))
 .WithOpenApi(operation =>
 {
 operation.Summary = "Get a specific todo";
 operation.Description = "Retrieves a single todo item by its unique identifier.";
 operation.Parameters[0].Description = "The unique identifier of the todo item";
 return operation;
 });

这为您提供了与控制器上的 Swashbuckle XML 注释相同级别的文档控制，但采用了更明确、代码优先的方式。

身份验证和授权

保护最小 API 端点遵循与 ASP.NET Core 的其余部分相同的模式 - 您只是以不同的方式应用它们。

基本设置```csharp

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = “https://your-identity-provider.com”; options.Audience = “your-api”; });

builder.Services.AddAuthorizationBuilder() .AddPolicy(“AdminOnly”, policy => policy.RequireRole(“Admin”)) .AddPolicy(“PremiumUser”, policy => policy.RequireClaim(“subscription”, “premium”));

var app = builder.Build();

app.UseAuthentication(); app.UseAuthorization();


### 对端点应用授权

```csharp
// Require any authenticated user
app.MapGet("/profile", (ClaimsPrincipal user) =>
{
 return Results.Ok(new
 {
 Name = user.FindFirstValue(ClaimTypes.Name),
 Email = user.FindFirstValue(ClaimTypes.Email)
 });
}).RequireAuthorization();

// Require a specific policy
app.MapDelete("/admin/users/{id}", (int id) =>
{
 // Delete user logic
 return Results.NoContent();
}).RequireAuthorization("AdminOnly");

// Allow anonymous access
app.MapGet("/public/health", () => Results.Ok(new { Status = "Healthy" }))
 .AllowAnonymous();

请注意如何将 ClaimsPrincipal 直接注入到处理程序参数中 - 框架会处理其余的事情。这是让 Minimal API 感觉非常优雅的小事情之一。

组织大型 API

最小 API 房间里的大象是组织。当你的 Program.cs 有 50 个端点时，它就会变得一团糟。以下是我用来保持事情易于管理的模式。

路线组

路由组（在 .NET 7 中引入）允许您跨相关端点共享配置：

var todos = app.MapGroup("/todos")
 .WithTags("Todos")
 .RequireAuthorization();

todos.MapGet("/", (AppDbContext db) => db.Todos.ToListAsync());
todos.MapGet("/{id:int}", (int id, AppDbContext db) => db.Todos.FindAsync(id));
todos.MapPost("/", (Todo todo, AppDbContext db) =>
{
 db.Todos.Add(todo);
 db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
});

组中的所有端点共享 /todos 前缀、Todos 标签和授权要求。干净的。

扩展方法

这是真正可扩展的模式。将每组端点移至其自己的静态类中：

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
 public static RouteGroupBuilder MapTodoEndpoints(this WebApplication app)
 {
 var group = app.MapGroup("/todos").WithTags("Todos");

 group.MapGet("/", GetAll);
 group.MapGet("/{id:int}", GetById);
 group.MapPost("/", Create);
 group.MapPut("/{id:int}", Update);
 group.MapDelete("/{id:int}", Delete);

 return group;
 }

 private static async Task<IResult> GetAll(AppDbContext db)
 => Results.Ok(await db.Todos.ToListAsync());

 private static async Task<IResult> GetById(int id, AppDbContext db)
 => await db.Todos.FindAsync(id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound();

 private static async Task<IResult> Create(Todo todo, AppDbContext db)
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 }

 private static async Task<IResult> Update(int id, Todo updated, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 todo.Title = updated.Title;
 todo.IsComplete = updated.IsComplete;
 await db.SaveChangesAsync();

 return Results.Ok(todo);
 }

 private static async Task<IResult> Delete(int id, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 db.Todos.Remove(todo);
 await db.SaveChangesAsync();

 return Results.NoContent();
 }
}

// Program.cs — stays clean
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapTodoEndpoints();
app.MapUserEndpoints();
app.MapOrderEndpoints();

app.Run();

您的 Program.cs 成为 API 的目录。每个端点组都位于其自己的文件中。这是我推荐用于生产应用程序的方法。

卡特图书馆

如果您想要更多结构，Carter 库提供了基于模块的方法：

public class TodoModule : ICarterModule
{
 public void AddRoutes(IEndpointRouteBuilder app)
 {
 app.MapGet("/todos", async (AppDbContext db) =>
 await db.Todos.ToListAsync());

 app.MapPost("/todos", async (Todo todo, AppDbContext db) =>
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 });
 }
}

Carter 自动发现并注册所有模块。它是原始最小 API 方法和完整控制器之间的一个很好的中间立场。

TypedResults 和响应类型

从 .NET 7 开始，您可以使用 TypedResults 而不是 Results 进行类型安全响应。这看起来似乎是一个很小的变化，但它对 OpenAPI 文档和可测试性有真正的好处。

app.MapGet("/todos/{id:int}", async Task<Results<Ok<Todo>, NotFound>> (int id, AppDbContext db) =>
{
 var todo = await db.Todos.FindAsync(id);
 return todo is not null
 ? TypedResults.Ok(todo)
 : TypedResults.NotFound();
});

返回类型 Results<Ok<Todo>, NotFound> 明确告诉框架（和您的 OpenAPI 文档）该端点可以生成哪些响应类型。不再需要猜测，不再需要手动 Produces<>() 来处理基本情况。

对于多种可能的结果：

app.MapPost("/todos",
 async Task<Results<Created<Todo>, ValidationProblem, Conflict>>
 (Todo todo, AppDbContext db) =>
{
 if (string.IsNullOrEmpty(todo.Title))
 return TypedResults.ValidationProblem(
 new Dictionary<string, string[]>
 {
 { "Title", new[] { "Title is required" } }
 });

 if (await db.Todos.AnyAsync(t => t.Title == todo.Title))
 return TypedResults.Conflict();

 db.Todos.Add(todo);
 await db.SaveChangesAsync();

 return TypedResults.Created($"/todos/{todo.Id}", todo);
});

我已经开始在所有新项目中使用 TypedResults。编译器会捕获声明的返回类型与实际返回的类型之间的不匹配，从而消除一整类运行时意外。

性能考虑因素

Minimal API 的卖点之一是性能，值得理解“为什么”它们更快。

**减少启动开销。**控制器严重依赖反射来发现端点、绑定模型和应用过滤器。最小 API 使用源生成器（从 .NET 7 开始）在编译时生成绑定代码。这意味着启动时的工作量更少，每个请求的内存分配也更少。

没有 MVC 管道。 基于控制器的 API 经历完整的 MVC 管道：操作选择、模型绑定、操作过滤器、结果执行。最小 API 会跳过所有这些，直接从路由到处理程序。

RequestDelegate 编译。 框架将您的 lambda 表达式编译为优化的 RequestDelegate 实例。如果您直接使用 HttpContext，生成的代码非常接近您手写的代码。

以下是一些最大化性能的实用技巧：

// Use AsNoTracking for read-only queries
app.MapGet("/products", async (AppDbContext db) =>
 await db.Products.AsNoTracking().ToListAsync());

// Return results directly — avoid unnecessary allocations
app.MapGet("/count", async (AppDbContext db) =>
 await db.Products.CountAsync());

// Use cancellation tokens for long-running operations
app.MapGet("/report", async (AppDbContext db, CancellationToken ct) =>
 await db.Orders
 .AsNoTracking()
 .GroupBy(o => o.Status)
 .Select(g => new { Status = g.Key, Count = g.Count() })
 .ToListAsync(ct));
```还值得一提的是，随着每个 .NET 版本的发布，控制器和 Minimal API 之间的性能差距不断缩小。对于大多数应用程序来说，这种差异不会成为瓶颈，而是数据库查询和外部服务调用。根据开发人员经验和项目需求而不是基准进行选择。

## 结论

自从在 .NET 6 中引入以来，最小 API 已经取得了长足的进步。最初的“hello world”演示功能已经成熟为生产 API 的合法选择。借助端点过滤器、路由组、类型化结果和可靠的 OpenAPI 支持，您拥有构建结构良好、可维护的服务所需的一切。

我的推荐？如果您正在启动一个新的 API 项目（尤其是微服务或专注的内部 API），请认真尝试最小化 API。使用扩展方法模式进行组织，依靠端点过滤器来解决横切问题，并利用 `TypedResults` 来实现类型安全。

对于现有的基于控制器的项目，不必急于迁移。这两种方法都很有效，您甚至可以同时使用它们。但下次您需要添加小型服务或快速内部 API 时，请跳过控制器并进行最小化。你可能不会回去。

快乐编码！

在 Blazor 组件中使用独立的 CSS

Wed, 12 Mar 2025 00:00:00 +0000

使用 Blazor 时总是困扰我的一件事是很容易意外地破坏组件之间的样式。您在一个组件中添加一个类，突然之间完全不同的页面上的其他内容看起来消失了。事实证明，Blazor 为此提供了一个内置解决方案：CSS 隔离。

什么是 CSS 隔离？

CSS 隔离使您可以将样式范围限定到特定组件。 Blazor 通过在构建时为每个组件生成唯一属性并将其附加到 CSS 选择器来实现此目的。因此，您的样式仅适用于它们所属的组件。

不需要 BEM 命名，不需要疯狂的特异性黑客。只是干净的、有范围的 CSS。

如何使用

假设您有一个名为 Card.razor 的组件：

<div class="card">
 <h3 class="card-title">@Title</h3>
 <p class="card-body">@ChildContent</p>
</div>

@code {
 [Parameter]
 public string Title { get; set; }

 [Parameter]
 public RenderFragment ChildContent { get; set; }
}

要添加独立样式，您只需创建一个具有相同名称但扩展名为 .razor.css 的文件。在本例中：Card.razor.css。

.card {
 border: 1px solid var(--color-border);
 border-radius: 8px;
 padding: 1rem;
 background: var(--color-bg-secondary);
}

.card-title {
 font-size: 1.1rem;
 font-weight: 600;
 margin-bottom: 0.5rem;
}

.card-body {
 color: var(--color-text-secondary);
 font-size: 0.9rem;
}

就是这样！ Blazor 将自动选择它并将这些样式的范围仅限于 Card 组件。如果您在其他地方有另一个 .card 类，它不会受到影响。

它是如何工作的

当您构建项目时，Blazor 会重写 HTML 和 CSS。您的组件会获得一个独特的属性，例如 b-3x8qz7k2f1，并且 CSS 选择器会附加该属性：

.card[b-3x8qz7k2f1] {
 border: 1px solid var(--color-border);
 /* ... */
}

生成的 CSS 包作为 {ProjectName}.styles.css。确保您的 index.html 或 _Host.cshtml 中有此内容：

<link href="YourApp.styles.css" rel="stylesheet" />

如果您缺少该链接，您的独立样式将不会显示，您将花费 30 分钟思考发生了什么。相信我，我去过那里。

定位子元素

需要记住的一件事是，默认情况下，独立 CSS 仅适用于当前组件的元素。如果要为子组件内的元素设置样式，则需要 ::deep 组合器：

::deep .child-element {
 color: red;
}

这告诉 Blazor 也将样式应用于子组件中的匹配元素。当您有一个需要为其子组件设置样式的包装组件时，这非常方便。

何时使用它

我现在几乎每个组件都使用 CSS 隔离。它使事情保持干净和可预测。我唯一不使用它的时候是真正的全局样式，例如重置、版式或主题变量——这些样式位于共享 CSS 文件中。

希望你喜欢这篇文章！请随时通过任何社交媒体与我联系：@emimontesdeoca。

资源

ASP.NET Core Blazor CSS 隔离

使用语义内核控制圣诞节支出

Sat, 28 Dec 2024 00:00:00 +0000

## 简介

随着假期的临近，管理开支可能成为一项挑战，尤其是在购物和礼品购买热潮的情况下。在这篇博文中，我们将探讨如何利用人工智能使用 .NET 技术来帮助跟踪您的圣诞节支出。通过利用语义内核和人工智能的力量分析收据，我们可以有效地提取关键详细信息，例如商店名称、日期、商品列表和总额。该解决方案可让您轻松监控和管理您的圣诞节支出，确保您控制在预算范围内，而无需手动查看收据。

2024 年人工智能Adviento Adviento 西班牙语日历

<p对齐=“中心”>

这个项目的灵感来自于我参加 Calendario de Adviento de Inteligencia Artificial 2024 en Español，这是一个专门针对人工智能的在线活动。您可以在此 Dev.to 链接上找到有关该活动的更多信息。

项目

对于这个项目，我们将使用 Azure OpenAI，该服务允许我们利用强大的 AI 模型（例如 GPT-4）来处理和分析图像。该过程涉及多个步骤，从设置后端 API 服务到与 Blazor 前端集成以进行图像上传。我们还将使用**.NET Aspire**，这是一个有助于无缝连接一切的组件。

先决条件

在我们深入研究代码之前，请确保您满足以下先决条件：

.NET 9
Azure OpenAI 访问（API 密钥）
Visual Studio 或 Visual Studio Code
Blazor、HTTP 客户端和 API 开发的基本知识

Visual Studio 解决方案

我们最终会得到这样的东西，我喜欢把东西分开并用很酷的名字，所以它看起来是这样的：

<p对齐=“中心”>

但让我们一步一步来创造东西吧！

步骤 0：模型

收据扫描仪应用程序的核心依赖于几个关键模型，这些模型促进前端、API 和 AI 服务之间的交互。本项目使用的主要模型如下：

分析收据请求
该模型表示用于分析收据的请求结构。它包含 ImageBytes 属性，该属性保存将要处理的收据图像的字节数组。
```
public class AnalyzeReceiptRequest
{
 public byte[] ImageBytes { get; set; }
}
```
收据分析结果
该模型在处理收据后捕获结果。它保存从收据中提取的结构化数据，例如商店名称、日期、商品和总金额。
```
public class ReceiptAnalyzeResult
{
 public DateTime CreatedAt { get; set; }
 public ReceiptData Result { get; set; }
}
```

收据数据
这是保存结构化收据数据的模型。它包括商店名称、日期、商品列表（包含每个商品的名称和价格）以及收据上的总金额的属性。

public class ReceiptData
{
 public string Store { get; set; }
 public DateTime? Date { get; set; }
 public List<ReceiptItem> Items { get; set; }
 public decimal? Total { get; set; }
}

收据项目
收据上的每一项都由该模型表示。它包含商品名称及其价格。

public class ReceiptItem
{
 public string Name { get; set; }
 public decimal? Price { get; set; }
}
```这些模型是客户端和服务器之间传递数据的基础，确保信息的顺畅流动。 API 接收收据图像，作为回报，它处理并返回一个可以由前端轻松使用的结构化 JSON 对象。

第 1 步：设置后端 API 服务

构建此应用程序的第一步是设置 API 服务来分析收据图像。我们将使用 Azure OpenAI API 从收据图像中提取信息。以下是所有内容如何组合在一起的详细说明：

AI 服务 - 深入探讨

人工智能服务是我们收据分析系统的核心。它负责与 Azure OpenAI 的 API 进行通信，以处理图像数据并返回有意义的见解。 AiApiClient 类是将处理与 Azure OpenAI API 的所有交互的客户端。

AI 客户端实施

AiApiClient 是负责将收据图像（字节数组格式）发送到 Azure OpenAI API 的关键组件。它处理通信、错误记录和数据解析：

public class AiApiClient
{
 private readonly HttpClient _httpClient;
 private readonly ILogger<AiApiClient> _logger;

 public AiApiClient(HttpClient httpClient, ILogger<AiApiClient> logger)
 {
 _httpClient = httpClient;
 _logger = logger;
 }

 public async Task<ReceiptAnalyzeResult?> AnalyzeAsync(byte[] imageBytes, CancellationToken cancellationToken = default)
 {
 if (imageBytes == null || imageBytes.Length == 0)
 {
 _logger.LogWarning("ImageBytes is null or empty.");
 return null;
 }

 _logger.LogInformation("Sending analyze request with image bytes of length: {Length}", imageBytes.Length);

 var request = new AnalyzeReceiptRequest
 {
 ImageBytes = imageBytes
 };

 try
 {
 var response = await _httpClient.PostAsJsonAsync("/analyze-receipt", request, cancellationToken);

 if (!response.IsSuccessStatusCode)
 {
 _logger.LogWarning("Failed to analyze receipt. StatusCode: {StatusCode}", response.StatusCode);
 return null;
 }

 var analyzeResult = await response.Content.ReadFromJsonAsync<ReceiptAnalyzeResult>(cancellationToken: cancellationToken);

 if (analyzeResult == null)
 {
 _logger.LogWarning("No content received from AI API service.");
 return null;
 }

 _logger.LogInformation("Analysis result received: {AnalyzeResult}", analyzeResult);

 return analyzeResult;
 }
 catch (Exception ex)
 {
 _logger.LogError(ex, "An error occurred while analyzing the receipt.");
 return null;
 }
 }
}

在这部分代码中，我们定义了 AnalyzeAsync 方法，该方法负责：

将图像字节数组发送到 Azure OpenAI API。
处理来自 API 的任何错误或不成功的响应。
将返回的JSON数据解析为结构化结果（ReceiptAnalyzeResult）。

将此功能分离到专用服务 (AiApiClient) 的好处包括：

错误处理： 集中处理网络问题或无效响应等错误。
日志记录： 正确记录请求和响应以监视系统行为。

<p对齐=“中心”>

API 服务 - 处理请求和响应

API 服务 充当前端 Blazor 应用程序和 AI 服务之间的中介。该服务负责接受图像数据，将其传递给AI服务，并将分析结果返回给客户端。

API 端点

在此步骤中，我们定义一个简单的 API 端点来接受收据图像，将其转发给 AI 服务进行处理，并将结果返回给客户端：

using ReceiptScanner.Shared.Clients;
using ReceiptScanner.Shared.Models;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddProblemDetails();

// Register AiApiClient with HttpClient
builder.Services.AddHttpClient<AiApiClient>(client =>
{
 client.BaseAddress = new Uri("https+http://aiservice");
});

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
 app.MapOpenApi();
}

// POST endpoint to analyze receipt
app.MapPost("/api/analyze-receipt", async (AnalyzeReceiptRequest request, AiApiClient aiApiClient, ILogger<Program> logger) =>
{
 if (request.ImageBytes == null || request.ImageBytes.Length == 0)
 {
 logger.LogWarning("ImageBytes is null or empty.");
 return Results.BadRequest("ImageBytes is required.");
 }

 logger.LogInformation("Received analyze receipt request with image bytes of length: {Length}", request.ImageBytes.Length);

 try
 {
 var result = await aiApiClient.AnalyzeAsync(request.ImageBytes);

 if (result == null)
 {
 logger.LogWarning("Failed to analyze the receipt.");
 return Results.Problem("Unable to process the receipt at this time. Please try again later.");
 }

 logger.LogInformation("Analysis completed successfully. Result: {Result}", result);

 return Results.Ok(result);
 }
 catch (Exception ex)
 {
 logger.LogError(ex, "An error occurred while processing the receipt.");
 return Results.Problem("An error occurred while processing the receipt. Please try again later.");
 }
});

app.MapDefaultEndpoints();

app.Run();

这个端点：

接受收据图像作为请求正文的一部分。
调用AiService endopint方法将图像发送到Azure OpenAI进行处理。
将分析结果返回给客户端。

<p对齐=“中心”>

步骤 2：设置 Blazor 前端

现在我们已经设置了后端，让我们将注意力转向 Blazor 前端。用户可以在这里上传收据图像进行分析并查看结果。

Blazor 页面实施

Blazor 页面提供了一个简单的界面，用户可以在其中上传多个收据图像，然后查看表格中显示的分析结果。这是该页面的代码：

@page "/analyzer"
@using ReceiptScanner.Shared.Clients
@using ReceiptScanner.Shared.Models
@using System.Globalization
@inject ApiServiceClient ApiClient
@inject ILogger<Program> Logger

@attribute [StreamRendering]
@rendermode InteractiveServer

<PageTitle>Receipt Analyzer</PageTitle>

<h1 class="text-center my-4">Receipt Analyzer</h1>

<div class="container">
 <p class="lead text-center mb-4">Upload receipt images below to extract their data.</p>

 <!-- File Upload Section -->
 <div class="card mb-4">
 <div class="card-body">
 <InputFile OnChange="HandleFileSelected" multiple class="form-control mb-3" />
 <button class="btn btn-primary w-100" @onclick="ProcessReceipts" disabled="@(!hasFiles)" type="button">
 <span class="@(!processing ? "d-none" : "") spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
 @if (processing)
 {
 <span>Processing...</span>
 }
 else
 {
 <span>Process Receipts</span>
 }
 </button>
 </div>
 </div>

 <!-- Uploaded Images Preview -->
 @if (fileBytesList.Any())
 {
 <div class="card mb-4">
 <div class="card-header">
 <h5 class="mb-0">Uploaded Receipt Images</h5>
 </div>
 <div class="card-body">
 <div class="row">
 @foreach (var fileBytes in fileBytesList)
 {
 <div class="col-12 col-md-4 mb-3">
 <img src="@($"data:image/jpeg;base64,{Convert.ToBase64String(fileBytes)}")" class="img-fluid rounded" alt="Uploaded receipt" />
 </div>
 }
 </div>
 </div>
 </div>
 }

 <!-- Processing Indicator -->
 @if (processing)
 {
 <div class="alert alert-info text-center" role="alert">
 <strong>Processing receipts...</strong> Please wait while we analyze the uploaded files.
 </div>
 }

 <!-- Analysis Results Section -->
 @if (analyzedReceipts != null && analyzedReceipts.Any())
 {
 <div class="card">
 <div class="card-header">
 <h5 class="mb-0">Analysis Results</h5>
 </div>
 <div class="card-body">
 <table class="table table-striped table-bordered">
 <thead>
 <tr>
 <th>Store</th>
 <th>Date</th>
 <th>Total</th>
 <th>Items</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var receipt in analyzedReceipts)
 {
 <tr>
 <td>@(receipt.Result?.Store ?? "Unknown")</td>
 <td>@(receipt.Result?.Date?.ToString() ?? "Unknown")</td>
 <td>@(receipt.Result?.Total?.ToString("C", ci) ?? "Unknown")</td>
 <td>
 <ul class="list-unstyled">
 @if (receipt.Result?.Items is not null)
 {
 @foreach (var item in receipt.Result?.Items!)
 {
 <li><strong>@item.Name</strong> - @item.Price?.ToString("C", ci)</li>
 }
 }
 </ul>
 </td>
 </tr>
 }
 </tbody>
 </table>
 </div>
 </div>
 }
 else if (processed && (analyzedReceipts == null || !analyzedReceipts.Any()))
 {
 <div class="alert alert-warning text-center" role="alert">
 <strong>No results found.</strong> Please try again with different images or ensure they are clear and legible.
 </div>
 }
</div>

@code {
 private bool hasFiles;
 private bool processing;
 private bool processed;
 private List<byte[]> fileBytesList = new();
 private List<ReceiptAnalyzeResult> analyzedReceipts = new();
 CultureInfo ci = new CultureInfo("es-es");

 private async Task HandleFileSelected(InputFileChangeEventArgs e)
 {
 try
 {
 fileBytesList.Clear();

 foreach (var file in e.GetMultipleFiles())
 {
 var memoryStream = new MemoryStream();
 await file.OpenReadStream().CopyToAsync(memoryStream);
 fileBytesList.Add(memoryStream.ToArray());
 }

 hasFiles = fileBytesList.Any();
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while handling file upload.");
 }
 }

 private async Task ProcessReceipts()
 {
 if (!hasFiles)
 return;

 processing = true;
 analyzedReceipts.Clear();

 try
 {
 foreach (var fileBytes in fileBytesList)
 {
 var result = await ApiClient.AnalyzeReceiptAsync(fileBytes);
 if (result != null)
 {
 analyzedReceipts.Add(result);
 }
 }
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while processing receipts.");
 }
 finally
 {
 processing = false;
 processed = true;
 }
 }
}

```该页面允许用户上传收据，并在表格中显示分析结果，其中包含商店名称、日期、总金额和商品列表。

<p对齐=“中心”>
<img src="https://imgur.com/BLswKhm.png">
</p>

## 步骤 3：.NET Aspire

<p对齐=“中心”>
<img src="https://imgur.com/ja56RWN.png">
</p>

### 什么是.NET Aspire？

.NET Aspire 是一组强大的工具、模板和包，用于构建可观察的、生产就绪的应用程序。 .NET Aspire 通过一系列处理特定云原生问题的 NuGet 包来交付。云原生应用程序通常由小型、互连的部分或微服务组成，而不是单个、整体的代码库。云原生应用程序通常会消耗大量服务，例如数据库、消息传递和缓存。有关支持的信息，请参阅 .NET Aspire 支持政策。

分布式应用程序是一种跨多个节点使用计算资源的应用程序，例如在不同主机上运行的容器。此类节点必须通过网络边界进行通信，以便向用户传递响应。云原生应用程序是一种特定类型的分布式应用程序，它充分利用云基础设施的可扩展性、弹性和可管理性。

在该项目中使用 **.NET Aspire** 可以带来多种好处，可以提高整体系统质量，例如：

### 1. **集中日志记录**

.NET Aspire 自动集成整个应用程序的日志记录，这意味着您不必为每个服务手动配置日志记录。这可确保日志一致并存储在集中位置，从而使调试和监控变得更加容易。

例如，`AiApiClient` 类使用日志记录发送到 AI 服务的图像字节、API 响应以及分析过程中发生的任何错误。

```csharp
_logger.LogInformation("Sending analyze request with image bytes of length: {Length}",

 imageBytes.Length);

<p对齐=“中心”>

2. 自动指标收集

.NET Aspire 还自动跟踪和报告重要的应用程序指标，例如响应时间、请求计数和错误率。这可以帮助您了解应用程序的执行情况并快速检测任何瓶颈或问题。

<p对齐=“中心”>

3. 提高性能

.NET Aspire 优化了 HTTP 调用，这有助于缩短响应时间并减少不必要的资源消耗。它提供连接池、请求重试和智能路由等功能。

4. 无缝集成

.NET Aspire 简化了各种服务（如本项目中的 AI 和 API 服务）的集成并简化了部署过程。您无需担心低级配置，因为 Aspire 会为您处理与基础设施相关的任务。

<p对齐=“中心”>

结论人工智能不再只是一个流行词或我们在科幻电影中看到的东西。它正在积极解决当今的现实世界问题，就像我们在这个项目中解决的问题一样——从收据中提取结构化数据。在 Azure OpenAI、.NET Aspire 和 Blazor 的帮助下，我们可以自动化原本耗时且容易出错的手动任务。 AI 不仅仅像 ChatGPT 那样聊天或响应提示；它可以解释图像，提取有价值的信息，并在几秒钟内为我们提供可操作的见解。

通过使用 Azure OpenAI 进行收据分析，并使用 .NET Aspire 与日志记录和指标无缝集成，我们创建了一个功能强大且可扩展的解决方案。人工智能在简化业务流程、自动化繁琐任务和提高准确性方面的潜力是巨大的，这只是其应用的一个例子。

这篇文章是 Calendario de Adviento de Inteligencia Artificial 2024 en Español 的一部分，该活动展示了现实世界的人工智能应用，并向西班牙语技术社区介绍最新趋势。如果您想更深入地了解人工智能及其可能性，那么本次活动是一个很好的起点。

人工智能正在改变我们的工作方式，这个项目只是对可能性的一瞥。人工智能的真正力量在于它解决实际问题的能力——无论是处理收据、分析图像还是预测趋势。我们只是触及了表面。

源代码

该项目的完整源代码可在 GitHub 上找到。请随意下载它，探索 AI 和 API 服务如何协同工作，并根据您自己的用例进行调整。如果您遇到任何问题，或者您有改进的想法，请立即创建问题或提交拉取请求。我们始终欢迎您的贡献，您的反馈将有助于使这个项目变得更好！

快乐编码！

使用容器来...跟踪圣诞礼物的价格？

Thu, 12 Dec 2024 00:00:00 +0000

圣诞节即将来临，随之而来的是为亲人寻找完美礼物的快乐任务。如果您和我一样，您可能喜欢买到划算的商品，但在节日期间浏览热门商品价格飞涨的感觉就像现实生活中的雪橇之旅一样 — 令人兴奋，但有点不知所措！今年，我决定充分利用我的技术技能并使流程自动化，而不是让自己因每日价格检查而发疯。

<p对齐=“中心”>

作为一名软件开发人员和热衷于利用技术解决日常问题的人，我找到了一种自动化检查价格过程的方法。我决定创建一个可以为我做这件事的系统，而不是每天手动访问多个在线商店来比较价格。这不仅节省了时间，还能确保我获得最优惠的价格，而无需每天检查的压力。

为什么要自动化价格监控？

自动化价格监控就像拥有自己的圣诞老人精灵团队全天候工作，以确保您无需费力即可获得最好的交易。这就是您会喜欢它的原因：

昂贵的物品：我们都知道圣诞礼物可能会非常昂贵，尤其是当您的清单上有小玩意和玩具时。在这些上省钱就像找到库存的最后一个树顶一样令人满意。
每日检查：谁有时间（或耐心）每天检查价格？不是我！
自动化：拥抱节日的奉献精神——给自己一份高效的礼物。
准确性：自动化确保您的价格检查像鲁道夫的鼻子一样准确。

核心技术

为了打造自己的圣诞老人小帮手，我决定使用几项关键技术：

容器

容器就像软件的圣诞包装。他们将您的应用程序与其所有的好东西（依赖项）捆绑在一起，因此一切都可以像在新雪中乘坐雪橇一样顺利运行。 Docker 是我们创建这些容器的首选。

开拓者

Blazor 是一个很酷的框架，用于使用 .NET 构建交互式 Web 应用程序。这就像用您自己的节日播放列表替换通用的圣诞颂歌一样——量身定制、高效且有趣。

Docker-Compose

Docker-Compose 是我们北极运营的管理者。它帮助我们保持所有服务（例如 API 和 Blazor 前端）完美和谐地一起运行。把它想象成我们节日交响乐的指挥。

分步指南

现在，让我们深入圣诞老人的工作室，将这个项目变为现实！

第 1 步：创建 API

1.1 设置项目

戴上你的编码圣诞老人帽子并设置一个新的 ASP.NET Core Web API 项目。打开你的终端（这有点像打开你的降临节日历）并运行：

dotnet new webapi -o PriceMonitorApi
cd PriceMonitorApi

此命令创建一个名为 PriceMonitorApi 的新目录并设置一个基本的 Web API 项目。想象一下，这就像为你的姜饼屋打造一个坚固的底座。

1.2 添加 HttpClient 和抓取库接下来，添加 `HttpClient` 和一个解析 HTML 的库。这将是我们可靠的获取和读取价格数据的雪橇。

dotnet add package HtmlAgilityPack

HtmlAgilityPack是帮助我们解析HTML文档的精灵。

1.3 创建模型

模型就像我们玩具的蓝图。让我们创建一个模型来表示产品信息：

namespace PriceMonitorApi.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

我们刚刚为我们的数据创建了完美的模板。

1.4 实现爬虫服务

我们的抓取服务就像圣诞老人的小帮手——为我们获取和处理信息：

using HtmlAgilityPack;
using PriceMonitorApi.Models;
using System.Globalization;

namespace PriceMonitorApi.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> ScrapeProductInfoAsync(string url)
 {
 var response = await _httpClient.GetStringAsync(url);

 var htmlDoc = new HtmlDocument();
 htmlDoc.LoadHtml(response);

 var title = htmlDoc.DocumentNode.SelectSingleNode("//h1[@class='product-title']").InnerText.Trim();
 var priceString = htmlDoc.DocumentNode.SelectSingleNode("//span[@class='product-price']").InnerText.Trim();

 if (decimal.TryParse(priceString, NumberStyles.Currency, CultureInfo.InvariantCulture, out var price))
 {
 return new ProductInfo
 {
 Title = title,
 Price = price,
 Date = DateTime.UtcNow
 };
 }

 throw new Exception("Unable to parse price");
 }
 }
}

这段代码将我们的 HtmlAgilityPack 变成了节日魔杖。

1.5 创建 API 控制器

让我们创建一个控制器，它将充当我们数据的看门人：

using Microsoft.AspNetCore.Mvc;
using PriceMonitorApi.Models;
using PriceMonitorApi.Services;

namespace PriceMonitorApi.Controllers
{
 [ApiController]
 [Route("api/[controller]")]
 public class ScraperController : ControllerBase
 {
 private readonly ScraperService _scraperService;

 public ScraperController(ScraperService scraperService)
 {
 _scraperService = scraperService;
 }

 [HttpGet("productinfo")]
 public async Task<ActionResult<ProductInfo>> GetProductInfo(string url)
 {
 try
 {
 var productInfo = await _scraperService.ScrapeProductInfoAsync(url);
 return Ok(productInfo);
 }
 catch (Exception ex)
 {
 return BadRequest(new { Message = ex.Message });
 }
 }
 }
}

我们的控制器确保数据传输速度比圣诞老人从烟囱里传输的速度还要快。

1.6 在 DI 容器中注册服务

最后，注册您的 ScraperService 以确保它在需要时可用。

services.AddHttpClient<ScraperService>();

现在您的 API 已准备就绪，就像平安夜圣诞老人的雪橇一样！

步骤 2：创建 Blazor 应用程序

Blazor 帮助我们像圣诞树一样装饰我们的项目，使其具有视觉吸引力和互动性。

2.1 设置 Blazor 项目

接下来，我们将创建一个 Blazor 项目，充当价格监控雪橇之旅的界面。

dotnet new blazor -o PriceMonitorBlazor
cd PriceMonitorBlazor

此命令洒了一些假日魔法来设置基本的 Blazor WebAssembly 项目。

2.2 添加模型

就像设置装饰物一样，在 Blazor 项目中添加一个 ProductInfo 模型：

namespace PriceMonitorBlazor.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

2.3 创建 API 调用服务

创建一个服务来从我们的 API 获取数据 - 将其视为我们的在线购物伙伴：

using PriceMonitorBlazor.Models;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"https://localhost:5001/api/scraper/productinfo?url={url}");
 return response;
 }
 }
}

2.4 在DI容器中注册服务

确保 ScraperService 已注册，以便我们可以将其注入到我们的组件中。

builder.Services.AddScoped<ScraperService>();

2.5 创建 Blazor 组件

更新 Pages/Index.razor 以包含有趣的交互式界面：

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="FetchProductInfo">Fetch Price</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();

 private async Task FetchProductInfo()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 var productInfo = await ScraperService.GetProductInfoAsync(productUrl);
 productInfos.Add(productInfo);
 }
 }
}

这就像设置节日展示一样，使我们的应用程序具有互动性和令人愉悦。

步骤 3：使用 Docker-Compose 连接所有内容

现在，让我们使用 Docker-Compose 连接所有内容，将我们的项目变成一个运转良好的雪橇。

3.1 创建 Dockerfile

为 API 和 Blazor 项目创建 Dockerfile：

PriceMonitorApi/Dockerfile：

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorApi/PriceMonitorApi.csproj", "PriceMonitorApi/"]
RUN dotnet restore "PriceMonitorApi/PriceMonitorApi.csproj"
COPY . .
WORKDIR "/src/PriceMonitorApi"
RUN dotnet build "PriceMonitorApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorApi.dll"]

PriceMonitorBlazor/Dockerfile：

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorBlazor/PriceMonitorBlazor.csproj", "PriceMonitorBlazor/"]
RUN dotnet restore "PriceMonitorBlazor/PriceMonitorBlazor.csproj"
COPY . .
WORKDIR "/src/PriceMonitorBlazor"
RUN dotnet build "PriceMonitorBlazor.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorBlazor.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorBlazor.dll"]

3.2 创建 docker-compose.yml

使用单个 docker-compose.yml 文件连接所有点（圣诞灯）：

version: '3.4'

services:
 api:
 image: pricemonitorapi
 build:
 context: ./PriceMonitorApi
 dockerfile: Dockerfile
 ports:
 - "5000:80"
 networks:
 - price-monitor-network

 blazor:
 image: pricemonitorblazor
 build:
 context: ./PriceMonitorBlazor
 dockerfile: Dockerfile
 ports:
 - "5001:80"
 depends_on:
 - api
 networks:
 - price-monitor-network

networks:
 price-monitor-network:
 driver: bridge

图表

下面的图表有助于可视化不同的组件和数据流，这将帮助我们了解圣诞老人世界中到底发生了什么：

####系统架构图

数据流程图

序列图

Docker 设置的组件图

步骤 4：URL 管理、刷新和自动定期刷新在此演示中，我们仅将其存储在内存中，但在实际应用程序中，您将使用数据库。对于这个有趣的项目，让我们坚持使用内存存储。

4.1 修改服务以管理 URL

首先，我们将确保我们的服务可以处理添加和检索 URL，以及获取产品信息：

更新Services/ScraperService.cs：

using PriceMonitorBlazor.Models;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;
 private List<string> urls = new List<string>();

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"http://localhost:5000/api/scraper/productinfo?url={url}");
 return response;
 }

 public void AddUrl(string url)
 {
 if (!urls.Contains(url))
 {
 urls.Add(url);
 }
 }

 public List<string> GetUrls()
 {
 return urls;
 }

 public void ClearUrls()
 {
 urls.Clear();
 }
 }
}

4.2 更新 Blazor 组件以进行 URL 管理和刷新

接下来，更新 Pages/Index.razor 以添加 URL 管理、刷新和自动定期刷新：

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="AddUrl">Add URL</button>
</p>

<p>
 <button @onclick="RefreshPrices">Refresh All Prices</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();
 private Timer _timer;

 protected override void OnInitialized()
 {
 StartTimer();
 }

 private void StartTimer()
 {
 // Set up the timer to call RefreshPrices every minute (60000 ms)
 _timer = new Timer(async _ => await InvokeAsync(RefreshPrices), null, TimeSpan.Zero, TimeSpan.FromMinutes(1));
 }

 private void AddUrl()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 ScraperService.AddUrl(productUrl);
 productUrl = string.Empty;
 }
 }

 private async Task RefreshPrices()
 {
 productInfos.Clear();
 var urls = ScraperService.GetUrls();

 foreach (var url in urls)
 {
 var productInfo = await ScraperService.GetProductInfoAsync(url);
 productInfos.Add(productInfo);
 }
 StateHasChanged();
 }
}

在此更新的组件中：

我们使用 Timer 每分钟定期调用 RefreshPrices 方法。
StartTimer 方法将计时器初始化为立即启动，然后每 60 秒触发一次。
当组件初始化以开始定期刷新时，OnInitialized 生命周期方法调用 StartTimer。

4.3 运行解决方案

要运行具有新功能的更新后的 Blazor 应用程序，请重建并重新启动 Docker 容器：

docker-compose build
docker-compose up

在浏览器中加载 http://localhost:5001 后，除了允许手动刷新和 URL 管理之外，Blazor 应用现在还应该每分钟自动刷新产品价格。

结论

建立这个价格监控系统真是太欢乐了！它不仅让我摆脱了日常价格检查的压力，而且还展示了现代网络技术的魔力。

2024 年节日科技日历

<p对齐=“中心”>

我创建这篇文章是 2024 年节日科技日历 活动的一部分，该活动汇集了科技爱好者、创新者和数字梦想家，分享知识并庆祝节日精神与技术奇迹的融合。这一举措不仅是为了学习和联系，也是为了回馈。

2024 年节日科技日历 今年将支持 Beatson 癌症慈善机构。 Beatson 癌症慈善机构致力于支持癌症患者、他们的家人以及照顾他们的医疗保健专业人员。有关他们令人难以置信的工作的更多信息，请访问 https://www.beatsoncancercharity.org/。

请访问节庆科技日历网站 https://festivetechcalendar.com，了解常见问题和有关该活动的更多详细信息。

嗬嗬嗬！

创建这个项目是为节日科技社区做出贡献并同时支持一项伟大事业的绝佳方式。

我希望本指南对您有所帮助，并激励您探索更多使用技术来简化日常任务的方法。

如果您有任何疑问或需要进一步帮助，请随时与我们联系。

快乐编码！

自定义 ValidationAttribute 和 Blazor 验证

Fri, 29 Mar 2024 00:00:00 +0000

# 定制一切

正如您可能在我的所有帖子中看到的那样，我真的尽力使所有内容尽可能干净，因为我已经写了有关自定义属性、自定义异常处理、服务集合注入等的帖子。

随着时间的推移，我意识到这种编码方式为我和我的团队提供了一种改进加班、更轻松地发现问题并尽可能分离代码的方法。

是的，在这个很酷的故事之后，我最近像往常一样一直在 Blazor 上工作，我发现，经过多年的开发，您可以创建自定义验证属性。

是的，这很有趣，这么多年过去了……

自定义验证属性

这个想法实际上来自工作，我们总是在所有地方进行验证，但我有一些字段需要相同的验证过程，所以我认为那里可能有一些东西……比如自定义验证属性！

因此，我为此启动了 Microsoft 文档，发现是的，您可以创建自定义验证属性并将它们分配给属性，就像这样：

public class StringLengthRangeAttribute : ValidationAttribute
{
 public int Minimum { get; set; }
 public int Maximum { get; set; }

 public StringLengthRangeAttribute()
 {
 this.Minimum = 0;
 this.Maximum = int.MaxValue;
 }

 public override bool IsValid(object value)
 {
 string strValue = value as string;
 if (!string.IsNullOrEmpty(strValue))
 {
 int len = strValue.Length;
 return len >= this.Minimum && len <= this.Maximum;
 }
 return true;
 }
}

并在一个简单的类中使用它，如下所示：

[Required]
[StringLengthRange(Minimum = 10, ErrorMessage = "Must be >10 characters.")]

[StringLengthRange(Maximum = 20)]

[Required]
[StringLengthRange(Minimum = 10, Maximum = 20)]

自定义验证器

因此，我有一个针对某些特定业务案例需要的验证器，该验证器将计算 20 个第一个字符，这些字符将由 9 个数字和一个连字符组成，并以 2 个通常是国家/地区代码的字符结尾，因此如下所示： 123456789-123456789-ES

我最终得到了这样的东西，它非常简单但有效：

using System;
using System.ComponentModel.DataAnnotations;
using System.Text.RegularExpressions;

public class SpecialStringValidatorAttribute : ValidationAttribute
{
 private const int TotalLength = 22;
 private const string Pattern = @"^(\d{10})-(\d{10})-([A-Za-z]{2})$";

 protected override ValidationResult IsValid(object value, ValidationContext validationContext)
 {
 string strValue = value as string;

 if (!string.IsNullOrEmpty(strValue))
 {
 if (strValue.Length != TotalLength)
 {
 return new ValidationResult($"The string must be {TotalLength} characters long.");
 }

 if (!Regex.IsMatch(strValue, Pattern))
 {
 return new ValidationResult("The string must follow the pattern: 1234567890-1234567890-AB");
 }

 return ValidationResult.Success;
 }

 return new ValidationResult("The string cannot be null or empty.");
 }
}

测试

我也为他们写了一些测试，以防万一：

public class SpecialStringValidatorTests
{
 [Theory]
 [InlineData("1234567890-1234567890-AB", true)]
 [InlineData("1234567890-1234567890-XY", true)]
 [InlineData("1234567890-1234567890-A1", false)]
 [InlineData("1234567890-1234567890-A", false)]
 [InlineData("1234567890-123456789-AB", false)]
 [InlineData("1234567890-1234567890", false)]
 [InlineData("1234567890-1234567890-ABCDE", false)]
 public void SpecialStringValidatorTest(string input, bool expectedResult)
 {
 // Arrange
 var validator = new SpecialStringValidatorAttribute();

 // Act
 var result = validator.IsValid(input);

 // Assert
 Assert.Equal(expectedResult, result);
 }
}

当运行时我得到了这个结果：

Microsoft (R) Test Execution Command Line Tool Version 16.9.1
Copyright (c) Microsoft Corporation. All rights reserved.

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.

Test run in progress...

Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-AB", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-XY", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A1", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-123456789-AB", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-ABCDE", expectedResult: False)

Test Run Successful.
Total tests: 7
 Passed: 7
 Total time: 1.7296 Seconds

自定义验证和 Blazor

现在我知道可以使用他的方法，将其实施到 Blazor 中显然是个好主意，对吧？

假设我有这个表单，它将使用我之前展示的模型 Person：

@using Models
@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<EditForm Model=@Person FormName="PersonForm">
 <DataAnnotationsValidator/>
 <ValidationSummary/>
 <div class="form-group">
 <label for="Name">Name</label>
 <InputText @bind-Value=Person.Name class="form-control" id="Name" />
 <ValidationMessage For="() => Person.Name"/>
 </div>
 <div class="form-group">
 <label for="MySpecialString">My special string</label>
 <InputText @bind-Value=Person.MySpecialString class="form-control" id="Name" />
 <ValidationMessage For="() => Person.MySpecialString"/>
 </div>
 <div class="form-group">
 <label for="Age">Age</label>
 <InputNumber @bind-Value=Person.Age class="form-control" id="Age" />
 <ValidationMessage For=@(() => Person.Age) />
 </div>
 <input type="submit" class="btn btn-primary" value="Save"/>
</EditForm>

@code {
 Person Person = new Person();
}

一旦我们运行它，我们就会收到以下错误：

如果我们只输入我们想要的内容，我们就会得到以下结果，一切都很清楚：

老实说，对我来说，很明显我们应该至少将验证这些表单的逻辑转移到自定义验证属性中，它使我们可以自由地将登录代码存储在单个位置，并且我们可以稍后将其用于 API 或其他应用程序。

希望您喜欢它，如果您有任何疑问或想联系我，请不要犹豫，与我联系！

.NET API 上的自定义异常处理

Sun, 01 Oct 2023 00:00:00 +0000

例外是不好的，我们知道吗？但如果我们必须处理它们怎么办？

当我们遇到异常时会发生什么，例如，在 API 上，它会显示一条堆栈消息，其中包含我们可能希望从用户获得的响应中删除的大量信息。

对于演示，我创建了一个 dotnet API 并添加了一个会引发异常的方法：

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new Exception("This is a custom exception!");
}

如果我们抛出异常，它看起来像这样：

System.Exception: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method16(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

这看起来很正常，这是你从异常中得到的，但对我来说，它显示了很多信息，如果你有库和东西，它可以向可能试图查看东西的人显示有关你的客户、你的项目或其他东西的明智信息。

这是 Swagger 上的样子：

创建自定义异常

这一步可以避免，因为我们知道会抛出什么异常，在本例中是 Exception，但对我来说，拥有自定义异常更好，因为您可以更好地控制抛出的内容。

在本例中，我刚刚创建了一个继承自 Exception 的对象 CustomException：

namespace CustomExceptionHandleDemo.Exceptions
{
 public class CustomException : Exception
 {
 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 public CustomException() { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 public CustomException(string message) : base(message) { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 /// <param cref="Exception" name="inner">Parameter for inner</param>
 public CustomException(string message, Exception inner) : base(message, inner) { }
 }
}

创建自定义异常后，让我们更新方法以抛出 CustomException 而不是 Exception：

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new CustomException("This is a custom exception!");
}

目前这不会改变任何东西，但堆栈跟踪将显示抛出的对象是 CustomException 而不是 Exception，看一下堆栈跟踪的开头：

CustomExceptionHandleDemo.Exceptions.CustomException: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method24(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

创建 ExceptionFilterAttribute

微软为我们提供了一种在抛出异常后处理异常的方法，您可以在[此处](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.filters.exceptionfilterattribute?view=aspnetcore-7.0查看更多信息。

但到目前为止，他们给我们的文档是：

一个抽象过滤器，在操作抛出异常后异步运行。子类必须重写 OnException(ExceptionContext) 或 OnExceptionAsync(ExceptionContext)，但不能同时重写两者。

那么让我们创建一个，我们将创建 CustomExceptionFilterAttribute，其中我们将覆盖 OnException：

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc;
using CustomExceptionHandleDemo.Exceptions;

namespace CustomExceptionHandleDemo.ExceptionFilterAttributes
{
 public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
 {
 /// <summary>
 /// OnException
 /// </summary>
 /// <param cref="ExceptionContext" name="context">Parameter for context</param>
 public override void OnException(ExceptionContext context)
 {
 if (context.Exception is CustomException)
 {
 context.HttpContext.Response.StatusCode = 500;
 context.Result = new ObjectResult(context.Exception.Message);
 }
 }
 }
}

正如你所看到的，我们正在查看 ExceptionContext，当异常是 CustomException 类型时，我们会做一些事情。

这个东西正在更新我们要返回的响应和状态代码。

为了更新状态代码，我们必须更新 context.HttpContext.Response.StatusCode，为了返回结果，我们必须通过为 context.Result 提供一个继承自 ActionResult 的对象来更新 context.Result。

这是一个过滤器，所以这意味着我们必须通过添加 [CustomExceptionFilter] 来添加一些东西。

使用过滤器

现在，让我们复制我们拥有的方法并添加此过滤器，以便它采取行动，我们的 API 端点最终将如下所示：

using CustomExceptionHandleDemo.ExceptionFilterAttributes;
using CustomExceptionHandleDemo.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace CustomExceptionHandleDemo.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 public WeatherForecastController()
 {
 }

 [HttpGet]
 [Route("GetWithoutExceptionHandler")]
 public Task GetWithoutExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }

 [HttpGet]
 [Route("GetWithExceptionHandler")]
 [CustomExceptionFilter]
 public Task GetWithExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }
 }
}

如您所见，我们有一个名为 GetWithExceptionHandler 的新方法，其逻辑与 GetWithoutExceptionHandler 相同，但在本例中，我们将过滤器 [CustomExceptionFilter] 添加到方法中。

运行该方法后，结果如下，我将显示一个图像，因为它不再显示堆栈跟踪：

因此，我们创建了一个自定义异常，一个过滤器来覆盖当我们抛出异常并在方法上使用它时发生的情况。

这可以用于很多事情，例如记录和了解错误发生的内容、时间和地点。

一种更好的注入东西的方法

Mon, 04 Sep 2023 00:00:00 +0000

每当我构建服务、存储库、属性或任何要注入到我的应用程序中的内容时，我们都必须执行此步骤，这实际上是将服务添加到应用程序中。

这始终是相同的，您转到 Program.cs，然后继续在文件的某些部分添加 builder.Services.AddScoped<MyService>(); 以注入服务。

像这样的东西：

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddScoped<ARepository>(); // 👀
builder.Services.AddScoped<BRepository>(); // 👀

// Services
builder.Services.AddScoped<AService>(); // 👀
builder.Services.AddScoped<BService>(); // 👀
builder.Services.AddScoped<CService>(); // 👀
builder.Services.AddScoped<DService>(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

我的意思是，它确实有效，但我很挑剔，而且我不太喜欢它。

假设我们想要执行多个依赖项注入，并且它们实际上并不是相同的东西，在我的例子中，这可能类似于拥有一个包含所有存储库的库，另一个包含所有服务的库，最后一个包含属性的库。

在这种情况下，您能想象我们必须添加到 Program.cs 中的行数吗？

假设我们有一个包含一些服务的库，如果我们想包含所有服务，我们必须使用 IServiceCollection。

因此，我们将创建一个 static class，它有一个名为 AddServices 的 static 方法，该方法返回 IServiceCollection。

在本例中，它将被命名为 IServiceCollectionServicesExtensions。

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddServices(this IServiceCollection services)
 {
 services
 .AddScoped<AService>()
 .AddScoped<BService>()
 .AddScoped<CService>()
 .AddScoped<DService>();

 return services;
 }
}

不仅如此，我们还有另一个库，其中包含该服务正在使用的一些存储库，所以让我们也这样做。

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddRepositories(this IServiceCollection services)
 {
 services
 .AddScoped<ARepository>()
 .AddScoped<BRepository>();

 return services;
 }
}

现在，我们已经创建了要注入的存储库和服务方法，但是我们如何使用它们呢？

让我们回到 Program.cs 并添加以下内容：

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddRepositories(); // 👀

// Services
builder.Services.AddServices(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

这看起来干净多了，不是吗？好了，我们已经成功地注入了一些服务和存储库，但现在看起来更好了，我们实际上已经在外部库中注入了我们注入的内容。

使用 .NET API 上的属性进行依赖注入

Tue, 22 Aug 2023 00:00:00 +0000

依赖注入可能是目前 .NET 上最好的功能之一。在任何可能的情况下，您都不可能不使用它，所以如果您像我一样，您非常希望将它添加到您所做的所有实现中。

过滤器，根据微软官方的文档：

ASP.NET Core 中的过滤器允许代码在请求处理管道中的特定阶段之前或之后运行。

内置过滤器可处理以下任务：

授权，防止用户访问未经授权的资源。

响应缓存，短路请求管道以返回缓存的响应。

可以创建自定义过滤器来处理横切问题。横切关注点的示例包括错误处理、缓存、配置、授权和日志记录。过滤器避免重复代码。

我经常使用 API，有些东西必须运行每个请求，或者几乎所有请求，所以，理想情况下我们想要做的是使用它加上……依赖注入！

但有时这有点棘手，如果我们想继承 ActionAttribute，它就不会像我们想要的那样工作，所以我们需要使用 TypeFilterAttribute，它让我们在重写 OnActionExecutionAsync 时做一些事情。

我通常创建这个过滤器来进行一些日志记录，所以我们将使用它作为示例：

/// <summary>
/// LoggedQueryAttribute class
/// </summary>
public class LoggedQueryTypeFilterAttribute : TypeFilterAttribute
{
 /// <summary>
 /// Constructor for <see cref="LoggedQueryTypeFilterAttribute"/>
 /// </summary>
 public LoggedQueryTypeFilterAttribute() : base(typeof(LoggedQueryFilter))
 {
 }

 /// <summary>
 /// LoggedQueryFilter class
 /// </summary>
 private class LoggedQueryFilter : IAsyncActionFilter
 {
 /// <summary>
 /// <see cref="_loggingService"/> object
 /// </summary>
 private readonly LoggingService _loggingService;

 /// <summary>
 /// Constructor for <see cref="LoggedQueryFilter"/>
 /// </summary>
 /// <param cref="LoggingService" name="loggingService">Parameter for loggingService</param>
 public LoggedQueryFilter(LoggingService loggingService)
 {
 _loggingService = loggingService;
 }

 /// <summary>
 /// OnActionExecutionAsync
 /// </summary>
 /// <param cref="ActionExecutingContext" name="context">Parameter for context</param>
 /// <param cref="ActionExecutionDelegate" name="next">Parameter for next</param>
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 // Get properties
 var properties = (Request)context.ActionArguments.First().Value!;

 // Get call from context
 var call = context.HttpContext.Request.Path.Value!;

 // Logging
 _loggingService.LogCustomEvent(call);

 // Continue call
 await next();
 }
 }
}

逻辑非常简单，我们通过使用 context.ActionArguments.First().Value 访问 context 对象来获取主体，同时我们也通过 context.HttpContext.Request.Path.Value 获取方法调用。

然后我们只需从我们的服务中调用我们的方法，在本例中是 _loggingService.LogCustomEvent(call)。

然后，我们必须调用 await next();，因为管道必须继续。

这是针对属性的，现在，我们实际上必须将此属性包含到方法中。

[LoggedQueryTypeFilterAttribute]
public ActionResult<string> TestFilter()
{
 return Ok("Hello world!");
}

希望您喜欢它，如果您有任何疑问或想联系我，请不要犹豫，与我联系！

带有外部库的 Swagger 文档

Fri, 17 Feb 2023 00:00:00 +0000

使用多个库来拆分代码以应对未来的情况是一件好事。就我个人而言，我喜欢这样做，如果我可以拆分我的逻辑，以便可以在其他项目或项目的一部分中重用它。

至少对我来说，必须拆分数据模型，包括 Entity Framework，以便可以在 Console application、Blazor application 或 API 中引用和使用它。

让我们看一下我如何做事情的示例，这是一个项目的屏幕截图，该项目具有一些应用程序和一个包含所有模型的共享库。

这是我从 API 项目中移出的类的示例，其中每个属性和类都有 summary 的文档。

namespace CustomLibrariesDocumentation.Models
{
 /// <summary>
 /// WeatherForecast class
 /// </summary>
 public class WeatherForecast
 {
 /// <summary>
 /// Gets or sets the Date
 /// </summary>
 public DateOnly Date { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureC
 /// </summary>
 public int TemperatureC { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureF
 /// </summary>
 public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

 /// <summary>
 /// Gets or sets the Summary
 /// </summary>
 public string? Summary { get; set; }
 }
}

如果我们将其引用到 Console application 并且开始使用该模型，我们可以看到文档，这是 Visual Studio 中的标准功能，因此它可以正常工作，如下所示：

但是，如果我们将其引用到 API 并转到 Swagger，则没有摘要文档。

我们该如何解决这个问题？

首先，我们必须在库上启用 XML 注释，为此，您需要更新项目设置并启用 ``:

这将在构建文件夹中生成一些以文件扩展名 xml 结尾的文件，如下所示：

现在我们已经完成了此操作，我们必须在 Program.cs 上添加一些内容，以便昂首阔步地读取这些文件，这是因为默认情况下它只加载其所在项目的 XML 定义。

它使用了 AddSwaggerGen 内部的一个方法，称为 IncludeXmlComments。

这个想法是，如果我们拥有所有 xml 文件，我们将强制将它们加载到 Swagger 上。

builder.Services.AddSwaggerGen(s =>
{
 // Comments
 var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

 foreach (string xmlFiles in allXmlFiles)
 {
 s.IncludeXmlComments(xmlFiles);
 }
});

很简单，我们从构建目录中获取 xml 文件，并使用 IncludeXmlComments 方法添加它们。

现在我们再次加载 API 并检查是否可以看到文档。

而且你可以看到我们可以看到文档！

希望对您有所帮助，如有任何疑问请随时联系我！

清理 Git 中的本地分支

Mon, 30 Jan 2023 00:00:00 +0000

您是否曾经遇到过当地分支机构过多的情况？这种情况经常发生在我身上，因为我们对每个功能、错误或琐事都使用分支。

我最终得到了这样的东西，一段时间后它就变得超级脏

这真的让我很烦恼，所以我将分享一个快速命令，您可以在控制台上运行来执行此清理操作！

我在 Robert Corvus 的以下 answer 中的 Stack Overflow 中找到了这个命令，这是在 Powerhsell 上运行的版本。

运行此命令时请小心，因为您可能会丢失所做的更改

在运行之前，请记住将 MY_MASTER_BRANCH_NAME 更新到您的主分支，它可以是像我使用的 master 或默认情况下称为 main 的新分支。

git branch | %{ $_.Trim() } | ?{ $_ -ne 'MY_MASTER_BRANCH_NAME' } | %{ git branch -D $_ }

运行此命令后，您将得到如下输出

希望对您有帮助！

更新 ASP.NET Core 7 中的 Identity 路由

Mon, 23 Jan 2023 00:00:00 +0000

甚至想知道微软如何命名如此罕见的东西？我一直认为他们并没有真正做得那么好，但是，事实就是如此！

这样做的好处是，您在开发过程中几乎可以改变一切！

您是否曾经进入过一个页面，只需执行注册或登录过程就立即意识到这是一个 ASP.NET Web 项目？

这种情况在我身上发生过很多次，因为默认情况下，在您创建的项目中，您有这些 url 来执行登录和注册过程（您也有很多其他页面）。

因此，本教程展示了一种更新这些 URL 的方法，以便您的项目看起来更好！

默认行为

当我们创建 Blazor 项目并决定将其与 Identity 一起使用时，它会显示如下内容：

<imgalign=“中心”src=“https://i.imgur.com/2W8Oou9.png">

当我们尝试进行登录或注册过程时，我们会选择 /Identity/Account/Login 或 /Identity/Account/Register。

但是，如果我告诉您您实际上可以将这些 URL 更新为不同的呢？

搭建 `Login` 和 `Register` 页面

为了更新这些页面，微软隐藏了它们，但您可以快速搭建它们并进行您想要的更改！

为此，您需要在项目的上下文菜单中转到 Add Scaffolded Item，如下所示：

然后它将弹出一个模式，您必须选择 Identity 两次并单击 Add：

在此之后，它将弹出另一个模式，您可以在其中选择要更新整个身份中的哪些页面。您可以更新很多页面，但我们将重点关注 Account/Login 和 Account/Register：

现在让它工作一会儿，然后检查解决方案资源管理器，您会发现一些新文件：

这些新文件是 ASP.NET 在您选择添加身份时添加到您的项目中的登录和注册页面！

更新网址

您可能已经注意到，这些文件是 razor 文件，因为它们的扩展名是 cshtml，因此我们将使用指令来更新页面的 url：

@page "/login"
@model LoginModel

@{
 ViewData["Title"] = "Log in";
}

<h1>@ViewData["Title"]</h1>
<div class="row">
 <div class="col-md-4">
 <section>
 <form id="account" method="post">
 <h2>Use a local account to log in.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email" class="form-label">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="current-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password" class="form-label">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="checkbox mb-3">
 <label asp-for="Input.RememberMe" class="form-label">
 <input class="form-check-input" asp-for="Input.RememberMe" />
 @Html.DisplayNameFor(m => m.Input.RememberMe)
 </label>
 </div>
 <div>
 <button id="login-submit" type="submit" class="w-100 btn btn-lg btn-primary">Log in</button>
 </div>
 <div>
 <p>
 <a id="forgot-password" asp-page="./ForgotPassword">Forgot your password?</a>
 </p>
 <p>
 <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
 </p>
 <p>
 <a id="resend-confirmation" asp-page="./ResendEmailConfirmation">Resend email confirmation</a>
 </p>
 </div>
 </form>
 </section>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to log in.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

正如您所看到的，大部分内容都是相同的，但是如果您看一下课程中的第一行，我已经更新了之前的内容：

@page

到

@page "/login"

嗯，这很容易，不是吗？现在让我们快速测试一下它是否有效。

首先，让我们转到最初的默认页面，检查它是否仍然有效：

事实并非如此！现在让我们测试一下新的 url，即 /login：

它有效！

现在让我们对寄存器做同样的事情，我们更新它的页面并在 @page 指令中添加我们想要的路径，然后让我们做一个测试！

@page "/register"
@model RegisterModel
@{
 ViewData["Title"] = "Register";
}

<h1>@ViewData["Title"]</h1>

<div class="row">
 <div class="col-md-4">
 <form id="registerForm" asp-route-returnUrl="@Model.ReturnUrl" method="post">
 <h2>Create a new account.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.ConfirmPassword" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.ConfirmPassword">Confirm Password</label>
 <span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
 </div>
 <button id="registerSubmit" type="submit" class="w-100 btn btn-lg btn-primary">Register</button>
 </form>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to register.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

我已经用 @page "/login" 更新了顶部部分，现在我们测试它是否有效：

也有效！

就是这样我希望您学会了如何更新此网址，主要是因为在某些项目中，当您以某种方式执行网址时，然后身份看起来不同，这很糟糕，哈哈！

如果您需要任何东西，请向我发推文或给我发送电子邮件，我会尽力提供帮助！

.NET 6 Core API 上的自定义属性

Fri, 09 Dec 2022 00:00:00 +0000

自定义属性确实是一件很好用的东西，我最近开始使用它们，因为它们允许我创建其中的单个属性并在控制器、类或方法本身上重用它们。

当您想要执行一些安全操作（例如检查标头或检查您确实需要的参数的值）时，它们确实很有帮助。

就我而言，我们将在 .NET Core API 项目中使用它，我们将在其中检查所有请求是否包含特定标头。

标头检查属性

因此，在创建了很酷的 .NET Core API 之后，让我们创建一个文件夹来存储我们的内容，因为我们喜欢使用文件夹。

然后我们将逻辑添加到我们的 HeaderCheckAttribute 类中。

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

namespace DotNet6CustomAttribute.Attributes
{
 public class HeaderCheckAttribute : ActionFilterAttribute
 {
 public override void OnActionExecuting(ActionExecutingContext context)
 {
 // Get all headers
 var headers = context.HttpContext.Request.Headers;

 // Check if headers has x-dotnet-6-custom-attribute
 if (!headers.ContainsKey("x-dotnet-6-custom-attribute"))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute is missing");
 }
 else if (string.IsNullOrEmpty(headers["x-dotnet-6-custom-attribute"]))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute can't be null or empty");
 }

 base.OnActionExecuting(context);
 }
 }
}

基本上的逻辑是，首先它检查带有键 x-dotnet-6-custom-attribute 的标头，如果存在，它检查它是否有值。

如果这两个表达式都为 true，它将返回带有特定消息的 BadRequestObjectResult。

将其添加到控制器中

我们可以将这个逻辑添加到多个地方，我们可以直接添加到整个控制器，也可以将它添加到某些方法中，我们将首先将其添加到方法中，然后添加到整个控制器中。

因此，让我们用它们来装饰 WeatherForecastController 类。

using DotNet6CustomAttribute.Attributes;
using Microsoft.AspNetCore.Mvc;

namespace DotNet6CustomAttribute.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 private static readonly string[] Summaries = new[]
 {
 "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
 };

 private readonly ILogger<WeatherForecastController> _logger;

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

 [HttpGet]
 [Route("GetWeatherForecastWithCheck")]
 [HeaderCheckAttribute]
 public IEnumerable<WeatherForecast> GetWithCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }

 [HttpGet]
 [Route("GetWeatherForecastWithoutCheck")]
 public IEnumerable<WeatherForecast> GetWithoutCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }
 }
}

让我们运行该项目吧！

我们有 2 个函数：GetWeatherForecastWithCheck 和 GetWeatherForecastWithoutCheck，其中一个会失败，其他不会，但让我们在 Swagger 上检查一下！

正如您所看到的，其中一个返回了我们的消息的 400 错误，另一个返回了值，现在为了充分测试这一点，让我们运行 Postman 并添加一个标头，以便我们还可以使用 GetWeatherForecastWithCheck 看到数据。

邮递员

现在在 Postman 上运行，我们添加标头，我们看到错误消息已更改，因为现在我们确实提供了标头，但它没有任何价值

如果我们给它添加一个值，我们最终就得到了值！

就是这样

好吧，就是这样！很简单吧？现在您知道如何创建属性并将其分配给方法和控制器！

和他们一起玩得开心！

代码

整个项目都在 Github 上，您可以在此处找到它！

如果您有任何问题或疑问，请随时在任何社交媒体上与我联系：@emimontesdeoca（在 Twitter 中实际上是 @emimontesdeocaa，末尾有两个 aa）。您还可以在博客标题上找到我的大部分社交活动。

希望你喜欢这篇文章！呀！

在 Blazor 中处理加载组件

Tue, 19 Jul 2022 00:00:00 +0000

Blazor 太棒了，真的太棒了，特别是当我们执行诸如加载盒子之类的异步操作时，它看起来很棒。

我一直在尝试采用多种方法来处理加载页面、状态、组件等。我想我终于找到了按照我想要的方式做到这一点的完美方法。

想法

我们不用重写每个页面或组件上的加载逻辑，而是使用 ChildComponent 构建父组件，这将使我们能够多次重用。

加载组件代码

代码非常简单，没什么可做的，一个基本的 if 带有加载属性，内部有一个切换函数，就完成了！

@if (_loaded)
{
 <div class="text-center">
 <div class="spinner-border" role="status">
 <span class="sr-only"></span>
 </div>
 </div>
}
else
{
 @ChildContent
}

@code {
 private bool _loaded = true;

 [Parameter]
 public RenderFragment? ChildContent { get; set; }

 public void ToggleLoad(bool state)
 {
 _loaded = state;
 }
}

用法

用法非常简单，为了测试，我们将使用一个新页面，并将内容放入刚刚创建的 LoadingComponent 组件中。

@page "/loading"
@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 This is some content
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent;


 protected override async Task OnInitializedAsync()
 {
 // We are going to simulate some load
 await Task.Delay(5000);

 loadingComponent.ToggleLoad(false);
 }

}

这就是它的样子

更有趣的例子

假设我们有多个组件，每个组件都有自己的加载时间，我们可以在此基础上构建一些看起来不错的东西！

让我们创建一个可以重用的假加载组件，称为 FakeLoadingComponent。

@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 It took @ellapsedTime seconds!
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent = new();
 private int ellapsedTime = 0;
 private Random rnd = new();

 protected override async Task OnInitializedAsync()
 {
 var random = rnd.Next(0, 5000);

 // We are going to simulate some load
 await Task.Delay(random);

 ellapsedTime = random/ 1000;

 loadingComponent.ToggleLoad(false);
 StateHasChanged();
 }
}

然后我们只需使用多个 FakeLoadingComponent 组件更新 Loading 页面并检查结果！

@page "/loading"
@using LoadingBoxes.Components

<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>

现在看起来好多了

就是这样！

希望你喜欢这篇文章！

从证书中获取到期日期

Fri, 27 May 2022 00:00:00 +0000

有一些网络应用程序可以帮助您检查我们使用的域中的证书的当前状态，我们有其中一些。

我创建了一个每天运行一次的 Azure 函数，并检查一些我需要查看的域，这是一个超级简单的控制台应用程序，如果证书的过期日期少于 30 天，它将发送一封电子邮件。

该函数如何工作的逻辑本身不会显示，我想展示对证书进行基本检查的函数以及我们获得的数据。

函数

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

此方法 CheckCertificateAsync 将返回一个 X509Certificate2 证书，让我们可以做很多事情，包括查看过期日期。

序列化结果

这是 certificate 对象的序列化值：

{
 "Archived":false,
 "Extensions":[
 {
 "KeyUsages":160,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.15",
 "FriendlyName":"Key Usage"
 },
 "RawData":"AwIFoA=="
 },
 {
 "EnhancedKeyUsages":[
 {
 "Value":"1.3.6.1.5.5.7.3.1",
 "FriendlyName":"Server Authentication"
 },
 {
 "Value":"1.3.6.1.5.5.7.3.2",
 "FriendlyName":"Client Authentication"
 }
 ],
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.37",
 "FriendlyName":"Enhanced Key Usage"
 },
 "RawData":"MBQGCCsGAQUFBwMBBggrBgEFBQcDAg=="
 },
 {
 "CertificateAuthority":false,
 "HasPathLengthConstraint":false,
 "PathLengthConstraint":0,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.19",
 "FriendlyName":"Basic Constraints"
 },
 "RawData":"MAA="
 },
 {
 "SubjectKeyIdentifier":"634E1585565AA49402C21642A4A5979A38025797",
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.14",
 "FriendlyName":"Subject Key Identifier"
 },
 "RawData":"BBRjThWFVlqklALCFkKkpZeaOAJXlw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.35",
 "FriendlyName":"Authority Key Identifier"
 },
 "RawData":"MBaAFBQusxe3WFbLrlAJQOYfr52LFMLG"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.5.5.7.1.1",
 "FriendlyName":"Authority Information Access"
 },
 "RawData":"MEcwIQYIKwYBBQUHMAGGFWh0dHA6Ly9yMy5vLmxlbmNyLm9yZzAiBggrBgEFBQcwAoYWaHR0cDovL3IzLmkubGVuY3Iub3JnLw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.17",
 "FriendlyName":"Subject Alternative Name"
 },
 "RawData":"MB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.32",
 "FriendlyName":"Certificate Policies"
 },
 "RawData":"MEMwCAYGZ4EMAQIBMDcGCysGAQQBgt8TAQEBMCgwJgYIKwYBBQUHAgEWGmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3Jn"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.4.1.11129.2.4.2",
 "FriendlyName":"SCT List"
 },
 "RawData":"BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSA=="
 }
 ],
 "FriendlyName":"",
 "HasPrivateKey":false,
 "PrivateKey":null,
 "IssuerName":{
 "Name":"CN=R3, O=Let's Encrypt, C=US",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMw=="
 },
 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",
 "PublicKey":{
 "EncodedKeyValue":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"MIIBCgKCAQEAq8cbDO3GAfjqqbPPCBdPost8NMRmEubv85gXecll7mZMH5qSfTPuB/ouFWL3tPMf1U8usWeoSUK/48yatzBGwmj1KKlkaW9MS2QkydztRp+kH8LvbzbQvGknuOLWGHBALLT17o/3DYxuA5LnXdY+vLvJWygQoFr2N/XhnhUjcm6OaQEJpIykydfbBQGQSEuQIIw4egpgdHkYJjCOYAsXuSSggN8/FADTCec0RzVjfFTSoJ3hV9HLE9M8MCSXjuo0AJ/MbAxq91S8XmDcRjHCCd7Zw+NjHo8cxZCQ6NqGvn3xwx8ahmmbC+CyDEcIyJJZK2Yv+qE4oS8QZfaX/RaHMwIDAQAB"
 },
 "EncodedParameters":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"BQA="
 },
 "Key":{
 "Key":{
 "Algorithm":{
 "Algorithm":"RSA"
 },
 "AlgorithmGroup":{
 "AlgorithmGroup":"RSA"
 },
 "ExportPolicy":0,
 "Handle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "IsEphemeral":true,
 "IsMachineKey":false,
 "KeyName":null,
 "KeySize":2048,
 "KeyUsage":16777215,
 "ParentWindowHandle":{
 "value":0
 },
 "Provider":{
 "Provider":"Microsoft Software Key Storage Provider"
 },
 "ProviderHandle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "UIPolicy":{
 "ProtectionLevel":0,
 "FriendlyName":null,
 "Description":null,
 "UseContext":null,
 "CreationTitle":null
 },
 "UniqueName":null
 },
 "LegalKeySizes":[
 {
 "MinSize":512,
 "MaxSize":16384,
 "SkipSize":64
 }
 ],
 "KeyExchangeAlgorithm":"RSA",
 "SignatureAlgorithm":"RSA",
 "KeySize":2048
 },
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 }
 },
 "RawData":"MIIFQDCCBCigAwIBAgISBNwTmwP/RTcrEeIgAdMrpaFtMA0GCSqGSIb3DQEBCwUAMDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMzAeFw0yMjA1MDcwOTUwMzZaFw0yMjA4MDUwOTUwMzVaMCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCrxxsM7cYB+Oqps88IF0+iy3w0xGYS5u/zmBd5yWXuZkwfmpJ9M+4H+i4VYve08x/VTy6xZ6hJQr/jzJq3MEbCaPUoqWRpb0xLZCTJ3O1Gn6Qfwu9vNtC8aSe44tYYcEAstPXuj/cNjG4Dkudd1j68u8lbKBCgWvY39eGeFSNybo5pAQmkjKTJ19sFAZBIS5AgjDh6CmB0eRgmMI5gCxe5JKCA3z8UANMJ5zRHNWN8VNKgneFX0csT0zwwJJeO6jQAn8xsDGr3VLxeYNxGMcIJ3tnD42MejxzFkJDo2oa+ffHDHxqGaZsL4LIMRwjIklkrZi/6oTihLxBl9pf9FoczAgMBAAGjggJZMIICVTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFGNOFYVWWqSUAsIWQqSll5o4AleXMB8GA1UdIwQYMBaAFBQusxe3WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5jci5vcmcvMCcGA1UdEQQgMB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wTAYDVR0gBEUwQzAIBgZngQwBAgEwNwYLKwYBBAGC3xMBAQEwKDAmBggrBgEFBQcCARYaaHR0cDovL2Nwcy5sZXRzZW5jcnlwdC5vcmcwggEGBgorBgEEAdZ5AgQCBIH3BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSDANBgkqhkiG9w0BAQsFAAOCAQEAjSEID5MWonbSiyHbmPYWO8ImCCOjkLGxgY8WJODbrWxFy+xU44UwrWOCkqYZUlv2LRmPqSyZDrIeeHK9VMbGh71oXX+XovikgAr6PpI0Mp897nPWj0XvOBaSYG0s+f+CXMtyt0tWCsQOcl+iT82+Ja71f8gbVL6l7xESewEE78pTKEH8EqD22r8VSD7FNICD8EYQr13v3AuVWObSU/R8Td6SrSVEknw1HgJS4e9nvmrMxBGKOJ+aWrAGiUydehg8M9o2gbGckMhz6D7cwB5l618cYaXKkW1dEOYZHl++qUj1/VPK+FNkiDZOPVNN//PbZuOLwAUIlZvhqGWX5/9PBg==",
 "SerialNumber":"04DC139B03FF45372B11E22001D32BA5A16D",
 "SignatureAlgorithm":{
 "Value":"1.2.840.113549.1.1.11",
 "FriendlyName":"sha256RSA"
 },
 "SubjectName":{
 "Name":"CN=blog.emilianomontesdeoca.com",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 "Thumbprint":"28CF960F772ABFF22AA193C291492C27F8E13D4D",
 "Version":3,
 "Handle":{
 "value":2658150705632
 },
 "Issuer":"CN=R3, O=Let's Encrypt, C=US",
 "Subject":"CN=blog.emilianomontesdeoca.com"
}

有效期

为了知道过期时间，我们需要查看该对象内部的 NotAfter 和 NotBefore：

 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",

控制台应用程序

以下代码片段是一个基于 .NET 6 构建的简单控制台应用程序，它将产生以下结果，您可以在其中检查所需的任何认证：

using Newtonsoft.Json;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Text.Json;

var url = "https://blog.emilianomontesdeoca.com/";

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

var cert = await CheckCertificateAsync(url);

var serializedValue = JsonConvert.SerializeObject(cert);

Console.WriteLine(serializedValue);

Console.ReadLine();

演示项目

您可以在我的 Github 中名为 expiration-date-certificate 的存储库中找到控制台应用程序。

在 Blazor 中聚焦元素

Thu, 05 May 2022 00:00:00 +0000

在我最近制作的 Wordlzor 游戏之后，我需要添加一个非常简单的功能：进入时聚焦整个游戏。

之所以需要这样做，是因为用户实际上可以在游戏中打字，而不仅仅是使用屏幕键盘。

JavaScript 文件

为此，我们必须创建一个名为 app.js 的 Javascript 文件，该文件将保存一个函数

window.FocusElement = (element) => {
 element.focus();
};

完成此操作后，我们需要将脚本包含在 index.html 文件中：

<script src="js/app.js"></script>

Blazor 组件

初始化脚本后，我们需要找到一个要关注的元素，因此在任何组件中，我们需要将该元素引用到一个对象。

因此，在我们的 blazor 组件中，让我们添加一个带有 @ref 属性：

<div @ref=@elementToFocus tabindex="0" >
 This is my focus component
</div>

然后在组件逻辑上，您可以将该属性设置为 ElementReference：

/// <summary>
/// Reference to element
/// </summary>
private ElementReference elementToFocus;

注入 JSInterop

现在，为了调用 Javascript 文件中的函数，我们需要使用 JSInterop。

首先，我们必须使用以下语法将其注入到组件上：

[Inject]
public IJSRuntime JSRuntime { get; set; }

注入服务后，我们现在可以调用它具有的任何方法，例如 InvokeVoidAsync，它将调用该函数：

public async Task Focus()
{
 // Focus when initializing
 await JSRuntime.InvokeVoidAsync("window.FocusElement", elementToFocus);
}

当你调用函数 Focus() 时，它将聚焦于我们创建的元素，显然你可以重构并将元素本身作为参数传递。

如果你想看看我是如何实现它的，请查看 Wordlzor 源代码，我用它来在关闭指令模式时发出警报和聚焦。

从 GitHub Actions 中的 VS 数据库项目生成 *.dacpac 文件

Mon, 18 Apr 2022 00:00:00 +0000

如果您需要使用数据库并且想要进行敏捷开发，则必须有一个流程，每当您添加或修改表、SP、函数时，它都会对其进行编译并生成数据库的部署文件。

我已经做这个方法很长时间了，我们在本地进行更改，与我们的数据库项目进行比较，然后当我们提交并推送更改时，它们会生成一个 bacpac 文件，该文件将进入数据库。

它消除了手工操作的所有麻烦，手工操作可能会导致人为错误，而在数据库中这确实是个坏消息。

数据库项目

当我们在 Visual Studio 上创建数据库项目并导入数据库时，它最终会像这样

当我们对该项目运行编译时，它将生成一个 dacpac 文件，其中包含我们的所有结构

Github 管道

现在我们已经在存储库上发布了代码，我们现在需要创建一个操作来编译该项目，生成此 dacpac 文件并将其放在我们可以下载或用于另一步骤的位置。

name: DacpacGithubActions project build

on:
 push:
 branches: main

jobs:
 build:
 runs-on: windows-latest

 steps:
 - uses: actions/checkout@v2

 - name: Setup MSBuild
 uses: microsoft/setup-msbuild@v1

 - name: Navigate to Workspace
 run: cd $GITHUB_WORKSPACE

 - name: Create Build Directory
 run: mkdir artifacts

 - name: Build Solution
 run: |
 msbuild.exe /t:DacpacGithubActions /p:DebugSymbols=false /p:DebugType=None /p:DeployOnBuild=true /p:WebPublishMethod=FileSystem /p:OutDir="../artifacts"
 
 - name: Upload artifact
 uses: actions/upload-artifact@v1.0.0
 with:
 name: DacpacGithubActionsArtifacts
 path: "../artifacts"

此操作将执行一系列操作，构建解决方案并将结果放入预先创建的 artifacts 文件夹中，然后它将文件从该文件夹上传到工件。

运行管道

现在继续触发构建，结果应该如下

如果我们实际下载该工件并查看内容，这就是我们将来实现持续部署步骤时所需要的，dacpac 文件！

代码

整个项目都在 Github 上，您可以在此处找到它！

希望你喜欢这篇文章！呀！

在 Blazor 中使用 Javascript Interop 切换主题

Fri, 01 Apr 2022 00:00:00 +0000

对于像我这样每次打开网页时都会出现闪回的人，我想出了一个超级简单的解决方案，介绍如何使用 Javascript 在浅色和深色模式之间切换，并使用 Javascript Interop 从 Blazor 调用它。

设置父属性

首先，我们必须使用标识符来标识父元素，这是因为我们根据该标识符的值更改颜色。

为了在 Javascript 中做到这一点，我们必须运行这个命令

document.documentElement.setAttribute('data-theme', 'YOUR_IDFENTIFIER');

在我们的例子中，我们希望每种样式都有两个标识符，分别是 light 和 dark。

创建 Javascript 文件来处理逻辑

现在我们有了更新标识符的函数，现在让我们创建一个包含运行该逻辑的函数的 Javscript 文件。我们的文件将被称为 app.js

在该文件中，我们将有一个函数来调用我们之前提到的代码。

var toggleTheme = function (identifier) {
 document.documentElement.setAttribute('data-theme', identifier);
}

将 Javascript 文件添加到 Blazor

通过将脚本添加到脚本所在的位置，将脚本添加到 Blazor 应用程序。

<script src="~/js/app.js"></script>

创建服务

现在我们有了 Javascript 代码，我们需要创建一个名为 ThemeToggleService 的服务。

该服务将处理在 light 和 dark 主题之间切换的逻辑。

注入 JSInterop

为了调用任何 Javascipt，我们必须调用 JSInterop，因此我们必须创建一个将注入的属性。

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }
}

设置标识符的函数

现在我们已经创建了服务，让我们创建设置标识符的函数，该函数将只更新页面中的 data-theme。

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 public class ThemeToggleService
 {
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }

 public bool IsLightTheme { get; set; } = true;
 public string GetIdentifier => IsLightTheme ? "light" : "dark";

 public async Task ToggleTheme() {
 IsLightTheme = !IsLightTheme;
 await jSRuntime.InvokeVoidAsync("toggleTheme", GetIdentifier);
 }
 }
}

添加服务启动

为了使该服务可用于所有组件和页面，我们必须将其添加到 Program.cs 文件中。

builder.Services.AddSingleton<ThemeToggleService>();

所以文件最终会是这样的

using BlazorDarkmodeToggle.Data;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSingleton<WeatherForecastService>();
builder.Services.AddSingleton<ThemeToggleService>();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

请记住，这可能会发生变化，具体取决于您使用的是 Blazor Server 还是 Blazor WebAssembly。

烘焙 CSS

现在我们已经准备好了部分代码，我们必须开始处理 CSS。我们要做的就是将所有处理 css 颜色、背景等的 css 属性设置为一个变量。

:root {
 --background-color:#ffffff;
 --text-color:#000000;
}

完成此操作后，使用标识符，我们可以轻松地在标识符之间进行更改，并且它将使用其他值之一。

[data-theme="dark"] {
 --background-color: #000000;
 --text-color: #ffffff;
}

对于很酷的动画淡入淡出，我们只需为所有属性添加一个 transition 属性，这样看起来就不错了。

* {
 transition: all 250ms;
}

现在我们将这个变量分配给一些CSS类，这样我们就可以在Blazor页面上看到它们。

.app-background {
 background-color: var(--background-color);
 width: 200px;
 height: 200px;
}

.app-text {
 color: var(--text-color);
}

请记住通过将文件添加到 head 上来将其添加到 Blazor 应用程序。

<link href="css/app.css" rel="stylesheet" />

从 Blazor 调用

那么我们要如何测试呢？为了简单起见，我们只需添加一个带有 app-background 类的 div，并且在其内部将有一个 p 和 app-text 类。因此，让我们在 Pages 文件夹下创建一个名为 Theme.razor 的页面，并为其添加一些代码

@page "/theme"
@using BlazorDarkmodeToggle.Data
@inject ThemeToggleService ThemeToggleService

<button class="btn btn-primary" @onclick=Toggle>Toggle theme</button>

<br />

<div class="app-background">
 <p class="app-text">Hello world!</p>
</div>

@code{
 public async Task Toggle()
 {
 await this.ThemeToggleService.ToggleTheme();
 }
}

我们可以通过转到 /theme 来测试这一点，但我们也将其添加到导航栏

<div class="nav-item px-3">
 <NavLink class="nav-link" href="theme">
 <span class="oi oi-list-rich" aria-hidden="true"></span> Theme togle
 </NavLink>
</div>

测试

正如您所看到的，一旦我们切换主题、背景和字体颜色更改，现在您就可以看到它有多么强大，如果您实际上在 CSS 上使用此变量开发整个页面，您可以拥有不同的主题，只需切换它们即可！

太棒了！

代码

整个项目都在 Github 上，您可以在此处找到它！

希望你喜欢这篇文章！

资源

从 ASP.NET Core Blazor 中的 .NET 方法调用 JavaScript 函数

将文件上传到 Blazor 中的 Azure Blob 存储

Wed, 23 Mar 2022 00:00:00 +0000

Azure Blob 存储服务是 Azure 生态系统上最常用的服务之一，它允许您将大量文件上传到云，同时价格超级便宜。它还具有直观的网络，您可以通过直接链接访问或下载它们。

总的来说，这是一项相当不错的服务，我一直在工作和个人项目中使用它，老实说，最好的事情是如何让它工作的简单性。

我使用 Azure Blob 存储的大多数情况都是在后端，直接上传操作结果或其他内容。所以我实际上没有从网站等上传任何类型的文件。不幸！

由于我是 Blazor 粉丝，因此我为您带来了一种使用 HTML5 的本机文件输入将文件上传到 Azure Blob 存储的方法。

先决条件

Azure 帐户（如果您没有，请使用一堆 $$$ 前往[此处]（又名.ms/免费））。
一个 IDE（VS、代码，任何都可以）
.NET Core 3.0或更高版本

创建 Azure Blob 存储

转到 Azure 门户，让我们继续创建存储帐户。

首先搜索 Storage accounts 并单击结果。

加载后，单击 Create。

将出现一个包含一系列步骤的表格，因此请继续填写它们。

使用所需的设置填充所有内容后，通过验证并创建资源。

创建后，单击 Go to resource。我们将获得一个连接字符串，让我们可以使用 API。

获取资源键

到达新创建的资源后，转到 Security + networking 下的 Acccess keys。加载后你会看到Connection string和Key，复制它们，因为我们稍后会需要它们！

创建一个很酷的 Blazor Server 项目

我将在本教程中使用 Visual Studio 2022，但正如我之前所说，您可以使用任何其他 IDE，只需使用 dotnet CLI 创建项目。

然后，让我们继续使用 Visual Studio 只需几个步骤即可快速创建 Blazor 项目。

如果我们运行刚刚创建的内容，它将如下所示，只是一个普通的 Blazor 应用程序。

现在我们已经创建了项目，让我们做一些 UI 操作，这样我们就有了一个带有一堆输入的新页面，这样我们就可以填写资源中的键、文件的 InputFile、一个用于执行某些操作的按钮以及一条操作将产生的消息。

创建模型

我们需要一些模型来正确地做到这一点。首先，我们将拥有 BlobRequest 类来处理连接字符串、容器名称和文件。

另外，为了保持一切整洁，我们将创建一个名为 BlobFile 的类，在其中存储 Name 和 Data。

我创建了一个名为 Models 的文件夹，因此我们将所有内容分开。

课程非常简单。```csharp using System.ComponentModel.DataAnnotations;

namespace UploadingFilesAzBlobBlazor.Models { public class BlobRequest { [Required(ErrorMessage = “Connection string is required”)] public string? ConnectionString { get; set; } [Required(ErrorMessage = “Container name is required”)] public string? Container { get; set; } public List? Files { get; set; } } }


```csharp
namespace UploadingFilesAzBlobBlazor.Models
{
 public class BlobFile
 {
 public string? Name { get; set; }
 public byte[]? Data { get; set; }
 }
}

修改用户界面

现在我们已经创建了模型，让我们继续用它在 UI 上施展一些魔法！

首先，在 Pages 文件夹下创建一个名为 Upload.razor 的页面。

在此页面中，我们将添加一个小表单来填充我们的 BlobRequest 类，因此我们必须为 ConnectionString、Container 和 Files 添加输入。

@page "/upload"
@using UploadingFilesAzBlobBlazor.Models
@inject IJSRuntime JsRuntime
<PageTitle> Upload</PageTitle>

<h1> Azure blob storage uploader!</h1>

<EditForm Model="@modal" OnValidSubmit="@HandleValidSubmit">
<DataAnnotationsValidator />
<ValidationSummary />

<div class="mb-3">
<label for="connectionString" class="form-label"> Connection string</label>
<InputText class="form-control" id="connectionString" @bind-Value="modal.ConnectionString" />
</div>

<div class="mb-3">
<label for="container" class="form-label"> Container name</label>
<InputText class="form-control" id="container" @bind-Value="modal.Container" />
</div>

<div class="mb-3">
<label for="formFileMultiple" class="form-label"> Files</label>
<InputFile OnChange="OnInputFileChange" class="form-control" id="formFileMultiple" multiple />
</div>

<div class="mb-3">
<button type="submit" class="btn btn-primary"> Submit</button>
</div>
</EditForm>

@code {
 private BlobRequest modal = new();
 private EditContext editContext;
 IReadOnlyList <IBrowserFile> selectedFiles;
 private void OnInputFileChange(InputFileChangeEventArgs e)
 {
 selectedFiles = e.GetMultipleFiles();
 this .StateHasChanged();
 }

 private async Task HandleValidSubmit() {
 // This is where we are going to upload stuff ! 
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
}

这是一些代码，但基本上会呈现表单并处理验证。

如果您按下上传按钮并且一切正常，它将显示一条警报。

上传到 Azure Blob 存储

现在我们已经完成了大部分 UI，现在让我们安装将处理 Azure Blob 存储 API 并允许我们上传文件的包。很简单。

添加 NuGet 包

让我们管理项目中的 NuGet 包并添加 Azure.Storage.Blob。

上传到 Azure Blob Stoare

现在让我们执行实际上传文件的逻辑，通常我们会使用连接字符串和 app.config 中的密钥，但为了本教程，我们使用输入并在那里提供数据。

首先，我们为 Azure Blob 存储类添加 using

@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models

然后我们将使用 HandleValidSubmit 方法，该方法将连接到 blob 存储，如果容器不存在则创建容器，然后上传文件。

private async Task HandleValidSubmit()
{
 try
 {
 // Instantiate container
 var container = new BlobContainerClient(modal.ConnectionString, modal.Container);
 // Create container if not exists
 var createResponse = await container.CreateIfNotExistsAsync();
 // Set access policy
 if (createResponse != null && createResponse.GetRawResponse().Status == 201)
 {
 await container.SetAccessPolicyAsync(Azure.Storage.Blobs.Models.PublicAccessType.Blob);
 }

 // For each file that we have uploaded
 foreach (var file in selectedFiles)
 {
 // New blob
 var blob = container.GetBlobClient(file.Name);
 // Delete any blob with the same name
 await blob.DeleteIfExistsAsync(Azure.Storage.Blobs.Models.DeleteSnapshotsOption.IncludeSnapshots);
 // Create a file stream and use the UploadSync method to upload the Blob.
 using (var fileStream = file.OpenReadStream())
 {
 await blob.UploadAsync(fileStream, new BlobHttpHeaders { ContentType = file.ContentType });
 }
 }

 // Display success message
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
 catch (Exception e)
 {
 // Display error message
 await JsRuntime.InvokeVoidAsync("alert", "An error ocurred!");
 }
}

测试代码

现在是测试代码的时候了，为此，只需填写表格并单击提交即可。

我们将显示一条警报，文件应上传到 Azure Blob 存储，转到 Azure 门户并查看。

如您所见，容器也已创建，现在如果我们进入容器，我们会看到我们上传的文件。

干得好！

重构

现在一切都已完成，让我们将代码从 .razor 页面移动到 .razor.cs 类，以便看起来更好。

如果您使用的是 Visual Studio 2022，当您将鼠标悬停在 @code 中时，会出现灯泡，它会向您显示 Extract block to code behind 的选项，并且它会按照说明进行操作！

现在您将把所有事情分开并完成！

代码

整个项目都在 Github 上，您可以在此处找到它！

希望你喜欢这篇文章！呀！

资源

覆盖 Pimcore 的核心控制器

Thu, 10 Dec 2020 00:00:00 +0000

我从事 Pimcore 项目已经有一段时间了，从来没有接触过 PHP 和 Symfony，所以这是一个巨大的挑战。

该文档很棒，我的意思是，说真的，它很棒，但看起来它不是为语言/框架的初学者制作的，所以我所做的一切都必须记下来。

在了解到可以使用捆绑包扩展 Pimcore 后，我花了很多时间尝试覆盖控制器、javascript 方法和更多东西。

因此，在这篇文章中，我将解释我如何设法覆盖控制器。如何覆盖 javascript 文件将在稍后介绍 😎。

创建包

首先，我们需要为其创建一个包，这非常简单，因为它记录在 Pimcore 文档中，我们只需要在项目文件夹上运行 bin/console pimcore:generate:bundle --namespace=EmiDemo/EmiDemoBundle 即可。

它会提示一些问题，但无需担心。

它将在 src 文件夹下创建一个新文件夹，其中包含我们之前声明的命名空间，其中我们将拥有该包的所有必需文件。

此外，该插件将被 Pimcore 管理站点检测到，但它将被禁用，您必须启用它才能开始使用它。

重写控制器中的方法

要覆盖控制器中的方法，首先显然您需要找到要更新的操作，这看起来很简单，但我会按照我通常的方式向您提供（从我的队友 Cesar 那里学习）。

首先进入您认为控制器采取操作的页面，在我的例子中，我想检查打开资产时加载的页面

然后只需打开控制台并进入网络选项卡，再次执行相同的步骤并尝试查找操作

通过此信息，您可以看到加载资产的操作是 http://localhost/admin/asset/get-data-by-id?_dc=1607601778450&id=2&type=image。由此我们可以看到控制器操作是get-data-by-id。

找到核心控制器中的action

对我来说，最简单的方法就是在 Visual Studio Code 中的所有文件中查找

可能它会找到多个，所以您必须看一下并决定哪一个是那个，在我们的例子中，我们正在使用资产，所以很明显我们想要使用 AssetController.php。

修改核心控制器

这取决于开发人员，我通常不这样做，因为覆盖控制器并从那里开发会更快。但我建议首先更新核心包中的控制器，看看您的更改是否有效。

在我们的例子中，我只会在方法的开头返回一条消息来检查它是否有效。

return $this->adminJson(['success' => false, 'message' => "Overriding the getDataByIdAction in the core!!"]);

然后让我们重新加载资产并检查网络选项卡

让我们保留其中的内容，以便稍后我们知道我们正在使用捆绑消息而不是核心消息。

现在，让我们将其复制到临时文件中以跟踪我们所做的事情。

将这些更改移至捆绑包

现在为了将这些更改转移到我们的包中，但首先我们需要来自核心控制器的一些内容：

命名空间
进口
控制器名称

显然，方法 getDataByIdAction 是我们想要重写的方法。

暴露控制器

我们需要公开控制器，为了做到这一点，您需要进入文件 /src/EmiDemo/EmiDemoBundle/Resources/config/pimcore/routing.yml 并添加

options:
 expose: true

此外，我们需要将 prefix 更改为我们要覆盖的控制器，在我们的例子中为 admin 控制器。

所以最后 ti 看起来像这样

emi_demo_emi_demo:
 resource: "@EmiDemoEmiDemoBundle/Controller/"
 type: annotation
 prefix: /admin
 options:
 expose: true

默认控制器.php

在我们的文件中，我们将添加导入并使用我们将覆盖的控制器扩展控制器

然后，我们只需从核心控制器复制方法，并在我们的例子中更新我们返回的消息。

如果你还记得的话，我们已经在核心控制器中有一条消息：Overriding the getDataByIdAction in the core!!，现在我们应该看到Overriding the getDataByIdAction in the bundle!!

让我们不返回任何内容，看看我们现在可以像以前一样看到页面

注释掉return语句并重新加载

就是这样

通过这个小演示，您可以看到重写现有 Pimcore 核心控制器是多么容易。您必须遵循一些步骤，但这并不难。只需确保在进行更改时公开控制器并不时清除缓存，有时它会被缓存，并且您会认为它不起作用并且只是缓存了。

如果您想知道如何覆盖 javascript 文件，它将出现在另一个教程中 😁。

在 Windows 10 上配置 Apple Magic Keyboard 2

Wed, 11 Nov 2020 00:00:00 +0000

就在昨天，我买了一台 Apple Magic Keyboard 2，即使我有大约 5 个机械键盘，因为我想尝试一下，而且它是无线的。

我的主要操作系统是 Windows 10，我喜欢它，并且不想更改它，因此考虑到这一点，我知道有必要做一些事情才能使键盘完美工作。我了解苹果的运作方式以及他们如何将自己的设备保留在其生态系统中。

问题

如果您配对键盘，您会认识到以下几点：

功能键不起作用
有些键映射错误（这发生在我的西班牙语版本中）

文档

为了使其工作，我必须从网上阅读大量内容，但这两个链接帮助我使其工作：

安装苹果键盘驱动程序

其中一些步骤来自之前提到的文档：

如果您的计算机上没有 7zip，请安装它。
如果您的计算机上没有安装Python（版本2.x）。
- 重要提示：Python 的最新版本是 3.x。但是，您需要 2.x 版本，因为准将脚本与 3.x 版本不兼容。 *（选项）默认情况下，安装程序不会将 python.exe 添加到您的 PATH 中。如果需要，您需要启用此选项。（见右侧截图）
- 如果您已经有其他版本的 Python，您可能不想启用此选项。 3.下载brigadier（一个可以帮助您下载最新Boot Camp版本的Python脚本）。
请右键单击以下链接并使用“链接另存为…”保存文件。 https://raw.githubusercontent.com/timsutton/brigadier/master/brigadier
打开命令提示符窗口（又名 DOS 框）并将目录更改为下载准将脚本的位置。
假设brigadier脚本保存为“brigadier.txt”，请运行以下命令：
- 如果 Python 版本 2.x 在您的路径中： python brigadier.txt –model=MacBook13,2
- 否则：[Python 版本 2.x 的路径]\python.exe brigadier.txt –model=MacBook13,2
它将从 bootcamp 下载一个包含所有驱动程序的大包
创建一个名为 BootCamp 的文件夹，并将 BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\BootCamp.msi 和 BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\AppleKeyboardMagic2 复制到其中。
运行管理 powershell 并执行 BootCamp.msi，它将安装一些东西，但我们需要使用 AppleKeyboardMagic2 文件夹的内容更新驱动程序 11.启动设备管理器（devmgmt.msc） 12.展开Human Interface Devices节点 13.寻找Bluetooth HID Device
使用 AppleKeyboardMagic2 文件夹的内容更新驱动程序
重新启动计算机

您应该看到蓝牙键盘现在被检测为 Apple 键盘

更新 FN 键行为如果您正确安装了所有内容，您会注意到默认情况下启用了 FN 键，这意味着您需要按 `fn` + `F5` 才能实际按下 `F5` 按钮。

为了解决这个问题，我找到了一个解决方案，在文档部分中指出，该解决方案通过更改注册表中的某些条目来起作用。

1.打开注册表 2. 前往HKEY_CURRENT_USER\SOFTWARE\Apple Inc.\Apple Keyboard Support 3. 创建或更新 OSXFnBehavior 并将其设置为 0 4. 重新启动计算机

更新按键映射

如果您对映射有疑问，可以使用 SharpKeys 并更新它们。

它使用起来非常简单，但请记住注销或重新启动计算机以启用更新，因为它会更新注册表。

就我而言，我必须更新 Windows、alt、º 和 <> 键。

将编译的库添加到 NuGet 包

Thu, 01 Oct 2020 00:00:00 +0000

就在前几天，我在缺失的库上发现了一个关于 NullReferenceException 的错误，该库应该存在，因为它来自我们上传的 nuget 包。

基本上，我编译了一个引用了几个项目的库类。在构建阶段，它会将 dll 文件添加到 bin 文件夹中，但是当 packaging 将其作为 nuget 包并将其安装在另一个解决方案中时，我引用并应复制到 bin 文件夹中的 dll 文件不在那里。

怎么解决

解决这个问题非常简单，您必须更新 nuspec 文件，并对于要复制的每个库，在 files 部分添加 file 。

<?xml version="1.0" encoding="utf-8"?>
<package >
 <metadata>
 <id>$id$</id>
 <version>$version$</version>
 <title>$title$</title>
 <authors>$author$</authors>
 <owners>$author$</owners>
 <requireLicenseAcceptance>false</requireLicenseAcceptance>
 <license type="expression">MIT</license>
 <projectUrl>$projectUrl$</projectUrl>
 <iconUrl>$projectIconUrl$</iconUrl>
 <description>$description$</description>
 <releaseNotes></releaseNotes>
 <copyright>$copyright$</copyright>
 <tags></tags>
 </metadata>
 <files>
 <file src="bin\Release\MyFile1.dll" target="lib\net47" />
 <file src="bin\Release\MyFile2.dll" target="lib\net47" />
 <file src="bin\Release\MyFile3.dll" target="lib\net47" />
 <file src="bin\Release\MyFile4.dll" target="lib\net47" />
 </files>
</package>

在 WSL 主目录上使终端加载 bash

Tue, 22 Sep 2020 00:00:00 +0000

从 WSL 面世之日起，我就一直喜欢使用 WSL 进行开发和测试，然后终端应用程序就被删除了，我非常高兴，它看起来不错，工作完美，性能也很棒。

如果不将其与 WSL 发行版一起使用而不是使用为您提供的控制台，那将是愚蠢的。

这个控制台显然很好，但是当你使用了终端之后，就再也回不去了。它真的好多了，还有颜色。

现在，如果您启动终端并打开一个新选项卡来加载 WSL 发行版，它将加载您已安装的用户文件夹。

这并不是真正的问题，因为如果您只是执行 cd ~ 它只会加载发行版用户文件夹。

问题是我不想一次又一次地这样做，所以让我们更新一个文件来自己完成它。

.bashrc

启动终端或控制台，进入您的配置文件文件夹，然后使用您喜欢的文本编辑器编辑 .bashrc 文件。

在文件末尾最后一条指令之前添加 cd ~。

保存，使用终端重新打开 WSL 控制台，您应该位于配置文件文件夹中。

请记住，您必须对所有 WSL 安装执行此操作，因为我们正在更新单个 WSL 安装的 bashrc 文件。

使用 ExpandoObject 生成动态对象

Fri, 06 Mar 2020 00:00:00 +0000

我一直需要将具有自己定义的列的 Excel 文件转换为具有动态列的新文件，并且我对如何在不出现严重性能问题的情况下正确执行此操作感到有点困惑。

我提出了一个教程，您可以在此处找到它，该教程使用.NET ExpandoObject，它几乎可以让您创建一个对象并添加动态成员。

扩展对象

微软的定义是：

表示一个对象，其成员可以在运行时动态添加和删除。

它有一些注释：

ExpandoObject 类使您能够在运行时添加和删除其实例的成员，以及设置和获取这些成员的值。此类支持动态绑定，这使您能够使用标准语法（如sampleObject.sampleMember），而不是更复杂的语法（如sampleObject.GetAttribute(“sampleMember”)）。

当前行为

我们有一个 ExcelExportService，通过传递 List<T>（在本例中为 ExcelItem），将使用 Reflection 创建一个 xlsx 文件。

到目前为止，我们的代码如下所示：

class ExcelItem
 {
 public int Id { get; set; }
 public string Name { get; set; }
 public string Surname { get; set; }
 public string Age { get; set; }
 public string CreatedAt { get; set; }
 public string UpdatedAt { get; set; }
 }

ExcelItem 是具有用于生成 Excel 文件的所有属性的对象。

public static byte[] GetExcelBytes() {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var items in itemsToExcel)
 {
 excelItems.Add(new ExcelItem()
 {
 Id = item.Id,
 Name = item.Name,
 Surname = item.Surname,
 Age = item.Age,
 CreatedAt = item.CreatedAt
 UpdatedAt = item.UpdatedAt
 });
 }

 return exportService.ExportToExcel(excelItems);
}

这种方法工作得很好，xlsx 文件生成时没有问题，每列都是每个属性，您可以使用这个 GetExcelBytes 方法，例如，将其保存到文件中：

File.WriteAllBytes("path-to-somewhere/my-file.xlsx", GetExcelBytes());

问题

由于我们所做的正确知道是使用 ExcelItem 对象的所有属性，所以我想要的只是实际上不使用所有它们，只使用其中的 2 或 3 个。

还有一个要求是我不想更改代码，一切都应该由 administrator 完成，他将决定应该显示哪些列，并且他可能知道也可能不知道代码中的属性。

TLDR：一切都应该是动态的，我们有一个具有属性的对象，我们必须确保生成的文件具有该对象的 N 属性，但显然不是硬编码的。

动态列

更改是使用 dynamic 对象，因为我们想设置该对象的哪些属性将用于生成列列表。

假设我们有一个具有很多属性的对象，例如大量，并且我们并不真的希望每次进行更改时都更改 ExcelItem 对象，我们创建一个 ColumnExcelItem 表，该表将用于生成 ExcelItem。

数据库结构

我们将此定义保存在数据库中，如下所示：

Id PropertyName
---------------------
1 Name
2 Surname
3 Age

请注意，我们的值少于 ExcelItem 对象的现有属性，它具有 6 属性，而我们仅在数据库中列出了 3。

另请注意，PropertyName 必须与我将用于动态分配的对象的属性名称匹配。

构建对象

现在我们有了数据库表，我们需要构建存储库来获取它并能够在代码中使用它们。我不会制作这部分的教程，我将在新的 GetExcelBytes() 函数的开头跳过。

public static byte[] GetExcelBytes(List<string> columns) {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 List<dynamic> objectsToExcel = new List<dynamic>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var item in itemsToExcel)
 {
 dynamic newObject = new ExpandoObject();
 foreach (var col in columns)
 {
 this.AddProperty(newObject, col, product.GetType().GetProperty(col).GetValue(item, null));
 }

 objectsToExcel.Add(newObject);
 }

 return exportService.ExportToExcel(objectsToExcel);
}

现在我们将创建一个具有 ExcelItem 的一些属性的对象，但完全是动态的。我们没有使用所有 6 个属性，而是只使用其中的 3 个，即我们只想发送的属性。

现在让我们假设这个 ExcelItem 对象有 200 个属性，疯狂，但这可能会发生。

我唯一要做的就是将要渲染到 Excel 文件中的那些属性插入到 ColumnExcelItem 表中，仅此而已。

案例

在本例中，我们只使用了一个案例，但假设您希望为某些用户提供不同的报告。假设 admin 角色应该获取所有属性，那么您将在数据库中创建类似这样的结构

ReportingTemplates

Id PropertyName
---------------------
1 Admin
2 Users

ReportingTemplateItems

Id TemplateId PropertyName
---------------------
1 1 Id
2 1 Name
3 1 Surname
4 1 Age
5 1 CreatedAt
6 1 UpdatedAt
7 2 Name
8 2 Surname
9 2 Age

然后通过获取模板，您可以拥有不同的列，所有列都是动态的并且没有代码相关。

如果我们有一个角色为 Admins 的用户，则该文件将包含列 Id、Name、Surname、Age、CreatedAt、UpdatedAt。

如果您使用 Users 角色生成它，它将具有 Name、Age。 Surname。

结论

这是学习 dynamic 在 .NET 中如何工作的一种很酷的方法，当您需要为不同的用户提供不同的角色或模板，并且对投入时间硬编码内容不感兴趣时，这确实是一个很好的解决方案。

使用 TravisCI 持续交付 NuGet 包

Tue, 21 Jan 2020 00:00:00 +0000

最近我做了一个教程，介绍如何使用 Travis CI 作为工具来自动测试您刚刚推送或尝试推送到 master 分支的代码。对其进行编译和测试，并最终向您报告更改的状态。

但我们可以继续让它变得更好，例如上一个教程中制作的核心库，我想使用 NuGet feed 将其公开，这样每个人都可以在他们的库中轻松操作！

但是如何？ 我们如何编译、测试该包，然后将该包发布到提要中，以便每个人都可以在他们的项目中下载它？

好了，这就是 😁 的教程！

＃什么是新的？

代码几乎没有变化，我们需要改变的是打包、发布以及如何自动化它。

.NET Core CLI

我们将使用 .NET Core CLI，我们在上一个教程中使用了 dotnet restore、dotnet build 和 dotnet test 等命令。

现在我们将使用一组新命令！

`dotnet nuget`

您可以在此处查看这套工具的文档，但有一个简短的解释：

dotnet nuget 是一组基本工具，包括安装、恢复、删除和发布包。

NuGet 提要

NuGet 是 .NET 的包管理器。 NuGet 客户端工具提供了生成和使用包的能力。 NuGet Gallery 是所有包作者和使用者使用的中央包存储库。

NuGet 是免费的，因此您可以注册并获取 API 密钥并开始上传包。它们将被上传、验证，然后为所有人列出。

获取API密钥

为了上传您的软件包，您需要在注册后获取 API 密钥，因此请转到 API 密钥页面并创建一个新密钥。

请记住，API 密钥的有效期为 365 天。

然后复制您的密钥并将其存储在某个地方，如页面中所述，您将无法再次看到它，如果您没有保存它，则必须重新生成它。

生成NuGet包

现在我们已经有了 API 密钥，下一步是从解决方案生成 NuGet 包，因此请继续打开包含类库的解决方案。

我将使用上一篇教程中的解决方案，其中有一个名为 CalculatorCLI.Core 的 .NET Core 库类。

现在转到项目属性，然后转到程序包，您将看到有关程序包的大量信息，例如程序包版本、作者、描述等。

接下来是填写此内容，您实际上不必填写所有内容，但重要且强制的内容是 Package id、Package version、Authors 和 Description。另外，如果您尝试自己上传文件，它将要求 License，我们也需要添加它。

然后你可以保存，右键单击项目并选择Pack。

1>------ Build started: Project: CalculatorCLI.Core, Configuration: Debug Any CPU ------
1>CalculatorCLI.Core -> D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\netstandard2.1\CalculatorCLI.Core.dll
1>Successfully created package 'D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\CalculatorCLI.Core.1.0.0.1.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

输出将显示，如果一切正常，它将打印 Successfully created package。

使用 `dotnet`

与上一个教程一样，我们使用不同的命令来构建和测试解决方案。现在，我们将添加更多命令来打包和发布包。

这些命令是：

dotnet pack -c <configuration>
dotnet nuget push <package> <k <apikey> -s <source>

部署脚本

当我们要改变构建方式时，我相信拥有不同的文件，每个文件都包含取决于环境的构建定义，将是最好的主意。

因此，让我们在存储库的根目录中创建一个名为 scripts 的文件夹，其中包含三个 bash 脚本。

scripts\compile.sh

#!/bin/sh

echo "Restoring..."
dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

echo "Building..."
dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release

scripts\test.sh

#!/bin/sh

echo "Testing..."
dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

scripts\push.sh

#!/bin/sh

echo "Packing..."
dotnet pack ./CalculatorCLI/CalculatorCLI.Core/CalculatorCLI.Core.csproj -c Release

echo "Pushing..."
dotnet nuget push ./CalculatorCLI/CalculatorCLI.Core/bin/Release/*.nupkg -s "https://nuget.org" -k $NUGET_API_KEY

改进 `.travis.yml` 文件

现在我们已经更新了源代码，我们知道了需要使用的命令，我们需要将持续交付与持续集成相集成。这样我们除了编码、测试、审查和推送之外实际上不需要做任何事情。

我们现在要对 .travis.yml 文件执行以下操作：

1.添加不同的stages 2. 每个stage取决于分支 3. 如果您的构建是在 master 上，则意味着必须更新包，因此我们将把包推送到 NuGet feeds 4. 如果您的构建是拉取请求，我们仍然会检查构建是否可以编译并测试，但我们不会发布它。

阶段

从他们的文档中：

您可以通过在构建配置（您的 .travis.yml 文件）中指定条件来过滤和拒绝构建、阶段和作业。

您可以在其文档页面中找到有关 TravisCI stages 的更多信息。

因此，我们将更改文件并添加阶段，最终结果如下：

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

jobs:
 include:
 - stage: compile
 script: bash scripts/compile.sh

 - stage: test
 script: bash scripts/test.sh

 - stage: deploy-prod
 if: branch = master AND type = push
 name: "Deploy to NuGet"
 script: bash scripts/push.sh

正如您所看到的，我们有三个不同的阶段 compile、test 和 push，最后一个阶段仅在 branch 为 master 时运行，并且它不是 pull request，而只是 push。

如果您不明白这一点，只需查看文档即可，它的解释非常简单。

考虑到这一点，所有 pull request 都不会将任何内容推送到 NuGet feed。

将 API 密钥设置为环境变量

转到存储库构建的设置并添加一个名为 NUGET_API_KEY 的新环境变量，其值是从 NuGet 页面复制的 api 密钥。

创建一个 `pull request`

现在我们已经完成了所有设置，是时候创建一个 pull request 并检查该拉取请求的编译是否忽略了最后一个 stage。

检查构建

当您发出拉取请求时，一个构建将在 TravisCI 仪表板中排队，正如您所看到的，我们有 2 个不同的构建，而不是三个。

现在让我们接受 pull request 并再次检查构建，看看我们现在有三个作业而不是两个。

一旦您看到正在排队的构建，您就可以看到三个作业，包括末尾的 Deploy-prod。

整个构建完成后，您可以在日志中看到该包已被推送到源。

显然你可以在 NuGet 页面中看到它

就是这样

在本教程中，我们了解了如何自动化 NuGet 包交付。我们使用了一些工具，例如 TravisCI、stages 和 dotnet nuget。

在我看来，即使这需要时间来正确设置，并且在某些情况下可能过于复杂。为了让一切变得完美和自动化，在这种技术上投入时间是值得的。

您可以在此处中找到源代码，如果您有任何疑问，请随时通过我的 twitter 与我联系！

使用 TravisCI 持续集成 .NET Core 3.0 项目

Tue, 14 Jan 2020 00:00:00 +0000

上周末，我决定要正确启动我一直在不同存储库中执行的 scraper-checker-downloader 项目。

在开始另一个项目之后，这必须很酷，就像真正的酷，使用 CI/CD、拉取请求、文档、自述文件中的徽章，我所看到的一切都很酷，而且确实是最佳实践。

经过一个愉快的周末后，我最终创建了 Dramarr，这是一套可以从不同来源抓取和下载节目的工具。

它在组织中有不同的存储库，其中大多数是在拉取请求中以及在合并到主分支中时正在编译、测试和部署自身的库。

这就是所谓的 CI/CD 或持续集成/持续交付。

但在本教程中我们只讨论 CI。

持续集成

这是什么？

摘自 Martin Fowler 的博客，这是我读过的最好的解释：

持续集成是一种软件开发实践，团队成员经常集成他们的工作，通常每个人至少每天集成 - 导致每天多次集成。每个集成都通过自动构建（包括测试）进行验证，以尽快检测集成错误。

工具

有许多工具可将您的工作流程与 CI/CD 集成，但在本教程中，我们将使用 Github 来存储我们的代码，并使用 TravisCI 工具来设置 CI。关于语言和框架，我们将使用C#和新的.NET Core 3.0。

要求

为了使这项工作成功，您需要三件简单的事情：

1.Visual Studio 2019最新版本 2.Github账号 3. Travis-CI 帐户链接到您的 Github 帐户

项目

在本教程中，我们将使用一个简单的计算器。我们将创建一个库、一个命令行工具和一个测试项目来测试一切。

当我们设置 CI 时，这个测试项目也将运行，这意味着如果将来我们对代码进行更改并且我们最初创建的测试未通过，我们将收到通知，或者我们可以简单地拒绝拉取请求。

创建 Github 存储库

首先，我们将创建一个 Github 存储库，因此请访问 Github 并创建存储库并将其克隆到本地环境。我决定将这个新存储库命名为 CalculatorCLI-demo。

<imgalign=“中心”src=“https://i.gyazo.com/0657eb2bdeb3c331b9e4585d7deed5ef.png">

创建解决方案

现在让我们在克隆存储库的根文件夹中创建一个名为 CalculatorCLI 的空解决方案

核心库

就像在现实世界的项目中一样，我们将把逻辑存储在一个生成库的单独项目中，所以让我们创建它。

去创建一个 Class Library (.NET Standard) 并将其命名为 CalculatorCLI.Core

NET 核心版本创建项目后，请转到项目属性并将 `Target framework` 更改为 `.NET Standard 2.1`，以使其与 `.NET Core 3.0` 中构建的项目兼容。

代码

为了本教程的目的，让我们创建一个处理操作的简单类。

using System;

namespace ConsoleCalculator.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.ADD;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

命令行界面

现在我们已经有了核心项目，让我们创建应用程序。在本例中，它将是一个简单的控制台应用程序，它接受参数并显示输出结果。

那么让我们继续创建一个新的 Console App (.NET Core)，我将其命名为 CalculatorCLI.CLI。

NET 核心版本

正如我们之前所做的那样，一旦您创建了项目，请转到项目属性并将 Target framework 更改为 .NET Core 3.0（如果不是这样的话）。

然后将对 ConsoleCLI.Core 的引用添加到我们新创建的项目中。

代码

现在对于代码来说，这比以前更简单。

using ConsoleCalculator.Core;
using System;
using System.Text.RegularExpressions;

namespace ConsoleCalculator.CLI
{
 public class Program
 {
 public static void Main(string[] args)
 {
 if (args.Length == 0)
 {
 PrintUsage();
 }
 else
 {
 var joinedArgs = string.Join(" ", args);
 var regex = @"-op [\+\-\*\/] -l [-0-9]+ -r [-0-9]+";

 if (Regex.IsMatch(joinedArgs, regex))
 {
 int _left = Int32.Parse(args[3]);
 int _right = Int32.Parse(args[5]);
 string _operator = args[1];

 var _operation = new Operation(_operator, _left, _right);
 var _result = _operation.DoOperation();

 Console.WriteLine($"Result is: {_result}");
 }
 else
 {
 PrintUsage();
 }
 }
 }

 public static void PrintUsage()
 {
 Console.WriteLine($"Welcome to ConsoleCalculator!");
 Console.WriteLine($"");
 Console.WriteLine($"-op Operator, it must be +,-,*,/");
 Console.WriteLine($"-l Left number");
 Console.WriteLine($"-r Left number");
 Console.WriteLine($"");
 Console.WriteLine($"Example usage: -op + -l 5 -r 6");
 }
 }
}

我们将从命令中使用这个应用程序，因此为了使其工作，我们必须传递一些参数来调用它。例如：

ConsoleCalculator.CLI.exe -op + -l 10 -r 20

翻译过来就是：

ConsoleCalculator.CLI.exe -operator + -leftValue 10 -rightValue 20

其代码非常简单，如果它与某个正则表达式模式不匹配，则这是一个错误的调用，它会调用 PrintUsage()。这意味着，如果我们输入与数字不同的东西，因为它是在正则表达式上设置的，它甚至不会尝试进行计算。

这意味着，如果我们这样称呼它：

ConsoleCalculator.CLI.exe -operator + -leftValue asdfg -rightValue ghjk

它永远不会进入操作逻辑内部，我们将保存未来的检查，例如 TryParse 值。

测试

我们有核心库和命令行，但我们现在需要测试，因为这就是我们想要在 CI 中做的事情。

因此，让我们继续创建一个新的 MSTest Test Project (.NET Core) 并将其命名为 CalculatorCLI.Tests。

NET 核心版本

正如我们之前所做的那样，一旦您创建了项目，请转到项目属性并将 Target framework 更改为 .NET Core 3.0（如果不是这样的话）。

然后将对 ConsoleCLI.Core 和 ConsoleCLI.Core 的引用添加到我们新创建的测试项目中。

代码

我们将把测试分成两个不同的文件：CoreTests.cs 和 CLITests.cs

using CalculatorCLI.Core;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CoreTests
 {
 public int _left = 2;
 public int _right = 2;

 [TestMethod]
 public void ShouldAdd()
 {
 var expectedResult = 4;
 var operation = new Operation("+", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var expectedResult = 0;
 var operation = new Operation("-", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var expectedResult = 4;
 var operation = new Operation("*", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var expectedResult = 1;
 var operation = new Operation("/", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 [ExpectedException(typeof(System.DivideByZeroException))]
 public void ShouldThrowExceptionForDivideByZero()
 {
 var operation = new Operation("/", _left, 0);
 operation.DoOperation();
 }

 [TestMethod]
 [ExpectedException(typeof(System.Exception), "Operator invalid")]
 public void ShouldThrowExceptionForWrongOperator()
 {
 var operation = new Operation("text", _left, 0);
 operation.DoOperation();
 }
 }
}

using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CLITests
 {
 public string _left = "2";
 public string _right = "2";

 [TestMethod]
 public void ShouldAdd()
 {
 var args = new string[] { "-op", "+", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var args = new string[] { "-op", "-", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var args = new string[] { "-op", "*", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var args = new string[] { "-op", "/", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }
 }
}

创建完所有内容后，我们最终将得到如下解决方案：

<imgalign=“center"src=“https://i.gyazo.com/ffecc23a14d796af9a46dbb390c0d072.png"/> />

现在我们可以运行测试了，因此请转到 Visual Studio 中的 Test Explorer 并运行它们！

特拉维斯 CI

如果您现在还不知道，TravisCI 是一个托管的持续集成和部署系统。

这里我们必须执行一些步骤，但首先我们将链接我们的 Github 存储库以供 TravisCI 代理监听，以便构建和测试我们的项目。

启用存储库

为此，请登录 Travis CI 页面并转到您的存储库，然后通过单击存储库名称旁边的滑块来过滤您创建的项目并启用它。

<imgalign=“中心”src=“https://i.gyazo.com/28b366dddd3f5caa9100ca6b6d200764.png”>

创建.travis.yml我们需要在项目的根目录中创建一个名为 `.travis.yml` 的文件，这是因为如文档中所述：

Travis 仅在添加 .travis.yml 文件后在您推送的提交上运行构建。

因此，使用以下行在存储库的根目录中创建一个 .travis.yml 文件：

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

before_script:
 - dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

script:
 - dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release
 - dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

我不会详细介绍 .travis.yml 文件的工作原理，但让我们回顾一下它的作用：

我们设置语言为csharp。
我们不会使用 mono 因为 .NET Core 3.0 将在 Linux 中本机运行。
我们将 dotnet 版本设置为 3.0。
我们设置了os，默认是linux，但我还是添加了它。
现在我们有了 before_script ，它将在主要逻辑之前获胜。这里，所以我所做的是运行 dotnet restore 到解决方案，以便稍后一切都完美加载。
现在在 script 中，我们将对我们的解决方案执行 dotnet builld 和 dotnet test，这将检查它是否已编译，然后运行测试。

我们完成了！

上传到master

现在我们只需要把一切都推向掌握即可。

git add --all
git commit -m "Initial files"
git push

检查持续集成

我们可以在存储库页面或 TravisCI 仪表板中检查推送到 master 的 CI 状态。

进展情况

<imgalign=“中心”src=“https://i.gyazo.com/977ea42a90adccf0736464b6603867a5.png”>”

<imgalign=“中心”src=“https://i.gyazo.com/52a5f9356df5436c862b7df6fe66a9f4.png">”

完成

<imgalign=“中心”src=“https://i.gyazo.com/c3d3521925a3e20bcf55bf5f6a2a711d.png">”

<imgalign=“中心”src=“https://i.gyazo.com/8c749c2ce44837a39fc5cd3e8838a798.png">”

让我们打破它

现在为了看看它有多强大，让我们破坏代码并更改核心库以使其失败。

代码更改

因此，请转到 Operation.cs 并更改一些会破坏某些测试的内容。

using System;

namespace CalculatorCLI.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

如果我们再次运行测试，因为我们将情况更改为加法，它将失败：

case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;

正如预期的那样，ShouldAdd 情况失败了：

<imgalign=“中心”src=“https://i.gyazo.com/a57d0a0f8c07cc1ab6e4f55a8466cbbd.png">

现在提交此更改并将其推送到 master，然后等待 TravisCI 代理的结果。

git add --all
git commit -m "Breaking changes"
git push

构建

现在让我们查看 TravisCI 日志，我们将看到我们成功地破坏了项目，因为集成测试失败并且构建状态为错误。

<imgalign=“中心”src=“https://i.gyazo.com/397befe9b7f5a32b6e97511733296b00.png">”

在日志的最后我们可以看到错误本身：

<imgalign=“中心”src=“https://i.gyazo.com/e5cbf32c5dd7a08bf6628d81edff3130.png">”

让我们再次修复它！

现在恢复我们所做的并将代码推送到 master，并检查新构建的状态。

测试成功通过：

<imgalign=“中心”src=“https://i.gyazo.com/02deb8fcb4fca618ff2d79f1c27c6df5.png">”

并且构建也成功了：

<imgalign=“中心”src=“https://i.gyazo.com/38a227f0634c6040c6608f8c51f36cd3.png">”

结论

真的很强大，CI和CD很早以前就已经存在了，但现在让它在每个项目中运行都非常简单，不管它有多小或多简单。从我的角度来看，每个人至少应该为他们的每个项目设置 CI，因为这是一个很好的实践，它最终会节省你调试和查找错误的时间，如果你设置了正确的 tests 和 CI，这些错误就不会发生。

就是这样

这就是如何创建一个 .NET Core 3.0 解决方案，该解决方案在使用 TravisCI 的每个构建上进行持续集成并将代码存储在 Github 中。

您可以在此处找到该项目的源代码。

我对内存缓存的看法

Tue, 03 Sep 2019 00:00:00 +0000

我一直在研究一些处理大量数据的东西。在这样做的过程中，我意识到其中很大一部分永远不会改变，或者至少在一段固定的时间内不会改变。

所以我认为创建个人缓存存储库会很有用，当然这不是什么新鲜事，几周前我在 StackOverflow 的 post 中读到了由 Nick Craver 撰写的关于他们如何管理应用程序缓存的内容。

另外，我一直想使用缓存，它是如何工作的，逻辑以及如何让它工作，所以…为什么不！

流量

下面是一个快速流程，展示了当用户请求一个值时，拥有缓存控制权的类将如何表现。

实施

在我们开始之前

我知道，我知道。 System.Runtime.Caching 处理内存缓存。但我决定自己构建它，如果您想使用该类，请查看此处以获取操作方法。

缓存项

第一步是拥有一个存储对象值和到期日期的类。可能有更好的方法来做到这一点，但这就是我的想法，所以你可以：

public class CacheItem
{
 public string Identifier { get; set; }
 public object Value { get; set; }
 public DateTime ValidUntil { get; set; }

 public CacheItem(string identifier, object value, TimeSpan valid)
 {
 Identifier = identifier;
 Value = value;
 ValidUntil = DateTime.UtcNow.Add(valid);
 }
}

缓存存储库

然后我们需要一个类来处理对象并将它们保存在某个地方（如 CacheItem）。我喜欢处理具有后缀 Repository 的类中的所有数据/模型，但您不必，所以让我们构建一个用于缓存。

public class CacheRepository
{
 private static Dictionary<string, string> Cache = new Dictionary<string, string>();
 private static T Set<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var item = new Models.Item(key, lookup(), durationMinutes);
 return Save<T>(key, item);
 }
 private static T Save<T>(string key, Item item)
 {
 Cache[key] = JsonConvert.SerializeObject(item);
 return (T)item.Value;
 }
 private static T Get<T>(string key)
 {
 var cached = Cache.FirstOrDefault(x => x.Key == key).Value;
 var item = string.IsNullOrEmpty(cached) ? null : JsonConvert.DeserializeObject<Item>(cached);
 return (item == null)
 ? default : (item.ValidUntil > DateTime.UtcNow)
 ? JsonConvert.DeserializeObject<T>(JsonConvert.SerializeObject(item.Value)) : default;
 }
 public static T GetOrSet<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var cache = Get<T>(key);
 return cache == null ? Set(key, lookup, durationMinutes) : cache;
 }
}

到目前为止，我们有一个名为 Cache 的静态字典，其中将存储所有项目。请记住，这只会在应用程序运行时持续，因此这个教程标题中有内存缓存。

请记住，一旦加载 CacheRepository 类，Cache 项就会被初始化。

调用 CacheRepository 类时唯一可用的方法是 GetOrSet(string key, Func<T> lookup, TimeSpan durationMinutes)，它需要三个参数：

key：要保存的对象的标识符。
lookup：缓存过期或为空时的回调函数。
durationMinutes：将添加到当前时间（UTC 时间）的持续时间（以分钟为单位）。

缓存时间

现在，使用我们的缓存存储库从某处获取一些数据。

为了使所有这些都有意义，让我们创建一个具有一些属性的示例对象，然后创建一个存储库来获取并填充该对象的列表。

public class User
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public string Email { get; set; }
}
public class UserRepository
{
 public List<User> Get()
 {
 // Code to get users
 }
}

由于我们有填充 User 列表的方法，所以让我们使用 CacheRepository 类。

private UserRepository _userRepository = new UserRepository();
private List<User> _user;
public List<User> User
{
 get
 {
 _user = CacheRepository.GetOrSet($"users", usersRepo.Get, TimeSpan.FromMinutes(10));
 return _user;
 }
}

就像这样，每次访问变量 User 时，它都会向 CacheRepository 询问具有键 users 的对象的值。

如果该密钥存在，它将检查到期日期。如果这些条件之一为 false，它将使用回调来设置对象的值（使用 usersRepo.Get），将其保存到缓存，并将到期日期设置为 DateTime.UtcNow + TimeSpan.FromMinutes(10) 并返回它。

使用 Devtools 截取页面屏幕截图

Thu, 09 May 2019 00:00:00 +0000

有时，我需要向客户或团队成员展示网站当前状态的完整屏幕截图，甚至是网站的一部分，因此我一直在使用全页屏幕截图，对于任何其他类型的屏幕截图，我使用Windows 片段工具或 Snaggit。如果我想像这篇文章 Gyazo 那样在线托管它，它也有一个 GIF 制作器。

最近发现Devtools有一个可以全屏截图的工具，不需要扩展！

这不是新想法，它已包含在 2017 年 4 月的 Devtools 更新中，但看起来我住在岩石下，直到现在才发现……

开发工具

正如官方 Devtools 页面中所述：

Chrome DevTools 是一组直接内置于 Google Chrome 浏览器中的 Web 开发人员工具。 DevTools 可以帮助您即时编辑页面并快速诊断问题，最终帮助您更快地构建更好的网站。

在 Devtools 中运行命令

您已经知道如何打开 Devtools，但如果您忘记了并且为了本文的目的，请使用键 F12 或快捷方式 Ctrl + Shift + I 打开它。然后您必须打开 Devtools 内菜单中的 Run command 或使用 Ctrl + Shift + P。

截图工具

如果您输入screenshot，它将过滤命令，您可以使用 4 种类型的屏幕截图方法：

1.区域截图 2.全尺寸截图 3.节点截图 4. 截图

在检查所有截图方法之前，devtools处理完图像后，会自动以网页名称下载。

区域截图

area screenshot 将让您选择网站的一部分并进行屏幕截图。

结果：

全尺寸截图

full size screenshot 将从头到尾截取整个网页的屏幕截图。

结果：

节点截图

node screenshot 将让您制作检查元素中选定节点的屏幕截图。

结果：

捕获屏幕截图

capture screenshot 将在不滚动的情况下截取当前页面的屏幕截图以及浏览器的大小。

结果：

使用 .NET Framework 中的嵌入式和外部资源的自定义语言

Mon, 06 May 2019 00:00:00 +0000

简介

在工作中，我们遇到了一个正常的问题，我确信很多开发人员都必须处理这个问题，即来自向其客户提供我们服务的客户的语言和自定义语言。

例如，假设基本语言使用非正式语言，而客户需要正式语言，因为他们的客户是老年人。

另请注意，该解决方案适用于多种语言，我们将使用英语和西班牙语。

我的母语不是英语，对于教程中的任何错误，我深表歉意。如果您发现错误并想要修复它们，您可以在 this repo 上打开拉取请求，我很乐意批准它！

资源

资源是扩展名为 .resx 的 XML 文件，它们具有键/值结构，如下所示：

<?xml version="1.0" encoding="utf-8"?>
<root>
 <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
 <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
 <xsd:element name="root" msdata:IsDataSet="true">
 <xsd:complexType>
 <xsd:choice maxOccurs="unbounded">
 <xsd:element name="metadata">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" />
 </xsd:sequence>
 <xsd:attribute name="name" use="required" type="xsd:string" />
 <xsd:attribute name="type" type="xsd:string" />
 <xsd:attribute name="mimetype" type="xsd:string" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="assembly">
 <xsd:complexType>
 <xsd:attribute name="alias" type="xsd:string" />
 <xsd:attribute name="name" type="xsd:string" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="data">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
 <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
 <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="resheader">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" />
 </xsd:complexType>
 </xsd:element>
 </xsd:choice>
 </xsd:complexType>
 </xsd:element>
 </xsd:schema>
 <resheader name="resmimetype">
 <value>text/microsoft-resx</value>
 </resheader>
 <resheader name="version">
 <value>2.0</value>
 </resheader>
 <resheader name="reader">
 <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <resheader name="writer">
 <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <data name="Action_cancel" xml:space="preserve">
 <value>Finish</value>
 </data>
 <data name="Action_greeting" xml:space="preserve">
 <value>Hello</value>
 </data>
</root>

我们将为两种不同的语言创建资源：英语和西班牙语，因此文件的命名法将为：resources.ISOLANGUAGECODE.resx，例如：resource.es.resx 为西班牙语，resource.resx 为英语，如果我们稍后要添加德语，文件将被命名为 resource.de.resx。

嵌入资源

内嵌资源，项目编译时会添加到dll里面。

这是一个带有嵌入资源的图像，如您所见，文件 Resource.resx 在编译中看不到。

外部资源

另一方面，外部资源或未嵌入的资源是编译后将添加到文件夹中的资源。

资源文件 (.resx) 将位于 Properties 文件夹内

构建项目

让我们从 .NET Framework 中的控制台项目开始。

创建嵌入资源文件

添加一个带有几个键的资源文件，并确保它是嵌入式资源，稍后我们将使用它来更新外部资源。

创建外部资源文件

为了将外部资源与嵌入资源分开，我们将在一个带有名称的文件夹中添加外部资源，以便以后可以轻松访问它们。

提示：要在 Properties 文件夹内添加文件夹，请在外部创建并将其移至内部，Visual Studio 不允许您创建它

执行与嵌入资源相同的操作，然后转到文件的 properties 和 Advanced、Build action 内部，并将其更改为：Content 并将 Copy to Output Dictionary 更改为 Copy if newer。

它应该是这样的：

添加一个键到app.config

因为我们是很酷的开发人员，喜欢把一切都做好，并且不更改每个客户端的代码，所以让我们向 appconfig 添加一个键，该键将具有我们将要查找资源文件的文件夹的名称

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <startup>
 <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
 </startup>
 <appSettings>
 <add key="CustomResources.Folder" value="John" />
 </appSettings>
</configuration>
```因此，稍后，当我们查找资源时，它将查找 `Properties.John` 而不是 `Properties.Doe`。

此外，当应用程序已经部署时，这使得更改变得更容易，因为您可以轻松更改 app.config。

## 访问嵌入的资源文件

使用 .NET Framework 相当简单，因此为了访问嵌入式属性，我们只需使用 `Properties` 对象，该对象将资源文件作为属性，并且在该对象内部将包含 `resx` 文件中的所有键/值。

```csharp
static void Main(string[] args)
{
 var hello = Properties.Resource.Action_greeting;
 var bye = Properties.Resource.Action_cancel;

 Console.WriteLine($"Action_greeting value: {hello}, Action_cancel value: {bye}");

 Console.Read();
}

运行它应该向我们展示如下内容：

Action_greeting value: Hello, Action_cancel value: Cancel

访问外部资源文件

这部分几乎相同，您可以通过 Properties 对象访问资源文件。

var hello = Properties.Resource.Action_greeting;
var bye = Properties.Resource.Action_cancel;

var johnhello = Properties.John.Resource.Action_greeting;
var johnbye = Properties.John.Resource.Action_cancel;

var doehello = Properties.Doe.Resource.Action_greeting;
var doebye = Properties.Doe.Resource.Action_cancel;

问题

使用此方法的主要问题是每个键都是对象内部的属性，因此我们必须像之前看到的那样调用它。如果要调用John资源文件的密钥Action_greeting，我们必须使用以下Properties.John，然后使用Resource.Action_greeting。

这就是问题所在。

那是因为，如果我们正在为很多客户开发应用程序，那么改变我们为每个客户调用资源文件的方式是一个坏主意。

您能想象吗？ 为每个客户端编译应用程序并将 John 更改为 Doe，然后更改为其他内容。 这太疯狂了！

解决方案

我们的团队领导想到了一个非常好的方法，就像后备系统一样，我们必须有一个资源的基本模型，然后对于每个客户端都有一个资源文件，它将用他们的资源更新文件，最后我们得到一个资源列表。

如果客户不需要自定义资源，我们将使用基础资源；如果客户需要，我们将使用他们的资源。

要将其放入清单中，我们必须这样做：

找到一种方法将所有键/值映射到嵌入资源的字典。
找到一种方法将所有键/值映射到外部资源的字典
混合两个文件并为每种语言提供一个字典
创建一个访问字典并返回值的方法

图表

让我们编码

首先，让我们创建一个单独的类，其中我们将拥有所有逻辑，从获取资源文件到混合它们并返回值。该类将被称为 CustomResources。

看起来是这样的：

 class CustomResources
 {

 private static Dictionary<string, string> _ResourcesEnglish;
 private static Dictionary<string, string> ResourcesEnglish;

 private static Dictionary<string, string> _ResourcesSpanish;
 private static Dictionary<string, string> ResourcesSpanish;


 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromFile(string file)
 {
 ...
 }

 public static string GetText(string key)
 {
 ...
 }

 public static string GetText(string key, string language)
 {
 ...
 }
 }

请注意，我们正在实现属性的延迟加载，这有助于提高性能并使其加载字典一次。

GetDictionaryFromEmbedded：从嵌入资源返回字典。
GetDictionaryFromFile：从外部资源返回字典。
OverwriteDictionary：混合两个字典并返回一个字典。
GetText：返回给定键的值

从嵌入资源到字典

我们必须从 xml 文件中获取所有属性并返回一个字典：

private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
{
 Dictionary<string, string> res = new Dictionary<string, string>();

 try
 {
 ResourceManager rm = new ResourceManager(embedded, Assembly.GetExecutingAssembly());
 var resourceSet = rm.GetResourceSet(new CultureInfo(cultureInfoCode), true, true);

 var resourceDictionary = resourceSet.Cast<DictionaryEntry>()
 .ToDictionary(r => r.Key.ToString(),
 r => r.Value.ToString());
 res = resourceDictionary;
 }
 catch (Exception e)
 {
 string a = e.Message;
 // Error getting resource file
 }

 return res;
}

两件事：- 请注意，它需要一个名为 embedded 的参数，该参数是您可以在设计器中看到的文件的名称，在我们的例子中是：resources-demo.Properties.Resource。

我们还有一个名为 cultreInfoCode 的参数，它是要选择的语言的代码。对我们来说幸运的是，.NET Framework 为我们完成了这项工作，我们不需要做任何事情，只需设置我们想要英语或西班牙语，它就会在 resource.es.resx 或 resource.resx 之间进行选择

从外部资源到字典

从文件获取有点困难，但并不难，我们必须获取可执行文件的当前位置，连接资源文件的位置，然后将其解析为字典。

但首先您必须添加对 System.Windows.Forms 的引用，才能访问 ResXResourceReader。

现在我们的 GetDictionaryFromFile 方法：

private static Dictionary<string, string> GetDictionaryFromFile(string file)
{
 Dictionary<string, string> res = new Dictionary<string, string>();
 string currentPath = (System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase) + file).Replace("file:\\", "");

 try
 {
 using (ResXResourceReader resxReader = new ResXResourceReader(currentPath))
 {
 foreach (DictionaryEntry entry in resxReader)
 {
 res.Add((string)entry.Key, (string)entry.Value);
 }
 }
 }
 catch (Exception e)
 {
 string a = e.Message;
 }

 return res;
}

文件参数需要填写从可执行文件到资源文件的位置，在我们的例子中是："\\Properties\\John\\Resource.resx"。

混合字典

我们已经完成了，首先，请记住将 System.Configuration 添加到引用中，以便您可以访问 app.settings。

 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
{
 var identifier = ConfigurationManager.AppSettings["CustomResources.Folder"];
 if (String.IsNullOrEmpty(identifier))
 return currentDictionary;

 foreach (var item in newDictionary)
 {
 try
 {
 currentDictionary[item.Key] = item.Value;
 }
 catch (Exception)
 {
 if(addIfDoesntExist)
 currentDictionary.Add(item.Key, item.Value);
 }
 }

 return currentDictionary;
}

从字典中获取文本

创建一个调用选择语言的私有方法的公共方法：

private static string GetText(string key, string language)
{
 try
 {
 switch (language)
 {
 case "es":
 return ResourceSpanish[key];
 case "en":
 default:
 return ResourceEnglish[key];
 }
 }
 catch (Exception)
 {
 return $"No value with key: {key} and language: {language}";
 }
}

public static string GetText(string key)
{
 try
 {
 return GetText(key, Thread.CurrentThread.CurrentCulture.TwoLetterISOLanguageName);
 }
 catch (Exception)
 {
 return $"No value with key: {key}";
 }
}

请注意，如果要添加更多语言，则必须修改开关。

添加代码到属性 getter

由于我们现在拥有所有方法，因此我们可以修改公共属性的 getter 来获取值。

private static Dictionary<string, string> _ResourcesEnglish;
private static Dictionary<string, string> ResourcesEnglish
{
 get
 {
 if (_ResourcesEnglish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resource");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resource.resx", "en");
 _ResourcesEnglish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesEnglish;
 }
}

private static Dictionary<string, string> _ResourcesSpanish;
private static Dictionary<string, string> ResourcesSpanish
{
 get
 {
 if (_ResourcesSpanish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resources");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resources.es.resx", "es");
 _ResourcesSpanish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesSpanish;
 }
}

首先我们从app.settings中获取标识符。
然后我们得到基础资源，即嵌入的资源。
之后我们获取自定义资源，为此我们需要文件夹名称（即标识符）。
然后我们将它们混合并返回值。

所有这些都将在延迟加载后完成一次。

测试

与代码相关的所有内容都已完成，现在让我们测试一下，为了从字典中获取值，我们必须调用返回值的方法 CustomResources.GetText(string key) 。

更新整个资源文件

此测试是我们想要更新资源文件的整个键/值的情况，正如您在图片中看到的，我们具有相同的键但不同的值。

我们将测试 John，为了进行设置，我们将 app.config 设置为 <add key="CustomResources.Folder" value="John" />。

现在让我们检查我们的基础资源文件（Properties/Resource.es.resx）：

然后是我们的外部资源文件（Properties/John/Resource.es.resx）：

一切设置完毕后，我们运行控制台应用程序，让我们停止到属性的 get 部分并检查所有内容

folderIdentifier 具有应用程序设置的值：

baseResources 具有基础资源、嵌入资源的值：

customResources 具有文件夹 John 内的外部资源的值：

最后，_ResourcesSpanish 具有从基础资源到外部资源的混合值。

只更新一个

现在让我们测试相同但不同的场景，只需更新一个密钥并让另一个相同。

如您所见，这些文件对于 Action_greeting 具有相同的值含义，但对于 Action_cancel 具有不同的值，因此它应该仅更新 Action_cancel。

缺少资源文件

如果您不提供外部资源文件，那根本不重要，因为我们期望有一个文件，如果失败，它将返回一个空字典，并且当混合两个字典时，它将最终得到基本字典。

嵌入资源中缺少对

如果外部资源文件中有一对，默认情况下不会将其添加到最终字典中，您可以通过在混合两个字典时调用方法 OverwriteDictionary() 来更改这一点，并将参数 addIfDoesntExist 设置为 true。

不同的语言

正如你所看到的，我们没有指定任何语言，因为所有这些都是由调用 GetText(string key, string language) 的函数 GetText(string key) 完成的，参数 language 由 TwoLetterISOLanguageName 填充，它返回线程的当前语言。

就我而言，我将西班牙语作为默认语言，这就是为什么它总是以西班牙语显示，但我们也可以尝试使用英语。

让我们编写一些代码并构建一些东西来检查西班牙语和英语。

static void Main(string[] args)
{

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("es-ES");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("es-ES");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 Console.Read();
}

private static void WriteText(string key) {
 Console.WriteLine($"[Culture: {System.Threading.Thread.CurrentThread.CurrentCulture}] Key: {key} -> value: {CustomResources.GetText(key)}");
}

运行这个，输出应该是这样的：

[Culture: en-US] Key: Action_greeting -> value: Hello
[Culture: en-US] Key: Action_cancel -> value: Finish
[Culture: es-ES] Key: Action_greeting -> value: Hola
[Culture: es-ES] Key: Action_cancel -> value: Terminar

前两个值来自 resources.resx，均为英语，最后两个值均来自西班牙语，并且这些值是从 resources.es.resx 检索的。

就是这样

在本教程中，我们找到了一种混合嵌入式和外部语言资源的方法，这是我们团队中遇到的问题的解决方案，从那时起它就一直运行没有任何问题。

您可以在[此处](https://github.com/emimontesdeoca/resources-demo查看源代码。

如果您有任何问题，请随时通过 @emimontesdeocaa 发推文给我，我会在有时间时回复您。

使用 Bot Framework 和 DirectLine 进行流程案例的集成测试

Wed, 25 Apr 2018 00:00:00 +0000

简介

在之前的博文中，我们针对单例做了一些集成测试。 “单一案例”是指在向机器人询问某件事后，他只会回复一次，然后我们比较结果的情况。

本指南不会解释身份验证和 API 调用是如何完成的，如果您想查看，请查看单例指南。

心流对话怎么样？

使用当前的方式，我们在对话中没有任何类型的流程，例如，如果您想寻求帮助，然后会显示一个包含不同选项的菜单，然后在选择其中一个选项后，会显示另一个菜单。这将产生 2 个或更多 responses。 所以这意味着使用我们之前使用的集成测试解决方案将不起作用。

下面是单个案例的集成测试如何工作的图表。

这是我们如何使当前的集成测试解决方案适应流程案例的图表。

以下解释不会涵盖Bot Framework如何工作的所有基本信息，如果您不明白，请去查看官方文档。

示例案例

在以下指南中，我将使用带有我创建的流程对话的机器人，该机器人会寻求帮助，然后选择不同的选项。

新的 JSON 结构

现在我们在与机器人对话时拥有多个 request，我们需要修改 json 结构以添加我们将要执行的所有 request。

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint":
 "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint":
 "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "PedirAyuda",
 "requests": [
 {
 "type": "message",
 "text": "Ayuda",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Telefono",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Oficina",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Tenerife",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 }
 ],
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "922920252",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

正如您所看到的，有一个重要的变化，request 现在是 requests。这意味着现在我们有一个 List<Activity> 而不是单个 activity。

新对象

之前我们为单个案例设置了对象：TestEntry 和 TestEntryCollection。对于流程案例，我们将创建新对象：TestEntryFlow 和 TestEntryFlowCollection。

`TestEntryFlow`

该对象适用于集合中的每个条目，请注意 Requests 对象现在是一个 List<Activity>，而不是我之前提到的单个 Activity。

由于我们将多次询问机器人，因此我们需要将多个 activities 发送到对话中。

public class TestEntryFlow
{
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("requests")]
 public List<Activity> Requests { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
}

`TestEntiresCollection`

该对象将包含 DirectLine 的相关信息，例如 secret 和端点，以及我们将测试的 Entries 列表。

请注意，Entries 现在是 TestEntryFlow 的列表，而不是 TestEntry。

public class TestEntryFlowCollection
{
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntryFlow> Entries { get; set; }
}

为流程案例创建 `TestMethod`

新流程

首先，再看一遍图（和我上面贴的一样）。

正如您所看到的，进行测试的流程结构几乎相同：

获取信息
认证
创建对话这里发生了变化，现在我们必须多次向对话发送所有请求。为了做到这一点，我们必须循环每个请求，将其发送到机器人，然后将最新响应与我们的预期响应进行比较。
发送所有请求
获取所有消息
获取最新回复
与预期响应进行比较
断言结果

代码

首先，我们需要从文件中获取信息，这与我们之前处理单例时的情况相同。

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

现在我们必须循环 data.entries 的每个 TestEntryFlow，这样我们就可以遵循在单个情况下执行的相同流程，直到新部分，我们在 requests 中循环。

/// Arrange with current requested values
string token, newToken, conversationId;
Activity latestResponse = new Activity();

/// Act for step

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

/// 2 - Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

接下来的步骤非常简单，我们必须循环 entry.requests 并将每个 activity 发送到对话。

foreach (Activity step in entry.Requests)
{
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
}

我们使用 watermark 来获取最新消息，watermark 是 DirectLine API 在请求对话信息时返回的值。

之后，我们只需用 latestReponse 和 expectedResponse 填充 globals 即可。

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

为了完成这个案例，我们评估 entry 中的 assert 字符串。

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

最终代码

[TestMethod]
public async Task ShouldTestFlowCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert
 foreach (TestEntryFlow entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;
 Activity latestResponse = new Activity();

 /// Act for step

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

 foreach (Activity step in entry.Requests)
 {
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
 }

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }

 await Task.CompletedTask;
}

改进

我确实相信更好的流程是可能的，但这种改进意味着 JSON 结构也应该改变。另外，为了实现这一点，json 必须更加填充。

为了更好地进行测试，我们应该为每个 request 提供一个 response，并且每次发送消息时都应该进行断言。我们现在这样做的方法是存储所有 requests 和 最终 response 。

我制作了一个图表来展示它的外观。

我强烈认为这种方式总体上对于测试的完整性要好得多，因为您正在测试流程中的几乎所有行为，而不仅仅是测试最终响应。

这就是本指南的全部内容，请记住，本指南是单个案例指南的延续，如果您感到迷茫，请查看该指南，该指南更长并且对所有内容都有更多解释。

请记住，所有代码都存储在我的 github 中的 this 存储库中。

祝你有美好的一天！

使用Bot Framework和DirectLine集成测试（1）

Tue, 24 Apr 2018 00:00:00 +0000

自从我在一家公司工作一段时间后，我就被分配从事Bot Framework的集成测试工作。

我在小组中的工作是使机器人尽可能稳定，但首先，什么是 Bot Framework？

构建、连接、部署和管理智能机器人，以便在网站、应用程序、Cortana、Microsoft Teams、Skype、Slack、Facebook Messenger 等上与用户自然交互。快速开始使用完整的机器人构建环境，同时只需为您使用的内容付费。

您可以在此处找到有关 Bot Framework 的更多信息。

以下解释不会涵盖Bot Framework如何工作的所有基本信息，如果您不明白，请去查看官方文档。

为什么需要集成测试？

需要集成测试，因为每当我的一位同事推送修复、新功能甚至新错误时，该测试都会在将代码推送到生产之前运行，如果任何测试失败，代码将不会进入生产，这意味着最终用户不会遇到错误。

机器人集成测试？

我确实相信在机器人中，集成测试非常重要。你不可能拥有一个机器人，其中的某些菜单不起作用，或者某些功能不返回任何内容。

公司正在为他们的客户使用机器人，因为他们不希望人们忙于解决他们的问题，如果机器人可以帮助用户，其他员工将能够利用他们的时间做更重要的事情。

解决方案概述。

为了完成这项工作，我在 Visual Studio 中使用了一个测试项目，该项目将使用 WebClient 作为 API Rest 和一个 Json 文件，我们将在其中存储我们的案例。

JSON 文件

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint": "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

如您所见，我们有：

直线秘密 -> 来自已发布机器人的秘密
Directline 令牌生成端点 -> 使用秘密获取令牌的端点
直接对话端点 -> 端点以便进行对话
条目 -> 测试用例
- 请求 -> 我们发送到对话的内容
- 响应 -> 我们期望得到什么
- 断言 -> 我们在比较什么

反序列化

我们已经拥有完美格式化的 json 文件，现在我们必须将其加载到解决方案中，因此我们将使用 JSON.NET 和一些类。首先，我们有条目集合，其中包含所有内容，然后我们为每个集合提供一个条目列表。

 /// <summary>
 /// Object to parse from the file
 /// </summary>
 public class TestEntriesCollection
 {
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntry> Entries { get; set; }
 }

这是具有测试用例的名称、请求、响应和断言的对象。


 public class TestEntry
 {
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("request")]
 public Activity Request { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
 }

测试用例中从json解析为对象

有了解析对象的类，这很容易，因为我们需要作为对象来读取。

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\data.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

现在有了这个集合，我们将能够循环它并使用例如 foreach 来获取信息。

 foreach (TestEntry entry in data.Entries)
 {
 ....
 }

这就是这部分的全部内容，下一部分将包括 DirectLine 的授权，请记住所有代码都存储在我的 github 中的 this 存储库中。

使用Bot Framework和DirectLine集成测试（2）

Tue, 24 Apr 2018 00:00:00 +0000

在这一部分中，我们将进行 DirectLine 授权并从机器人的响应中获取值。

现在我们已经完成了反序列化，是时候从集合和整体中获取信息了，我们将使用这些信息来获取授权、进行 api 调用并断言结果。

以下解释不会涵盖Bot Framework如何工作的所有基本信息，如果您不明白，请去查看官方文档。

使用 WebClient 进行 API 调用

为了方便我们调用api，我创建了一个utils类，用于保存我们将要使用几次的函数，该类包括用于POST的uploadString和用于GET的downloadString。

 public class Utils
 {
 /// <summary>
 /// Uploads to an URL and gets result
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <param name="serializedJson">Serialized JSON to send</param>
 /// <returns></returns>
 public static T uploadString<T>(string bearer, string url, string serializedJson)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Upload string
 serializedResult = client.UploadString(url, serializedJson);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }

 /// <summary>
 /// Downloads from URL
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <returns></returns>
 public static T downloadString<T>(string bearer, string url)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Download string
 serializedResult = client.DownloadString(url);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }
 }

DirectLine 授权

如果你阅读官方文档，你可以找到如何做到这一点，而且非常简单，使用我们的函数就更容易了。首先请记住，我们在 foreach 语句中，因为我们正在对每种情况进行身份验证，如果我们超时，这将意味着测试将失败。

/// Arrange with current requested values
string token, newToken, conversationId;
/// Act

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

现在我们有了令牌，它将用于对对话端点进行以下所有调用。

创建对话。

为了与机器人对话，我们首先需要创建一个对话，该对话将返回一个包含对话 ID 的新令牌。

/// 2 -Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

此外，我们确实存储了 newToken 和 conversationId，用户向机器人发送消息都需要两者。

将活动发送到对话

现在，使用 conversationId 和 conversationEndpoint，我们可以创建最终端点来发送 Activity，即 json 文件中的 request。

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

获取最新消息

在消息历史记录中，在我们发送活动后，机器人应该已经做出响应，因此我们必须获取所有带有水印的消息，然后使用该水印过滤最新的消息/活动。

/// 4 - Get all activities, we get a List<activity> and a watermark
var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

/// 5 - Get the latest activity which is the response we should be expecting
var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

这就是这部分的全部内容，下一部分将包括我们从 json 中的 assert 获取文本的部分，将其转换为代码，就像在 Javascript 中但在 C# 中使用 eval() 一样，然后使用 Assert.isTrue() 获得最终的测试结果。

请记住，所有代码都存储在我的 github 中的 this 存储库中。

使用Bot Framework和DirectLine集成测试（3）

Tue, 24 Apr 2018 00:00:00 +0000

这是指南的最新部分，在这部分中，我们将评估 json 中断言中的文本。

现在我们使用了 request 并作为 activity 发送给机器人，我们得到了 response，我们必须将 json 中的 assert（我们存储在 json 中的响应，这是预期响应）与我们从机器人获得的响应进行比较。

以下解释不会涵盖Bot Framework如何工作的所有基本信息，如果您不明白，请去查看官方文档。

将 Microsoft.CodeAnalysis 添加到解决方案中

首先，我们必须将 CodeAnalysis 作为 NuGet 包包含进来。

安装后，记得将软件包添加到.cs文件中。

using Microsoft.CodeAnalysis.CSharp.Scripting;

创建一个 `Globals` 对象

为了评估，我们必须将参数传递给评估器。该评估器需要一个配置文件。

 /// <summary>
/// Object to pass parameters to Roslyn compiler
/// </summary>
public class Globals
{
 /// <summary>
 /// ExpectedResponse
 /// </summary>
 public Activity Request;
 /// <summary>
 /// ReceivedResponse
 /// </summary>
 public Activity Response;
}

这部分非常重要，在该配置文件中，我们将包含要比较的对象，因此对于我们来说，我们需要向其传递 预期响应 和 收到的响应。

有了这些信息，它将使用 json 文件中的 assert 并评估其中的内容。

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

** EvaluateAsync<T> 评估并返回 T，在我们的例子中，我们传递 string 进行评估，并传递 globals，其中包含要评估的数据。**

我将尝试用一个示例来解释这一点，使用一个条目（具有名称、请求、响应和断言）。

{
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }

让我们从这个条目中得到重要的东西，首先是断言 "assert": "Request.Text == Response.Text"，这意味着它将比较 Request.Text 与 Response.Text，并以布尔值形式返回值。

但是当我们调用函数 await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals) 时，我们传递 2 个参数：

string 要评估的字符串 -> "Request.Text == Response.Text"
评估者的 globals 数据 -> 在这种情况下，我们必须给出 Request 和 Response，请求是我们的 预期响应，响应是 收到的响应。

当我们在求值器中填充数据时，现在我们可以使用字符串并求值，因此它将返回 true 或 false。

完成

我们完成了，在这里你可以看到完成的TestMethod

[TestMethod]
public async Task ShouldTestSingleCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\data.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert

 foreach (TestEntry entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;

 if (entry.Request.Type == ActivityTypes.Message)
 {
 /// Act

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }
 }
 await Task.CompletedTask;
}

图表

这是我们为达到这一点所遵循的所有流程的图表，希望如果您不理解某些内容，这可以让您明白。

这就是全部，这是针对单个情况完成的，其中情况是 1 对 1，用户发送 activity 并且机器人返回另一个单个 activity。

我希望你喜欢它，下一篇将是具有多个响应的测试流程案例。

请记住，所有代码都存储在我的 github 中的 this 存储库中。

关于

Mon, 01 Jan 0001 00:00:00 +0000

关于我

我是 Emiliano Montesdeoca，一名乌拉圭裔西班牙软件开发者，微软开发者技术 MVP，住在西班牙加那利群岛特内里费的自豪父亲。

我喜欢解决复杂的技术挑战，并使用微软技术构建可扩展的云解决方案。我的日常工具围绕着 .NET、Azure、基于 Semantic Kernel 的 AI 以及 .NET Aspire 等现代架构。

我的工作

作为 Intelequia Technologies 的云解决方案团队负责人，我主导云原生应用程序的设计和交付——将战略愿景与实际执行相结合。我在架构与代码的交汇处发挥所长，确保团队交付既优雅又具备生产就绪性的解决方案。

社区贡献

我是一名频繁的国际演讲者，曾在 2023、2024 和 2025 年被评为 Sessionize 最活跃演讲者。我通过在全球会议上的演讲以及博客，分享来自真实世界的实用见解。

我也是 The .NET Blog 的创始人——这是 .NET 社区的资源平台——我也定期在这个博客上写下我学到和构建的内容。

指导他人和建设社区是我的核心组成部分。回馈塑造了我职业生涯的生态系统，这是我认真对待的事情。

联系我

我始终欢迎在活动中演讲、合作项目，或讨论云架构和 AI。随时联系！

Email: emimontesdeoca@outlook.es
GitHub: @emimontesdeoca
X / Twitter: @emimontesdeocaa
LinkedIn: emimontesdeoca
Instagram: @emimontesdeoca
Sessionize: emimontesdeoca

演讲

Mon, 01 Jan 0001 00:00:00 +0000

我是一名经常在国际技术大会上演讲的讲师，专注于 .NET、Azure、AI 和云原生开发。我于 2023、2024 和 2025 年荣获 Sessionize 最活跃演讲者，并持有开发者技术领域的 Microsoft MVP 认证。

如果您希望我在您的活动上演讲，欢迎联系我！

2026

2026 年的 Blazor

回顾 2026 年 Blazor 的现状，以及它随 .NET 10 的发展历程。审查最新的变更与改进、其对实际应用开发的影响，以及哪种 Blazor 托管模型最适合每种场景。

用 AI 强化三级支持：Azure Functions + OpenAI 实战

Azure Functions、Azure Monitor 告警和 Azure OpenAI 如何协同工作以加速三级支持。从自动告警分类到智能日志分析——将 AI 融入真实支持工作流的实践解析。

从仪表板到代理：可观察性的下一步

一场将 AI 代理世界与生产可观测性连接起来的实践课。从 Semantic Kernel 到通过 MCP 与 Grafana 交互、查询 OpenTelemetry 数据并帮助运营和优化真实系统的自主代理。

即将到来：Global Azure 2026 — 2026 年 4 月，西班牙马德里

2025

用微软代理框架拯救圣诞节

使用 Microsoft Agent Framework 构建和协调多个 AI 代理以找到完美的圣诞礼物。每个代理各有专长——从礼物想法生成到价格比较——共同协作实现更聪明的节日购物。

用 AI 强化三级支持：Azure Functions + Semantic Kernel 实战

Azure Functions、Azure Monitor 和 Semantic Kernel 协同工作，使三级支持更快、更高效——从自动告警检测到智能日志分析。

.NET 10 中 Blazor 有哪些新变化？

探索 .NET 10 中 Blazor 的关键新特性，包括性能改进、表单、持久状态和更强大的 JavaScript 互操作性。

使用 C#、Semantic Kernel 和 Gemini 的混合 AI：构建更智能的企业应用

在 C# 中编排混合 AI 工作流——将本地模型 (Phi-3) 与通过 Vertex AI 的 Gemini Pro/Ultra 融合，使用 Semantic Kernel 插件构建认知代理，并设计自适应架构。

.NET Aspire：无痛构建云原生应用

实践课，构建天生可扩展、弹性和可观测的云优先微服务。探索 .NET Aspire 如何消除 70% 的云样板代码。

.NET Aspire：无混乱的云原生

设计天生可扩展的应用的真实案例——从第一次提交就内置可观测性和自动弹性。

2024

AI 与 SQL 相遇：用 .NET 和 Semantic Kernel 构建智能披萨店

理解您的代码和数据的自然语言 AI 交互——构建由 .NET 和 Semantic Kernel 驱动的智能披萨店。

.NET Aspire：无复杂性的云原生应用

无痛构建云优先微服务——一场实践性的演示驱动分享，展示 .NET Aspire 如何简化云原生开发。

Power Platform：从低代码到专业代码的旅程

在同一平台内使用 TypeScript 从低代码 Power Apps 过渡到高级专业代码组件。

智能自动化：用集成 AI 转型企业应用

将 .NET 应用推向新高度——使用 Semantic Kernel 和 .NET Aspire 将传统逻辑与基于 AI 的推理结合。

从低代码到专业代码：企业解决方案中的 AI 开发方法

探索企业解决方案的不同方法——从含 AI 的 Power Platform 到使用 Semantic Kernel 的传统开发。

用 Azure 管理差旅费用

使用 Azure AI Vision、Document Intelligence 和带 Semantic Kernel 的 OpenAI 自动化差旅费用管理。

徽章与荣誉

🏆 Sessionize 最活跃演讲者 2025
🏆 Sessionize 最活跃演讲者 2024
🏆 Sessionize 最活跃演讲者 2023
🏅 开发者技术领域 Microsoft MVP

在 Sessionize 查看所有演讲 →

Emiliano Montesdeoca

Blazor 从零开始：第 3 章 —— 可扩展的组件设计

Blazor 组件到底是什么

第一步：从职责单一的组件开始

第二步：用参数显式表达行为

第三步：用 RenderFragment 做布局组合

第四步：优先组合，而不是巨型页面

第五步：保持标记与逻辑的平衡

第六步：实用的目录结构

Blazor 初期常见问题

下一章

从零开始 Blazor：第 2 章 — 你的第一个 Blazor 应用

第 1 步：创建项目

第 2 步：本地运行

第 3 步：理解项目结构

第 4 步：做第一次修改

第 5 步：读一遍 Program.cs

常见问题

下一章

Blazor 从零开始：第1章 — 什么是 Blazor？

简短的历史

Blazor 究竟是什么

渲染模型

静态 SSR

交互式服务器

交互式 WebAssembly

Auto 模式

在同一应用中混合模式

Blazor 与 JavaScript 框架的比较

跟进所需的内容

下一篇

Blazor 从零开始：全新系列

这个系列适合谁

我们将涵盖的内容

为什么要做系列，为什么是现在

如何跟进系列

C# 联合类型：受歧视联合终于来了

什么是受歧视工会？

今天我们如何模拟工会

具有继承性的抽象记录

手动枚举+数据模式

C# 提案：union 关键字

仅限超值会员

通用联合

方法联合

嵌套模式匹配

保护条款

实际例子

结果模式：替换预期错误的异常

领域建模：支付类型

状态机

序列化和互操作注意事项联合类型立即出现的实际问题之一是：如何序列化它们？如果您正在构建 API 或存储数据，则需要 JSON 序列化才能正常工作。

如何尝试

与现有方法的比较

这对 .NET 生态系统意味着什么

结论

使用语义内核在 C# 中构建 RAG 系统

简介

RAG 的工作原理

先决条件

设置内核

定义数据模型

分块文档

摄取文档

搜索相关块

根据上下文生成答案

使用它

转向生产

使用 Microsoft Agent Framework 构建代理工作流程

简介

什么是代理工作流程？

先决条件

构建顺序工作流程

定义代理

顺序执行

并行执行

条件分支

添加插件到工作流代理

工作流程中的错误处理

最佳实践

第三步：用 `RenderFragment` 做布局组合

C# 提案：`union` 关键字