寒流の编程笔记

你好，世界！

Sun, 18 Feb 2024 00:00:00 +0000

欢迎来到我的博客！

Info

《CommunityToolkit.Mvvm 社区工具包从入门到精通》系列教程已经基本完工！你可以点击这里查看，并在评论区留下你的宝贵意见。

虽然博客的绝大多数所需功能都已经实现，但仍有一些细节需要微调，比如：

右侧目录宽度太大
博客正文的标题下方不需要显示摘要内容
添加用户访问统计
阅读时长的计算并不十分准确
去掉文章小标题前面的“#”号
添加 RSS 订阅功能
添加一个「关于我」页面
添加评论区

更多关于我的信息，请查看关于我页面。

本博客使用 Hugo 搭建，主题是 Stack。

封面图片使用 Fooocus 绘制。

如何减少 PNG 文件大小

Tue, 01 Sep 2026 00:00:00 +0000

今天在推特上看到了一个有意思的帖子：

大致是说，他在尝试发布 ChatGPT Plugin 时，发现需要提交一个指定要求的图标文件：

PNG 格式
分辨率最好不小于 256x256
文件大小不超过 10 KB

这看似平平无奇的要求，其实可能还真没有那么简单，尤其是对于不熟悉图像处理的用户来说。不信的话，我这里有一张之前用 AI 生成的图标：

我将它用 ImageMagick 以默认的参数转为 PNG 格式，256x256 的尺寸后，发现它的大小是 64.6 KB，距离要求的 10 KB 还差得远。

虽然官方没有要求必须不小于 256x256，但如果我们确实想达到这个分辨率，这该怎么办呢？

尝试使用不复杂的图片

上面那张图片之所以体积比较大，是因为它的内容比较复杂，包含了很多颜色和细节。对于 PNG 文件来说，复杂的图像通常会导致文件大小增加。所以，如果我们反其道而行之，尝试使用一些不复杂的图片，可能会更容易满足文件大小的要求。

这里我从网上随便找了一个 GitHub 给用户默认生成的头像，即 Identicon，它的内容相对简单，颜色也不多：

此时图片的大小瞬间来到了只有 2 KB 不到。

这确实满足了要求，但是难道说我们就只能用这么简单的图片作为图标了吗？

尝试压缩 PNG 图片

我们当然不甘心只能用这么简单的图片了。所以回到刚开始的图标，我们来想想办法如何降低它的体积。首先我们来试试用 ImageMagick 将它以最高的压缩质量进行编码，即：

1

magick input.png -quality 100 output.png

但很遗憾，它的体积也只是从刚刚的 64.6 KB 降低到了 62.6 KB。看来这条路行不通。

Tip

这里我们还可以添加 -strip 参数来去掉图片的元数据，从而进一步降低体积。但通常只会降低大约零点几 KB，基本可以忽略不计。

那我们再尝试一个笨方法：先将它适当缩小，再放大，也就是人为制造了马赛克，降低了图片质量。为了更有马赛克的感觉，我们采用最近邻插值法（-filter point），命令如下：

1

magick input.png -resize 64x64 -filter point -resize 256x256 output.png

这次文件体积是 8.64 KB，终于满足了要求。但我们仍不满足，因为这太模糊了。

量化 PNG 图片到 256 色

如果我们想要在保持图片清晰度的同时降低文件体积，那么量化图片到 256 色可能是一个不错的选择。PNG 格式支持调色板模式（Indexed Color），这意味着我们可以将图片的颜色数量限制在 256 种，从而显著减少文件大小。

我们仍然可以借助 ImageMagick 来实现这一点，命令如下：

1

magick input.png -colors 256 output.png

这里将原图、256 色、192 色并排放在了一起：

是不是乍一看起来差别不大？但实际上，放大之后不难发现，256 色的图像在细节上已经有所损失，而 192 色的图像则更为明显。而且遗憾的是，降低到 192 色之后，文件大小依然有 15.1 KB，虽然我们好像已经离成功不远了。

但遗憾的是，继续降低颜色数量到 128 色甚至 64 色之后，文件大小仍然有 11.7 KB。后续降低颜色数量的收效甚微，但图片质量已经越来越惨不忍睹了。

用 pngquant + oxipng

pngquant 跟上面我们用的 ImageMagick 做的事情类似，都是做颜色上的量化，但是它还能通过智能量化、抖动（dithering）等方式减少肉眼可见的损失，所以通常会得到更好的结果。

但是光使用它还不够，因为它只负责颜色量化。我们还可以搭配 oxipng 这个无损 PNG 优化器来进一步压缩。

为了达到 10 KB 以内的大小，我也是尝试了多次，最后得到了这样的方案：

1
2
3
4


# 先用 pngquant 将颜色量化到 24 色，并设置质量为 30
pngquant 24 --quality=30 tmp.png
# 再用 oxipng 进行无损压缩
oxipng -o 4 --strip safe output.png

终于，我们达到了 9.47 KB 的大小，也算是完成了任务。这里贴一张结果图：

但这个结果也是经不起细看的。所以，ChatGPT 对于图标的要求，可真是没那么容易满足啊。

总结

经过这一番折腾，我们不难得出结论：在尺寸与格式固定时，将复杂图像极限压缩至 10 KB 内，必须依赖强力颜色量化搭配专业无损二次压缩，且不可避免需要在细节与画质上做出一定妥协。

在 WPF 等桌面应用中应该单纯使用 DI 还是引入 Generic Host？

Mon, 24 Aug 2026 00:00:00 +0000

在现代 .NET 开发中，依赖注入（Dependency Injection，简称 DI）因为其在解耦、可测试性和生命周期管理上的优势，已经成为了几乎所有项目的标配。无论是 ASP.NET Core、Blazor 还是桌面端的 WPF、Avalonia、WinUI 等，微软官方都提供了统一的依赖注入体系。

很多做客户端开发（WPF、Avalonia、WinUI 等）的开发者，在早期的项目中大多接触过各种第三方 IoC/DI 容器，例如 Autofac、旧时 Prism 标配的 Unity、Simple Injector 等。这些第三方库的角色往往非常纯粹，就是一个单纯的 DI 容器：在应用启动时构建一个容器（比如 ContainerBuilder），把服务、ViewModel 和 Window 注册进去，最后解析主窗口并显示。微软官方的 Microsoft.Extensions.DependencyInjection 也是如此。

然而，当大家查阅现代的官方文档、开源项目或者技术博客时，却会发现有大量的项目直接引入了 Generic Host（通用主机，IHost / HostApplicationBuilder）。这难免会让不少客户端开发者产生困惑：在桌面端使用微软官方的依赖注入体系时，我们究竟应该只使用单纯的 DI 容器，还是把 Generic Host 整体引入进来？

这两种做法在实际开发中都非常普遍。事实上，微软官方的 DI 容器本身就是 Generic Host 的核心功能之一，而 Host 则在此基础上额外打包了配置、日志、Options 模式和后台托管服务等一整套基础设施。

本文将对比这两种方案的具体用法与能力差异，聊聊它们各自的优缺点，以及我们在实际项目中该如何权衡取舍。

单纯使用 DI（ServiceCollection）

如果我们的桌面应用主要是为了解耦业务服务（Services）与视图模型（ViewModels）、方便进行单元测试以及管理对象的生命周期（单例、瞬态等），并不需要一套复杂的跨环境配置系统或后台服务，那么直接使用纯粹的 DI 容器就是最直接、最轻量的选择。

我们只需要安装一个包：

1

dotnet add package Microsoft.Extensions.DependencyInjection

这个包非常干净，只包含 IServiceCollection、IServiceProvider 以及官方的默认 IoC 容器实现，几乎没有多余的传递依赖。

Note

如果想要在一个类库项目中使用 DI，那么只需要引用 Microsoft.Extensions.DependencyInjection.Abstractions 包即可，它只包含接口定义，不包含任何默认实现。然后就可以借助扩展方法来实现形如 AddXXX(this IServiceCollection services) 的注册方法，供入口项目调用。

在 WPF 中集成单纯 DI

在 WPF 中使用 DI 的经典做法是改造 App.xaml 和 App.xaml.cs。

首先，打开 App.xaml，移除默认的 StartupUri 属性，并在后台实现构造函数、重写 OnStartup 等方法来注册和配置服务、解析主窗口等：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


using System.Windows;
using Microsoft.Extensions.DependencyInjection;

namespace WpfDiApp;

public partial class App : Application
{
 // 提供全局静态访问点（可选，便于在某些特殊场景下获取服务）
 public new static App Current => (App)Application.Current;

 public IServiceProvider Services { get; }

 public App()
 {
 Services = ConfigureServices();
 }

 private static IServiceProvider ConfigureServices()
 {
 var services = new ServiceCollection();

 // 注册业务服务
 services.AddSingleton<IGreetingService, GreetingService>();

 // 注册 ViewModels
 services.AddTransient<MainWindowViewModel>();

 // 注册 Views/Windows
 services.AddTransient<MainWindow>();

 return services.BuildServiceProvider();
 }

 protected override void OnStartup(StartupEventArgs e)
 {
 base.OnStartup(e);

 // 从容器中获取主窗口并显示
 var mainWindow = Services.GetRequiredService<MainWindow>();
 mainWindow.Show();
 }

 protected override void OnExit(ExitEventArgs e)
 {
 // 应用程序退出时妥善释放容器中所有 IDisposable 的单例资源
 if (Services is IDisposable disposable)
 {
 disposable.Dispose();
 }

 base.OnExit(e);
 }
}

在视图和 ViewModel 中，我们就可以通过标准的构造函数注入来使用所需的服务了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public class MainWindowViewModel(IGreetingService greetingService)
{
 public string Message => greetingService.GetGreeting();
}

public partial class MainWindow : Window
{
 public MainWindow(MainWindowViewModel viewModel)
 {
 InitializeComponent();
 DataContext = viewModel;
 }
}

方案特点

极简且纯粹：没有任何多余的抽象层，只专注于依赖的注册与解析。
贴合桌面生命周期：桌面应用的生命周期本质上是由 UI 线程消息循环（Dispatcher）以及 Application.Current 控制的。单纯 DI 只作为一个普通服务容器挂在 App 下，完全不干扰 WPF 原有的运行逻辑。

引入 Generic Host

在 Generic Host 中，前面的 DI 并没有被替代，而是成为了 Host 的一部分。当我们使用 Host 时，注册和配置服务依然是通过 builder.Services（它本身就是一个 IServiceCollection）完成的，而构建出来的 IHost.Services 本质上也就是一个标准的 IServiceProvider。

如果想要在 WPF 中引入 Host，我们只需要安装一个包：

1

dotnet add package Microsoft.Extensions.Hosting

在现代 .NET 中，推荐使用 HostApplicationBuilder（通过 Host.CreateApplicationBuilder()）来搭建主机，它的语法与 ASP.NET Core 中的 WebApplicationBuilder 保持了一致。

同样在 App.xaml 中移除 StartupUri，并在 App.xaml.cs 中接入 Host：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


using System.Windows;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace WpfHostApp;

public partial class App : Application
{
 private readonly IHost _host;

 public App()
 {
 // 创建应用构建器（会自动载入命令行参数、环境变量及 appsettings 等）
 var builder = Host.CreateApplicationBuilder();

 // 1. 注册业务服务与后台服务
 builder.Services.AddSingleton<IGreetingService, GreetingService>();
 builder.Services.AddHostedService<HeartbeatBackgroundService>();

 // 2. 注册 Views 与 ViewModels
 builder.Services.AddTransient<MainWindowViewModel>();
 builder.Services.AddTransient<MainWindow>();

 _host = builder.Build();
 }

 protected override async void OnStartup(StartupEventArgs e)
 {
 base.OnStartup(e);

 // 启动 Host（会依次触发所有 IHostedService 的 StartAsync）
 await _host.StartAsync();

 // 解析并显示主窗口
 var mainWindow = _host.Services.GetRequiredService<MainWindow>();
 mainWindow.Show();
 }

 protected override async void OnExit(ExitEventArgs e)
 {
 // 优雅停止 Host（触发所有 IHostedService 的 StopAsync 并给它们一定的停止宽限期）
 using (_host)
 {
 await _host.StopAsync();
 }

 base.OnExit(e);
 }
}

除了上面看到的 DI 容器之外，Generic Host 还额外提供了许多开箱即用的功能。

多源配置系统

Host.CreateApplicationBuilder() 默认会自动加载并按顺序合并多个配置源：

appsettings.json
appsettings.{Environment}.json（例如 appsettings.Development.json）
环境变量
命令行参数（如果有传入）
本地开发阶段的用户机密（User Secrets）

在任何注入了 IConfiguration 的服务中，都可以直接读取合并后的配置项：

1
2
3
4
5


public class GreetingService(IConfiguration configuration) : IGreetingService
{
 public string GetGreeting() =>
 configuration["GreetingMessage"] ?? "Hello from Generic Host!";
}

配合 builder.Services.Configure<AppOptions>(builder.Configuration.GetSection("App"))，还可以将配置绑定到强类型的 Options 类上，并在服务中注入 IOptions<AppOptions> 或 IOptionsMonitor<AppOptions>（支持配置文件修改时热重载）。

结构化日志与第三方日志集成

Host 默认配置了 ILoggerFactory，且日志级别、过滤规则天然与 appsettings.json 中的 Logging 配置节绑定。在任何服务或 ViewModel 中，直接声明 ILogger<T> 即可记录日志：

1
2
3
4
5
6
7
8
9


public class MainWindowViewModel(
 IGreetingService greetingService,
 ILogger<MainWindowViewModel> logger)
{
 public void DoSomething()
 {
 logger.LogInformation("用户点击了操作按钮");
 }
}

使用 Host 的一大好处是日志抽象层的标准化。所有业务代码统一面向 Microsoft.Extensions.Logging 的 ILogger<T> 接口编写。如果后续想要替换为第三方日志框架，比如 Serilog，只需要引入 serilog/serilog-aspnetcore，然后在构建 Host 时替换底层的日志提供程序即可：

1
2
3


var builder = Host.CreateApplicationBuilder();

builder.Services.AddSerilog(); // 添加这一行即可替换内置的 Logger

后台托管服务（Hosted Services）

这也是 Host 独有的特性之一。通过继承 BackgroundService 或实现 IHostedService，我们可以定义伴随应用程序生命周期运行的后台任务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class HeartbeatBackgroundService(ILogger<HeartbeatBackgroundService> logger) : BackgroundService
{
 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
 while (!stoppingToken.IsCancellationRequested)
 {
 logger.LogInformation("后台心跳检测正常运行中...");
 await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
 }
 }
}

// 在 App.xaml.cs 中注册
builder.Services.AddHostedService<HeartbeatBackgroundService>();

当 _host.StartAsync() 被调用时，所有注册的 BackgroundService 会自动在后台线程中启动；当程序退出调用 _host.StopAsync() 时，Host 会触发取消通知并等待它们优雅退出。这对于需要常驻监听网络端口、定时同步数据或轮询任务的桌面端场景非常实用。

权衡与取舍

既然 Host 提供了这么多便利，是不是所有桌面项目都应该直接使用 Host？其实也不尽然。在实际选型时，有几个维度的权衡值得关注：

依赖包体积与依赖树深度

单纯 DI：只有一个 Microsoft.Extensions.DependencyInjection 包及其抽象层，依赖极其清晰干净。
Generic Host：Microsoft.Extensions.Hosting 相当于一个基础包，会自动拉入 Configuration、Logging、Options、FileProviders 等一整套依赖，不管你用不用。

虽然在常见的桌面开发中这些程序集并不会带来明显的体积压力，但如果在做 Native AOT 编译、或者对发布产物体积和裁剪比较敏感，过多的间接依赖会增加构建分析和裁剪配置的成本。也因此，微软还专门为 ASP.NET 提供了 WebApplication.CreateSlimBuilder 来减少不必要的依赖。

生命周期模型的差异

桌面应用的生命周期以 UI 线程和窗口 为核心，由 Dispatcher 消息循环驱动，通常绑定在主窗口关闭（ShutdownMode）或托盘图标交互上。
Generic Host 最初是为 服务端或控制台守护进程 设计的，生命周期围绕 StartAsync、StopAsync 以及控制台退出信号展开。

在 WPF 中使用 Host，本质上是用代码把这两套生命周期桥接在一起（在 OnStartup 触发 StartAsync，在 OnExit 触发 StopAsync）。如果应用中并没有任何 IHostedService 需要管理，那么这套异步启动和停止流程就显得有些多余。

按需组装的折中方案

很多开发者之所以引入 Host，只是因为“想用 appsettings.json”或者“想用 ILogger”。

但实际上，微软的这些扩展库大多是高度模块化的。如果只需要其中某一项功能，完全可以在单纯 DI 的基础上单独按需引入：

只需读取 appsettings.json：单独安装 Microsoft.Extensions.Configuration.Json，通过 new ConfigurationBuilder().AddJsonFile(...).Build() 构建配置，并以单例形式注册进 ServiceCollection；
只需使用 ILogger：单独安装 Microsoft.Extensions.Logging，通过 services.AddLogging() 直接向 ServiceCollection 注册日志服务。

我们可以按需组合自己需要的组件，而不必为了使用一两项功能而引入完整的 Host。

总结

对于桌面应用的开发来说：

单纯使用 DI（ServiceCollection）：适合轻量工具、单页面或架构相对简单的客户端。没有复杂的多环境配置和常驻后台任务，追求干净的依赖和最简单的启动流程。
引入 Generic Host：适合中大型桌面应用，或者需要多源配置、Options 模式、结构化日志管理以及后台常驻任务（IHostedService）的场景。

两者并没有绝对的优劣之分，搞清楚它们的包含关系与优缺点，根据实际需求选择最合适的方案即可。

System.Text.Json 相较于老牌 Newtonsoft.Json 目前仍缺失的功能及补救方法

Thu, 06 Aug 2026 00:00:00 +0000

在之前的文章中，我们梳理了截止到目前的 .NET 10，内置的 JSON 库都有哪些常用的功能。一般情况下，使用内置的 System.Text.Json 库已经足够满足大部分的 JSON 处理需求了，但在一些特定的场景下，仍然会遇到一些功能缺失的问题。本文将对比老牌的 Newtonsoft.Json 库，列出一部分缺失的功能，并提供一些补救方法。

JSONPath

JSONPath 是一种用路径表达式从 JSON 文档中定位节点的查询语法。它可以处理对象属性、数组下标、通配符、递归查找和条件筛选等场景；例如 $.store.books[?(@.price < 10)].title 表示找出价格低于 10 的书名。

Newtonsoft.Json 的 LINQ to JSON API 内置了 JSONPath 支持。将 JSON 解析为 JToken 后，使用 SelectToken 获取单个节点，或使用 SelectTokens 获取多个匹配节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


using Newtonsoft.Json.Linq;

var root = JToken.Parse("""
{
 "store": {
 "books": [
 { "title": "C# in Depth", "price": 45 },
 { "title": "JSON 入门", "price": 9 }
 ]
 }
}
""");

// 按路径获取一个节点。
var firstTitle = root.SelectToken("$.store.books[0].title")?.Value<string>();

// 使用通配符和筛选条件获取多个节点。
var cheapTitles = root
 .SelectTokens("$.store.books[?(@.price < 10)].title")
 .Select(token => token.Value<string>());

相对地，System.Text.Json 截至 .NET 10 仍没有提供 JSONPath 查询 API（在 GitHub 上有一个目前仍然 open 的 issue）现阶段，我们恐怕只能用 JsonNode 的索引器逐层访问，从而一定程度上绕开这个限制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


using System.Text.Json.Nodes;

var root = JsonNode.Parse("""
{
 "store": {
 "books": [
 { "title": "C# in Depth", "price": 45 },
 { "title": "JSON 入门", "price": 9 }
 ]
 }
}
""");

var firstTitle = root?["store"]?["books"]?[0]?["title"]?.GetValue<string>();

var cheapTitles = root?["store"]?["books"]?
 .AsArray()
 .Where(book => book?["price"]?.GetValue<decimal>() < 10)
 .Select(book => book?["title"]?.GetValue<string>());

但这种方式终究只是个临时方案，适合访问固定层级或自行编写少量遍历逻辑，但它不是 JSONPath 的替代品。如果业务逻辑依赖大量的 JSONPath，那么建议还是继续使用 Newtonsoft.Json。

使用 JsonPath.NET

如果希望继续使用 System.Text.Json 的 JsonNode 模型，同时又需要标准 JSONPath 查询，还可以使用 JsonPath.Net。它是 json-everything 项目的一部分，基于 System.Text.Json 实现，并遵循 RFC 9535 定义的 JSONPath 语法，支持属性访问、数组下标与切片、通配符、递归下降（如 $..title）和筛选器等。

先安装 NuGet 包：

1

dotnet add package JsonPath.Net

随后将 JSON 解析为 JsonNode，调用 JsonPath.Parse 解析查询表达式，再通过 Evaluate 执行查询。返回结果的 Matches 中同时包含匹配节点的值和它在原文档中的位置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


using System.Text.Json.Nodes;
using Json.Path;

var root = JsonNode.Parse("""
{
 "store": {
 "books": [
 { "title": "C# in Depth", "price": 45 },
 { "title": "JSON 入门", "price": 9 }
 ]
 }
}
""");

var path = JsonPath.Parse("$.store.books[?(@.price < 10)].title");
var result = path.Evaluate(root);

var cheapTitles = result.Matches
 .Select(match => match.Value?.GetValue<string>());
// "JSON 入门"

对于由用户输入的查询表达式，可以改用 TryParse，避免格式错误直接抛出异常：

1
2
3
4
5


if (JsonPath.TryParse(query, out var path))
{
 var result = path.Evaluate(root);
 // 使用 result.Matches 处理所有匹配项。
}

PopulateObject 填充既有对象

反序列化的一般流程是“从 JSON 创建一个全新的对象实例”。但有些场景下，我们希望把 JSON 的内容填充到一个已经存在的对象上：JSON 中出现的属性被覆盖，未出现的属性保持原值。典型场景包括用 JSON 片段更新配置对象、实现部分更新（partial update）、或者把反序列化结果合并到已有状态（例如 ViewModel）中。

Newtonsoft.Json 通过 JsonConvert.PopulateObject 直接支持这一需求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


using Newtonsoft.Json;

var config = new AppConfig
{
 Host = "localhost",
 Port = 8080,
 TimeoutSeconds = 30
};

// 只覆盖 JSON 中出现的属性，其余保持原值。
JsonConvert.PopulateObject("""{ "Port": 9090 }""", config);

Console.WriteLine($"{config.Host}:{config.Port}, Timeout={config.TimeoutSeconds}");
// localhost:9090, Timeout=30

public class AppConfig
{
 public string? Host { get; set; }
 public int Port { get; set; }
 public int TimeoutSeconds { get; set; }
}

而 System.Text.Json 截至 .NET 10 仍没有能把 JSON 原地填充到调用方传入的既有对象中的对应 API。.NET 8 起的 JsonObjectCreationHandling.Populate 是另一回事：它只能在反序列化新对象时，复用其已经初始化的属性或集合，不能替代这里的 PopulateObject。补救方法只能是退而求其次：先把 JSON 反序列化成新实例，再手动把需要的属性拷贝到既有对象上；或者解析为 JsonNode / JsonDocument 后自行遍历，只更新 JSON 中出现的属性。本质上，都是要自己动手造 Newtonsoft 已有的轮子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


using System.Text.Json;
using System.Text.Json.Nodes;

var config = new AppConfig
{
 Host = "localhost",
 Port = 8080,
 TimeoutSeconds = 30
};

var patch = JsonNode.Parse("""{ "Port": 9090 }""")!.AsObject();
foreach (var (name, value) in patch)
{
 if (name == nameof(AppConfig.Port))
 {
 config.Port = value!.GetValue<int>();
 }
}

对于属性较多或有嵌套结构的对象，这种手写遍历很快就会变得难以维护。如果项目里确实有大量这样的的需求，继续保留 Newtonsoft.Json 处理这部分逻辑，会比围绕 System.Text.Json 打补丁要省心得多。

DataTable 与 DataSet

DataTable 和 DataSet 是 ADO.NET 中用于承载表格数据及其关系的类型。Newtonsoft.Json 内置了对它们的转换器：DataTable 会被表示为对象数组，而 DataSet 会以表名为属性名、各表的行数组为属性值。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


using System.Data;
using Newtonsoft.Json;

var table = new DataTable("Users");
table.Columns.Add("Id", typeof(int));
table.Columns.Add("Name", typeof(string));
table.Rows.Add(1, "张三");
table.Rows.Add(2, "李四");

var tableJson = JsonConvert.SerializeObject(table, Formatting.Indented);
// [
// { "Id": 1, "Name": "张三" },
// { "Id": 2, "Name": "李四" }
// ]

var dataSet = new DataSet();
dataSet.Tables.Add(table);
var dataSetJson = JsonConvert.SerializeObject(dataSet, Formatting.Indented);
// {
// "Users": [
// { "Id": 1, "Name": "张三" },
// { "Id": 2, "Name": "李四" }
// ]
// }

DataTable? restoredTable = JsonConvert.DeserializeObject<DataTable>(tableJson);
DataSet? restoredDataSet = JsonConvert.DeserializeObject<DataSet>(dataSetJson);

System.Text.Json 截至 .NET 10 则没有为 System.Data 命名空间中的 DataTable、DataSet 及相关类型提供内置转换器，不能直接完成上述序列化或反序列化。官方建议通过自定义 JsonConverter<T> 支持这些类型；但这不只是补上几行代码：需要明确 JSON 格式、列的数据类型、DBNull 的表示方式，以及反序列化时是否允许自动推断列结构。

如果项目只是要向前端或 API 输出查询结果，更建议在数据访问层将行投影为 DTO、匿名对象或字典等，再交给 System.Text.Json 序列化。反之，如果需要和既有的 DataTable / DataSet JSON 格式双向兼容，那最好还是继续使用 Newtonsoft.Json 而不是折磨自己。

TypeNameHandling 与多态序列化

在序列化多态类型（基类引用指向派生类实例）时，仅靠属性本身往往无法还原出具体的派生类型，因此常见的操作时在 JSON 中额外写入类型信息作为“鉴别器”（discriminator），通常是一个额外的 $type 字段。

Newtonsoft.Json 通过 TypeNameHandling 枚举自动处理这一需求。默认值是 None；将其设置为 Auto 后，对于嵌套属性或集合元素，只要声明类型与实际运行时类型不一致，就会在 JSON 中写入 $type 字段；反序列化时则会根据 $type 自动还原为对应的派生类型，无需任何手工干预：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


using Newtonsoft.Json;

public abstract class Animal
{
 public string? Name { get; set; }
}

public class Dog : Animal
{
 public string? Breed { get; set; }
}

public class Cat : Animal
{
 public bool IsIndoor { get; set; }
}

List<Animal> animals =
[
 new Dog { Name = "Woffy", Breed = "Golden Retriever" },
 new Cat { Name = "Milo", IsIndoor = true }
];

var settings = new JsonSerializerSettings
{
 TypeNameHandling = TypeNameHandling.Auto
};

var json = JsonConvert.SerializeObject(animals, Formatting.Indented, settings);
// [
// {
// "$type": "Demo.Dog, Demo",
// "Breed": "Golden Retriever",
// "Name": "Woffy"
// },
// {
// "$type": "Demo.Cat, Demo",
// "IsIndoor": true,
// "Name": "Milo"
// }
// ]

// 反序列化时自动根据 $type 还原为 Dog 和 Cat。
var restored = JsonConvert.DeserializeObject<List<Animal>>(json, settings);

可以看到，默认写入的 $type 是 CLR 类型全名加简单程序集名，即 命名空间.类型名, 程序集名 的形式。如果配置为使用完整程序集信息，还会带上版本、区域性和公钥令牌等内容。整个过程完全由 Newtonsoft.Json 自动完成，业务代码只需配置一个开关，不需要在类型上做任何标注，派生类型之间也无需提前声明继承关系。

System.Text.Json 则默认不提供任何自动的类型信息写入。如果我们直接序列化上面的 List<Animal>，得到的 JSON 只会包含基类 Animal 声明的属性（也就是只剩 Name），派生类特有的 Breed、IsIndoor 会被静默丢弃，反序列化时也因为无法实例化抽象类而直接抛异常。

从 .NET 7 开始，System.Text.Json 提供了基于鉴别器字段的多态序列化支持，但需要我们在基类上通过特性显式声明所有允许的派生类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


using System.Text.Json;
using System.Text.Json.Serialization;

[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")] // 默认如此，可以省略
[JsonDerivedType(typeof(Dog), typeDiscriminator: "dog")]
[JsonDerivedType(typeof(Cat), typeDiscriminator: "cat")]
public abstract class Animal
{
 public string? Name { get; set; }
}

public class Dog : Animal
{
 public string? Breed { get; set; }
}

public class Cat : Animal
{
 public bool IsIndoor { get; set; }
}

List<Animal> animals =
[
 new Dog { Name = "Woffy", Breed = "Golden Retriever" },
 new Cat { Name = "咪咪", IsIndoor = true }
];

var json = JsonSerializer.Serialize(animals,
 new JsonSerializerOptions { WriteIndented = true });
// [
// {
// "$type": "dog",
// "Breed": "Golden Retriever",
// "Name": "Woffy"
// },
// {
// "$type": "cat",
// "IsIndoor": true,
// "Name": "咪咪"
// }
// ]

var restored = JsonSerializer.Deserialize<List<Animal>>(json);

不难看出，这种方案的局限性相当明显：

派生类型必须提前注册。需要通过 JsonDerivedType 特性或代码配置，列出所有允许参与多态序列化的派生类型，本质上是一个“白名单”。如果之后新增了派生类型却忘了注册，序列化时会直接抛异常。
基类需要感知全部派生类型。这与 Newtonsoft.Json 的“基类无感知、运行时自动识别”形成了鲜明对比，在派生类型分散于多个程序集、或由插件动态扩展的场景下尤为不便。
开放泛型派生类型不方便处理。可以注册具体的封闭泛型类型，例如 Derived<int>，但不能把开放泛型 Derived<T> 一次性注册为通用的派生类型。

如果不想使用特性（例如基类来自第三方库，不便修改），也可以通过 JsonSerializerOptions.TypeInfoResolver 以代码方式配置 JsonPolymorphismOptions，达到同样的效果，但“白名单”这一本质并没有改变：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


var options = new JsonSerializerOptions
{
 TypeInfoResolver = new DefaultJsonTypeInfoResolver
 {
 Modifiers =
 {
 typeInfo =>
 {
 if (typeInfo.Type != typeof(Animal))
 {
 return;
 }

 typeInfo.PolymorphismOptions = new JsonPolymorphismOptions
 {
 TypeDiscriminatorPropertyName = "$type",
 DerivedTypes =
 {
 new JsonDerivedType(typeof(Dog), "dog"),
 new JsonDerivedType(typeof(Cat), "cat")
 }
 };
 }
 }
 }
};

为什么要设计成这样？

System.Text.Json 的这种“麻烦”并非能力不足，而是有意为之的安全设计。

回顾 Newtonsoft.Json 的 TypeNameHandling：JSON 中的 $type 是一个程序集限定名，反序列化器会据此在运行时加载并实例化任意类型。这意味着，只要攻击者能够控制输入的 JSON，就可以构造 payload 指向程序集中某个“危险”的类型，借助其构造函数、属性 setter 或终结器执行副作用，轻则造成拒绝服务，重则实现远程代码执行。因此官方文档也反复强调：处理不可信数据时，必须配合自定义的 SerializationBinder 来限制可解析的类型范围——但这个“补救措施”本身就是把白名单的责任又交还给了开发者。

这类“反序列化任意类型”的漏洞并非 .NET 独有。Java 生态中广为人知的 fastjson 就是前车之鉴：它的 AutoType 特性同样允许在 JSON 中通过 @type 指定任意类，自 2017 年被曝出的远程代码执行漏洞（CVE-2017-18349）开始，官方陷入了“发布黑名单补丁—被研究者绕过—再发补丁”的漫长拉锯战，绕过版本一直延续到 1.2.80 之后。最终 fastjson 不得不默认关闭 AutoType，并推出全面重构的 fastjson2——但即便是 2.x 版本，此后仍陆续被曝出多个严重漏洞，例如 2.0.62 及之前的版本存在可导致远程代码执行的哈希碰撞绕过，直到 2.0.63 才修复。这段历史充分说明：允许数据驱动类型实例化，是一条先天就布满陷阱的道路。

System.Text.Json 的设计者显然吸取了这些教训，选择了“默认安全”（secure by default）的路线：

鉴别器是不透明字符串，而非程序集限定名。JSON 中不再泄漏程序集和命名空间等内部信息，也让数据格式与具体语言、框架解耦。
反序列化采用白名单机制。只有显式注册过的派生类型才会被还原，攻击者无法通过篡改鉴别器字段来实例化意料之外的类型，从机制上根除了任意类型加载的风险。
多态契约显式化。基类上声明的派生类型列表本身就是一份文档，代码审查时可以一目了然地看出哪些类型会出现在 JSON 边界上。

所以，与其说这是 System.Text.Json 的“功能缺失”，不如说是一次在安全与便利之间的明确取舍：它放弃了 TypeNameHandling 式的便利，换来了无需额外配置即可抵御反序列化攻击的安心。只有在需要与既有的 $type 程序集限定名格式兼容时，才有必要保留 Newtonsoft.Json；而对于新代码，鉴别器 + 白名单的方案是更值得推荐的选择。

BSON

BSON（Binary JSON）是 MongoDB 设计的一种二进制文档格式，可以看作 JSON 的二进制超集：它在 JSON 的类型之外还定义了日期、ObjectId、二进制数据等额外类型，并且每个字段都带有类型标记，文档本身则记录了总长度，因此解析器可以快速定位、跳过不需要的字段。

Newtonsoft.Json 通过独立的 Newtonsoft.Json.Bson 包提供 BSON 支持，用法与 JSON 基本一致，只是把读写器换成 BsonDataReader / BsonDataWriter：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


using Newtonsoft.Json;
using Newtonsoft.Json.Bson;

var book = new Book { Title = "示例", Price = 42 };

byte[] bson;
using (var ms = new MemoryStream())
using (var writer = new BsonDataWriter(ms))
{
 JsonSerializer.CreateDefault().Serialize(writer, book);
 bson = ms.ToArray();
}

Book? restored;
using (var ms = new MemoryStream(bson))
using (var reader = new BsonDataReader(ms))
{
 restored = JsonSerializer.CreateDefault().Deserialize<Book>(reader);
}

而 System.Text.Json 并没有内置 BSON 支持。如果需要读写 BSON（例如对接 MongoDB），可以使用官方的 MongoDB.Bson 包。

Tip

BSON 并不比 JSON 更省空间。 “二进制格式”容易让人联想到压缩，但实际上 BSON 为了可遍历性付出了代价：每个元素都要额外存储一个字节的类型标记，字符串和文档还要带上长度前缀，字段名也依然以原文存储。对于常见的小对象，BSON 序列化结果往往跟 JSON 大小不相上下，甚至可能还更大。BSON 的优势在于解析效率和类型保真（日期、二进制数据无需 Base64 或字符串约定），而不是体积。

另外，如果真正诉求只是“用二进制格式紧凑地保存/传输数据”，那么还可以考虑专门的二进制序列化方案，例如 MessagePack。它会为整数选择足够表示数值的紧凑编码；至于字段名是否变成数组下标或整数，则取决于具体实现和配置。以 .NET 下的 MessagePack-CSharp 为例，显式使用整数 [Key] 时，对象会按数组形式编码，通常比重复写字符串字段名更省空间。对于以数值、二进制数据为主的模型，它往往会比 JSON 或 BSON 更小、更快，但具体效果还是要以实际数据测试为准。MessagePack 有许多跨语言实现，跨语言互通通常不是问题；MessagePack-CSharp 也支持源生成器，性能表现很好。

总结

对于大多数新项目，System.Text.Json 已经足够成熟，性能、AOT 和与 .NET 平台的整合也更有优势。一般的对象序列化、配置读写和 Web API，都可以优先从它开始；多态场景则建议使用鉴别器加白名单的方式，别为了省一点配置又把任意类型反序列化的口子打开。

不过，Newtonsoft.Json 也没有过时。JSONPath、DataTable / DataSet、填充既有对象、BSON，以及需要兼容历史 $type 格式的场景，继续使用它往往比自己补一堆转换器更省事。两者完全可以在同一个项目中各司其职，不必为了“统一”而强行替换。

还有一些差异，比如反序列化后的回调，对于模型没有的成员的处理，显式 null 以及可空性约束等配置，本文就不赘述了。大家可以在遇到的时候去查阅相关的文档。

如何在 .NET 中获取程序的根目录？

Tue, 04 Aug 2026 00:00:00 +0000

我们开发基于 C# 的客户端软件的时候，经常需要去获取应用程序的根目录，比如我们想要读取应用程序根目录下的配置文件，或者在根目录下创建日志文件等。这看起来应该是一个非常简单的需求，可是当我们想要去实现时，就会发现似乎存在很多能够达到目的的方法。比如：

AppContext.BaseDirectory
AppDomain.CurrentDomain.BaseDirectory
Environment.CurrentDirectory
Assembly.Location
- GetAssembly(typeof(Program))
- GetEntryAssembly()
- GetExecutingAssembly()
- GetCallingAssembly()

本文想要探讨的，就是在 .NET 中获取应用程序根目录的几种方法，它们的底层逻辑，以及它们的适用场景。相信在看完本文之后，你会对如何获取应用程序根目录有一个清晰的认识。

BaseDirectory

咱们先不绕弯子，直接公布正确答案（因为后面的几乎都是误导项）。想要获取应用程序的根目录，最合适的方式就是使用 BaseDirectory；对于现代 .NET 应用，通常推荐 AppContext.BaseDirectory。

AppContext.BaseDirectory 表示应用程序基目录的绝对路径。这个目录也是 .NET 运行时进行程序集探测时的起点之一；在一般的桌面程序、控制台程序或 Windows 服务中，它通常就是启动程序所在的目录。例如，程序位于 C:\Program Files\MyApp\MyApp.exe 时，返回值通常为 C:\Program Files\MyApp。

Info

AppContext 用于提供当前应用的上下文信息和开关，例如基目录、目标框架名称以及应用上下文开关。AppDomain 则是 .NET 中用于隔离程序集、配置和安全边界的运行时概念；在现代 .NET 中，一个进程通常只有默认的 AppDomain。AppContext.BaseDirectory 的值与 AppDomain.CurrentDomain.BaseDirectory 相对应，但新代码通常优先使用前者。

Environment.CurrentDirectory

接下来我们就来看一些不那么正确，或者“有时候正确，有时候不正确”的做法吧。首先就是 Environment.CurrentDirectory。此外还有 Directory.GetCurrentDirectory()，它其实也是访问的前者。

一般情况下，如果你是双击一个 EXE 程序直接运行，或者是运行一个它的快捷方式，又或者是在 Visual Studio 等 IDE 中直接运行（或调试）程序，那么 Environment.CurrentDirectory 返回的值通常就是应用程序的根目录。然而，如果你在命令行中运行程序，并且没有 cd 到程序所在的目录，而是从其他目录去运行它，那么 Environment.CurrentDirectory 返回的值就会是你当前所在的目录，而不是应用程序的根目录。这也就是“当前工作目录”（current working directory，CWD）的概念，它是一个进程在运行时的上下文信息，而不是应用程序本身的路径。

还有一种情况是，你在使用 dotnet cli，并且在项目的根目录借助 dotnet run 的方式来启动程序，那么同样会观察到当前工作目录是你运行这句指令时的所在位置。

Info

实际上是否选择使用 CurrentDirectory 也是一门技巧。并不是说任何时候都不应该选择这一路径。比如我们想要开发的是类似 FFmpeg 的控制台工具，那么你肯定希望用户在某个目录下通过你的工具转换了一个文件后，输出文件也出现在当前的目录下，而不是跑到了你的程序的根目录。否则用户就只能每次都繁琐地使用绝对路径了。

Assembly

接下来我们看一看跟程序集有关的一些方法吧。这些方法有时候能行，有时候不太能行，而且还有几个干扰项。

Assembly.Location

首先一个最容易想到的方式就是获取当前程序所属程序集的位置。通常我们的做法是：

Assembly.GetAssembly(typeof(Program))
typeof(Program).Assembly

这两种方式都是获取当前程序的程序集对象，然后通过 Assembly.Location 属性获取程序集的路径。这里我们选择了几乎所有程序都会有的 Program 类，从而确保它是来自入口项目的。虽然我们可以选择入口项目中的任何类型，但其他的看起来可能会很怪异，也不够直观。

这个方法如果成功，会直接返回对应程序集的 DLL 文件的绝对路径。然后我们再通过 Path.GetDirectoryName() 方法获取它的目录路径，即可获得应用程序的根目录。

不过，这种方式依赖程序集确实存在对应的物理文件。在 .NET 5 及更高版本的单文件发布中，打包进单文件的程序集并没有独立的 DLL 路径，Assembly.Location 会返回空字符串；另一方面，动态生成的程序集同样没有可供返回的程序集文件路径，访问 Assembly.Location 会抛出 NotSupportedException。

此外还有一个问题：如果当前代码不在入口项目中，我们没办法拿到诸如 Program 这样的属于入口项目的类型，那么我们就无法获取入口程序集对象了。虽然我们总是有 BaseDirectory 这样的正确方法，但这不妨碍我们就是想没事找事，用一用 Assembly 上面的其他方法对吧？🙃

Assembly.GetXXXAssembly()

接下来我们看一看 Assembly 上的几个获取程序集对象的方法：

GetEntryAssembly()：获取正在运行应用程序的入口程序集对象。对于大多数桌面应用程序和控制台应用程序，它通常就是包含 Main 方法的程序集。
GetExecutingAssembly()：获取包含当前正在执行代码的程序集对象。
GetCallingAssembly()：获取调用当前正在执行方法的那个方法所在的程序集对象。

假设解决方案中有一个控制台项目 MyApp 和一个被它引用的类库项目 MyLibrary。MyApp 的 Program 调用类库中的 AssemblyHelper.Print()：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// MyApp/Program.cs
MyLibrary.AssemblyHelper.Print();

// MyLibrary/AssemblyHelper.cs
using System.Reflection;

namespace MyLibrary;

public static class AssemblyHelper
{
 public static void Print()
 {
 Console.WriteLine(Assembly.GetEntryAssembly()?.GetName().Name);
 Console.WriteLine(Assembly.GetExecutingAssembly().GetName().Name);
 Console.WriteLine(Assembly.GetCallingAssembly().GetName().Name);
 }
}

输出通常如下：

1
2
3


MyApp
MyLibrary
MyApp

可以看到，GetEntryAssembly() 始终指向应用入口程序集，适合在类库中反向取得宿主应用的信息；GetExecutingAssembly() 指向定义 Print 方法的类库程序集；GetCallingAssembly() 则指向调用 Print 的程序集。若把对 Print() 的调用再封装到另一个类库中，最后一项也会随之变为那个中间类库，而不再是 MyApp。

不过，GetCallingAssembly() 的结果依赖调用栈，且可能受到 JIT 内联优化的影响。至于 GetEntryAssembly()，即便它获取了入口程序集，单文件发布时其 Location 仍可能为空字符串。此外，有一种比较少见的情况是，非托管程序（例如 C++ 开发的程序）调用托管程序集（例如借助 COM 互操作等方式）时，GetEntryAssembly() 可能返回 null，因为入口程序集并非托管程序集。

总结

“获取程序根目录”这个需求的关键，在于先区分自己真正需要的是哪一种路径：应用的部署目录、进程的当前工作目录，还是某个程序集文件的位置。这些路径在本地调试时经常相同，但它们的来源和稳定性并不相同。

若要定位与应用程序一同部署的配置、资源或其他文件，应使用 AppContext.BaseDirectory。这是获取应用程序基目录的首选方式，也能正确应对单文件发布。
若要按用户启动程序时所在的位置解析相对路径，应使用 Environment.CurrentDirectory 或 Directory.GetCurrentDirectory()；不要假定它始终等于应用程序根目录。
若要确认某个程序集实际从哪里加载，可以使用 Assembly.Location。但它描述的是程序集文件的位置，并不等同于应用程序根目录；单文件发布、动态程序集等场景下也不可靠。
GetEntryAssembly()、GetExecutingAssembly() 和 GetCallingAssembly() 的职责是确定不同语义下的程序集对象，而不是解决目录定位问题。尤其是 GetCallingAssembly() 会受到调用栈和 JIT 优化的影响。

因此，如果问题确实是“应用程序根目录在哪里”，就不要折磨自己了，直接选择正确答案吧：

1

string baseDirectory = AppContext.BaseDirectory;

Figgle：在控制台中打印 ASCII 艺术字

Wed, 22 Jul 2026 00:00:00 +0000

我的一些 C# 的教学视频里经常会用到一种看起来很华丽的 ASCII 艺术字，形如：

1
2
3
4
5
6
7
8


 _____ _____ _ 
 / ____|/ ____| | 
| | | (___ | |__ __ _ _ __ _ __ 
| | \___ \| '_ \ / _` | '__| '_ \
| |____ ____) | | | | (_| | | | |_) |
 \_____|_____/|_| |_|\__,_|_| | .__/
 | | 
 |_|

或者

1
2
3
4
5
6
7
8
9


 ____ ____ __ 
/\ _`\ /\ _`\ /\ \ 
\ \ \/\_\\ \,\L\_\ \ \___ __ _ __ _____ 
 \ \ \/_/_\/_\__ \\ \ _ `\ /'__`\ /\`'__\/\ '__`\
 \ \ \L\ \ /\ \L\ \ \ \ \ \/\ \L\.\_\ \ \/ \ \ \L\ \
 \ \____/ \ `\____\ \_\ \_\ \__/.\_\\ \_\ \ \ ,__/
 \/___/ \/_____/\/_/\/_/\/__/\/_/ \/_/ \ \ \/
 \ \_\
 \/_/

经常会有观众问我这样的文字是怎么生成的。其实很简单，我用了 Figgle 这个 NuGet 库。

Figgle 是一个用于在 .NET 程序中生成 ASCII 艺术字横幅的开源库。给它一段普通文本和一种字体，它就能将文本渲染成上面那样由普通字符组成的“大字”。它很适合用在命令行工具的启动 Banner、示例程序的标题，或者需要在终端里突出显示某些信息的场景。

Figgle 的名字和能力都来自更早的 FIGlet 项目。FIGlet 是一个经典的命令行程序，最早由 Glenn Chappell 在 1991 年编写；它使用 .flf 字体文件，将文本转换为 ASCII 艺术字。此后，社区积累了大量不同风格的 FIGlet 字体。

Figgle 将这种成熟的字体格式和渲染方式带到了 .NET 生态中。它并不是自己定义一套新的艺术字格式，而是负责解析 FIGlet 字体并输出渲染结果。因此，Figgle 既可以使用它提供的现成字体，也可以使用自己找到或制作的 .flf 字体文件。

Figgle 的几个 NuGet 包

Figgle 项目目前主要发布了三个 NuGet 包，它们分别面向不同的使用方式。

`Figgle`

Figgle 是核心包，负责解析 FIGlet 字体和渲染文本。它不包含完整的字体集合，因此包本身比较轻量。

如果项目中使用的是自定义 .flf 文件，或者通过源生成器把字体嵌入到了自己的程序集里，运行时通常只需要引用这个包。

`Figgle.Fonts`

Figgle.Fonts 是字体包，内置了 250 多种 FIGlet 字体（截止到写这篇文章时的 0.6.6 版本，共有 265 种字体）。最简单的使用方式就是同时安装 Figgle 和它，然后通过 FiggleFonts 类取得某一种预置字体。

1
2


dotnet add package Figgle
dotnet add package Figgle.Fonts

后面会看到，诸如 Standard、Slant、Graffiti 等常用字体，都是由这个包提供的。它适合快速尝试不同的效果；代价是应用会携带完整字体集。

`Figgle.Generator`

Figgle.Generator 是一个 C# 源生成器包，主要用来优化发布体积和运行时开销。

它有两种典型用法：对于编译期就确定的文本，直接在编译时生成最终的 ASCII 字符串；对于运行时才确定的文本，则只将实际会用到的字体嵌入程序集。这样就无需在最终应用中携带完整的 Figgle.Fonts 字体包。

Note

如果只是想在小型控制台项目里快速打印一个标题，直接使用 Figgle 和 Figgle.Fonts 就足够了。Figgle.Generator 更适合在意应用体积，或只需要少数几个固定字体的场景。

使用 Figgle 和 Figgle.Fonts

对于大多数控制台程序而言，直接引用 Figgle 与 Figgle.Fonts 是最简单的方式。前者提供渲染能力，后者提供预置字体；安装命令在上文已经列出。

安装完成后，在代码中引入 Figgle 命名空间，即可通过 FiggleFonts 访问字体。下面的示例使用默认的 Standard 字体，将普通字符串渲染为 ASCII 艺术字：

1
2
3


using Figgle;

Console.WriteLine(FiggleFonts.Standard.Render("Hello, World!"));

Render 方法接收需要显示的文本，返回一个包含换行符的字符串。

Figgle.Fonts 内置了 250 多种字体。不同字体的高度、宽度和风格差异很大，只要更换 FiggleFonts 上的字体属性，就能得到完全不同的效果。

例如，Slant 字体会让字符呈现倾斜效果，而 ThreePoint 字体非常紧凑，适合控制台宽度有限，或者不希望 Banner 占用太多行的场景。

1
2
3
4


using Figgle;

Console.WriteLine(FiggleFonts.Slant.Render("Figgle"));
Console.WriteLine(FiggleFonts.ThreePoint.Render("Figgle"));

Tip

在选择字体时，建议同时考虑终端窗口的宽度和文本长度，并务必使用等宽字体（常见的有 Consolas、Courier New、Monaco 等），否则 ASCII 艺术字的对齐会被破坏。另外，Figgle 只支持 ASCII 字符，也就是英文字母、数字和常用符号；中文或其他非 ASCII 字符无法渲染。

使用 Figgle.Generator

直接引用 Figgle.Fonts 很方便，但它会将全部 265 种字体一并带入应用。对于只使用一个固定 Banner 的程序，这显然有些浪费。Figgle.Generator 是一个 C# 源生成器：它会在编译时读取字体并生成 C# 代码，让最终程序只保留真正需要的内容。

根据文本是否在编译时确定，源生成器有两种用法。

在编译期生成固定文本

如果 Banner 的内容固定，例如程序名称或版本标题，可以让源生成器直接将最终的 ASCII 字符串写入程序集。此时运行时不需要 Figgle 或 Figgle.Fonts。

先安装源生成器。PrivateAssets="all" 表示该包只在编译期使用，不会作为依赖传递给引用当前项目的其他项目：

1
2
3


<ItemGroup>
 <PackageReference Include="Figgle.Generator" Version="0.6.6" PrivateAssets="all" />
</ItemGroup>

然后为一个 partial 类添加 GenerateFiggleText 特性：

1
2
3
4
5
6
7


using Figgle;

[GenerateFiggleText(
 memberName: "Title",
 fontName: "slant",
 sourceText: "My Application")]
internal static partial class AsciiBanners;

编译时，源生成器会在 AsciiBanners 中生成名为 Title 的静态成员。使用时直接读取它即可：

1

Console.WriteLine(AsciiBanners.Title);

这里的 fontName 使用的是 FIGlet 字体名称，而不是 FiggleFonts.Slant 这样的 C# 属性名。字体名不区分大小写。

嵌入字体并在运行时渲染

如果需要渲染的文本直到运行时才能确定，例如将用户输入、服务器名称或当前环境名称输出为艺术字，就不能预先生成最终字符串。不过仍然可以只嵌入一个需要的字体。

这种方式需要在运行时引用核心包，并在编译期引用源生成器：

1
2
3
4


<ItemGroup>
 <PackageReference Include="Figgle" Version="0.6.6" />
 <PackageReference Include="Figgle.Generator" Version="0.6.6" PrivateAssets="all" />
</ItemGroup>

使用 EmbedFiggleFont 特性声明要嵌入的字体：

1
2
3
4
5
6


using Figgle;

[EmbedFiggleFont(
 memberName: "Slant",
 fontName: "slant")]
internal static partial class EmbeddedFonts;

编译后会得到一个 FiggleFont 对象，因此可以像普通字体一样在运行时调用 Render：

1
2


string environmentName = Environment.MachineName;
Console.WriteLine(EmbeddedFonts.Slant.Render(environmentName));

最终应用只会包含 Figgle 核心库和 slant 字体，不再依赖完整的 Figgle.Fonts 包。

Tip

固定文本优先使用 GenerateFiggleText，因为它连运行时渲染和核心库都不需要；只有在文本动态变化时，才选择 EmbedFiggleFont。

常用字体推荐

虽然 FiggleFonts 里面包含了大量的字体，但其实个人觉得 90% 以上的都完全用不上，或者可读性非常差。所以这里我挑选了一些个人向的常用字体，供大家参考。下面的例子都以“Figgle”为例。

Big

1
2
3
4
5
6
7
8


 ______ _ _ 
| ____(_) | | 
| |__ _ __ _ __ _| | ___
| __| | |/ _` |/ _` | |/ _ \
| | | | (_| | (_| | | __/
|_| |_|\__, |\__, |_|\___|
 __/ | __/ | 
 |___/ |___/ 

此外，Standard、Doom、IVrit 都与此类似，只是细节和大小上略有差异。

Slant

1
2
3
4
5
6
7



 _______ __ 
 / ____(_)___ _____ _/ /__ 
 / /_ / / __ `/ __ `/ / _ \
 / __/ / / /_/ / /_/ / / __/
 /_/ /_/\__, /\__, /_/\___/ 
 /____//____/ 

Ogre

1
2
3
4
5
6


 ___ _ _ 
 / __(_) __ _ __ _| | ___ 
 / _\ | |/ _` |/ _` | |/ _ \
/ / | | (_| | (_| | | __/
\/ |_|\__, |\__, |_|\___|
 |___/ |___/ 

Larry3d

1
2
3
4
5
6
7
8
9


____ ___ 
/\ _`\ __ /\_ \ 
\ \ \L\_\/\_\ __ __ \//\ \ __ 
 \ \ _\/\/\ \ /'_ `\ /'_ `\ \ \ \ /'__`\ 
 \ \ \/ \ \ \/\ \L\ \/\ \L\ \ \_\ \_/\ __/ 
 \ \_\ \ \_\ \____ \ \____ \/\____\ \____\
 \/_/ \/_/\/___L\ \/___L\ \/____/\/____/
 /\____/ /\____/ 
 \_/__/ \_/__/ 

预览全部字体

如果大家还拿不定主意，那么可以用下面这个 C# 脚本来快速预览所有字体。使用 .NET 10 新增的 dotnet run app.cs 即可。如果版本比较低，只需要把它改成一个传统的 C# 控制台项目即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


#:package Figgle.Fonts@0.6.6 // 它依赖 Figgle，会自动引入

using System.Reflection;
using Figgle;
using Figgle.Fonts;

var fonts = typeof(FiggleFonts)
 .GetProperties(BindingFlags.Public | BindingFlags.Static)
 .Where(p => p.PropertyType == typeof(FiggleFont))
 .Select(p => new { p.Name, Font = (FiggleFont)p.GetValue(null)! })
 .ToArray();

Console.Write("Enter text to render: ");
var input = Console.ReadLine();

foreach (var font in fonts)
{
 Console.WriteLine($"Font: {font.Name}");
 Console.WriteLine(font.Font.Render(input));
 Console.WriteLine();
}

System.Text.Json：.NET 内置的 JSON 库

Mon, 06 Jul 2026 00:00:00 +0000

在 .NET 平台上提到 JSON 序列化，很多人第一时间想到的还是 Newtonsoft.Json。这款诞生于 2006 年的第三方库长期占据 NuGet 下载量榜首，一度几乎是 .NET 项目的"标配"。但自 .NET Core 3.0 起，框架已经内置了 System.Text.Json 这款现代化的 JSON 库，并在 ASP.NET Core 中将其设为默认序列化器。

本文就来系统地梳理一下 System.Text.Json 的历史背景、基本用法、Record 支持、JsonNode 动态 DOM 以及源生成器等特性，帮助你全面了解这款内置 JSON 库。

历史

早期的官方库

.NET 早期有两个官方 JSON 库，但均是面向特定框架的延伸，而非通用解决方案：

JavaScriptSerializer（System.Web.Script.Serialization，.NET 3.5）随 ASP.NET AJAX 一同引入。功能相当原始，不支持 LINQ、不支持复杂类型映射，而且锁在 System.Web 程序集内，非 Web 项目根本无法引用。

DataContractJsonSerializer（System.Runtime.Serialization.Json，.NET 3.0）面向 WCF 设计，序列化行为由 [DataContract] / [DataMember] 特性驱动。它对类型结构有严格要求，对字典、匿名类型等常见场景支持有限，且不与 Web API 路径对齐。

Newtonsoft.Json 的崛起

正是因为官方库的局限，Newtonsoft.Json 应运而生。它实现了当时官方库所缺少的一切：灵活的转换器体系、LINQ to JSON（JObject/JArray）、丰富的序列化选项，以及对动态类型和跟踪引用等复杂场景的良好支持。它很快成为 .NET 生态中最流行的第三方库，长期占据 NuGet 下载量榜首。微软也在 ASP.NET Web API 和早期的 ASP.NET Core（直到 2.x）中采用它作为默认序列化器。

Info

Newtonsoft.Json 由 James Newton-King 于 2006 年创建。包名中的 “Newtonsoft” 取自作者姓氏 Newton-King，而 Json.NET 则是它更广为人知的别称。

现代化的挑战

然而，Newtonsoft.Json 的设计根植于早期 .NET，随着 .NET 的现代化，它的两个先天缺陷逐渐显现：

高度依赖反射：内部大量使用 string（UTF-16）中间表示，在高并发、低延迟场景下内存分配和 GC 压力成为瓶颈
阻碍裁剪和 NativeAOT：反射阻止编译器静态分析代码依赖，导致裁剪无法移除未使用的成员；NativeAOT 所需的部分反射 API 直接不可用

System.Text.Json 的诞生

2019 年 9 月，随 .NET Core 3.0 发布，微软推出了内置库 System.Text.Json。它以 UTF-8 字节流为核心，从设计层面就为低分配、高吞吐量而优化，序列化性能在大多数场景下从第一个版本起就超过了 Newtonsoft.Json。ASP.NET Core 3.0 同步将默认序列化器从 Newtonsoft.Json 切换为 System.Text.Json，并将 Newtonsoft.Json 从共享框架中移除。

不过，初版的功能覆盖局限相当明显，许多 Newtonsoft 用户习以为常的特性都不支持。此后多个版本持续补齐：

（.NET 5）支持公共字段的序列化
（.NET 5）支持通过带参数的构造函数创建不可变对象（包括 C# 9 record）
（.NET 6）支持源生成器，避免使用反射，更好地支持 NativeAOT 发布
（.NET 6）JsonNode（可变 DOM），类似 JObject
（.NET 8）内置命名策略新增 SnakeCaseLower、SnakeCaseUpper、KebabCaseLower、KebabCaseUpper（CamelCase 从 .NET Core 3.0 起即可用）

基本用法

了解了它的来龙去脉之后，我们来看看实际该怎么用。

序列化与反序列化

JsonSerializer 是主要入口，提供 Serialize / Deserialize 静态方法：

1
2
3
4
5
6


var person = new Person { Name = "Alice", Age = 30 };

string json = JsonSerializer.Serialize(person);
// {"Name":"Alice","Age":30}

Person? result = JsonSerializer.Deserialize<Person>(json);

如果需要与 Stream 或网络 I/O 直接交互，可以用 UTF-8 字节数组的重载，避免中间字符串分配：

1
2
3
4
5
6


byte[] bytes = JsonSerializer.SerializeToUtf8Bytes(person);
Person? result = JsonSerializer.Deserialize<Person>(bytes);

// 也支持直接读写 Stream
await JsonSerializer.SerializeAsync(stream, person);
Person? result = await JsonSerializer.DeserializeAsync<Person>(stream);

配置（JsonSerializerOptions）

通过 JsonSerializerOptions 控制序列化行为。由于首次构造时会做元数据缓存，建议声明为静态字段复用，避免重复开销：

1
2
3
4
5
6
7


private static readonly JsonSerializerOptions s_options = new()
{
 WriteIndented = true,
 PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};

string json = JsonSerializer.Serialize(person, s_options);

常用选项一览：

选项	说明
`WriteIndented`	输出带缩进的格式化 JSON
`PropertyNamingPolicy`	属性名转换策略（见下文）
`PropertyNameCaseInsensitive`	反序列化时属性名大小写不敏感
`DefaultIgnoreCondition`	全局忽略条件，如统一忽略所有 null 值
`IncludeFields`	将公共字段也纳入序列化（.NET 5+）
`AllowTrailingCommas`	允许 JSON 末尾多余的逗号
`ReadCommentHandling`	允许读取 JSON 中的注释

命名策略

PropertyNamingPolicy 统一转换所有属性名的大小写风格：

1
2
3
4
5
6
7
8


// camelCase → {"firstName":"Alice"}
PropertyNamingPolicy = JsonNamingPolicy.CamelCase

// snake_case（.NET 8+）→ {"first_name":"Alice"}
PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower

// SCREAMING_SNAKE_CASE（.NET 8+）→ {"FIRST_NAME":"Alice"}
PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper

Tip

PropertyNamingPolicy 只影响序列化输出的键名。如果希望反序列化时也能匹配不同大小写的 JSON 键，还需要开启 PropertyNameCaseInsensitive = true。

Web 预设（.NET 5+）

JsonSerializerDefaults.Web 是专为 Web API 场景准备的快捷预设，一次性启用 camelCase + 大小写不敏感 + 数字可来自字符串：

1

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);

ASP.NET Core 的 JSON 配置默认就使用该预设。

特性标注

当需要对个别成员做精细控制时，可以在属性或字段上标注特性，优先级高于全局选项。

`[JsonPropertyName]`

指定该成员在 JSON 中使用的键名，不受命名策略影响：

1
2
3
4
5
6


public class Person
{
 [JsonPropertyName("full_name")]
 public string Name { get; set; }
}
// → {"full_name":"Alice"}

`[JsonIgnore]`

排除某个成员，不参与序列化和反序列化：

1
2
3
4
5
6
7


public class User
{
 public string Name { get; set; }

 [JsonIgnore]
 public string PasswordHash { get; set; }
}

用 Condition 参数可以做条件忽略，而不是始终忽略：

1
2
3
4
5


[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Nickname { get; set; }

[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public int Score { get; set; } // 值为 0 时不输出

与之等效的全局写法：

1
2
3
4


new JsonSerializerOptions
{
 DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
}

`[JsonInclude]`（.NET 5+）

默认只处理公共属性（property）。要将公共字段（field）也纳入序列化，有两种方式：

1
2
3
4
5
6
7
8
9


// 方式一：逐个标注
public class Point
{
 [JsonInclude] public int X;
 [JsonInclude] public int Y;
}

// 方式二：全局开启（适合字段较多时）
new JsonSerializerOptions { IncludeFields = true }

Tip

虽然可以全局开启 IncludeFields，但公共字段在现代 C# 中并不常用，全局开启会让所有类型的序列化行为都受到影响。更推荐的做法是为涉及字段的特殊类型单独创建一个专用的 JsonSerializerOptions 实例，按需传入即可。

`[JsonPropertyOrder]`（.NET 6+）

控制属性在 JSON 输出中的排列顺序，数值越小越靠前，默认值为 0：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public class ApiResponse
{
 [JsonPropertyOrder(-1)] // 排在最前
 public bool Success { get; set; }

 public string Message { get; set; } // 默认 0

 [JsonPropertyOrder(1)] // 排在最后
 public object? Data { get; set; }
}

Record 类型

前面介绍的特性标注都是在"可变类型"上做精细控制。但现代 C# 中，我们越来越倾向于使用不可变的数据模型——这就轮到 record 出场了。

从 .NET 5 起，System.Text.Json 支持通过带参数的构造函数反序列化，这使 record 成为 JSON 数据模型的理想选择——不需要任何额外代码，就能同时拥有不可变性和完整的序列化支持。

Info

默认的反序列化路径是先调用无参构造函数创建实例，再通过属性 setter 赋值。但 record 的属性通常是只读的（init setter），且 record 通常只暴露带参构造函数、没有无参构造函数，这条默认路径自然走不通。因此序列化器需要通过带参构造函数，在创建对象的同时把值注入进去。否则恐怕就只能借助反射了。

位置 Record

最简洁的形式是位置 record（positional record），声明即可直接使用：

1

public record Person(string Name, int Age);

序列化与普通类型完全一致：

1
2
3


var person = new Person("Alice", 30);
string json = JsonSerializer.Serialize(person);
// {"Name":"Alice","Age":30}

反序列化时，System.Text.Json 会自动定位主构造函数，将 JSON 中的键按名称注入对应参数：

1

Person p = JsonSerializer.Deserialize<Person>("""{"Name":"Alice","Age":30}""")!;

选择构造函数：`[JsonConstructor]`

如果不使用上述最简单的 record 声明方式，并且部分属性有诸如 private set 甚至没有 setter 的情况，那么就需要提供带参构造函数来实现反序列化了。当类型有多个构造函数时，必须用 [JsonConstructor] 明确指定反序列化使用哪一个：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public record Point
{
 public int X { get; }
 public int Y { get; }

 [JsonConstructor]
 public Point(int x, int y) => (X, Y) = (x, y);

 public Point(int x) : this(x, 0) { }
}

只有单个构造函数时无需标注：有唯一的有参构造函数则自动选择它，只有无参构造函数则走属性赋值路径。

参数名匹配

反序列化时，JSON 键与构造函数参数名做大小写不敏感匹配，因此下面三种写法都能正确反序列化到 Person(string Name, int Age)：

1
2
3


{ "Name": "Alice", "Age": 30 }
{ "name": "Alice", "age": 30 }
{ "NAME": "Alice", "AGE": 30 }

如需映射到不同的 JSON 键名，在位置 record 上使用 [property: JsonPropertyName(...)]（property: 前缀是为了将特性作用到自动生成的属性上，而非构造函数参数）：

1
2
3
4
5
6


public record Person(
 [property: JsonPropertyName("full_name")] string Name,
 int Age
);
// 序列化 → {"full_name":"Alice","Age":30}
// 反序列化匹配键 "full_name"

非位置 record 或普通 class 则直接标注在属性上即可，无需 property: 前缀。

JsonNode

到目前为止，我们都是在"提前知道 JSON 结构"的前提下做序列化。但实际开发中，经常会遇到结构不固定的 JSON——比如配置文件、第三方 API 返回的动态数据等。这种时候就需要 JsonNode 出场了。

JsonNode 是 .NET 6 引入的可变 DOM，适用于不方便预定义类型的场景：处理结构不固定的 JSON、只需读写其中几个字段、或者动态拼装 JSON 请求体等。

它由四个类型组成，与 Newtonsoft 的类型一一对应：

System.Text.Json	Newtonsoft.Json	说明
`JsonNode`	`JToken`	所有节点的抽象基类
`JsonObject`	`JObject`	JSON 对象 `{ }`
`JsonArray`	`JArray`	JSON 数组 `[ ]`
`JsonValue`	`JValue`	标量值（字符串、数字、布尔等）

解析与读取

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


string json = """
 {
 "name": "Alice",
 "age": 30,
 "scores": [95, 87, 92],
 "address": { "city": "Beijing" }
 }
 """;

JsonNode root = JsonNode.Parse(json)!;

string name = root["name"]!.GetValue<string>(); // "Alice"
string city = root["address"]!["city"]!.GetValue<string>(); // "Beijing"
int age = (int)root["age"]!; // 30

Newtonsoft 的等效写法几乎相同，仅取值方法有差异：

1
2
3
4


JObject root = JObject.Parse(json);
string name = root["name"]!.Value<string>();
string city = root["address"]!["city"]!.Value<string>();
int first = (int)root["scores"]![0]!;

Tip

JsonNode 的索引器返回 JsonNode?（可空），所以读取链中常见 !。Newtonsoft 的 JToken 在类型转换上更宽松，支持隐式转换运算符，但代价是运行时类型错误更难察觉。

构建 JSON

JsonObject 支持像 Dictionary 那样初始化，同时 JsonArray 支持集合初始化器语法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var node = new JsonObject
{
 ["name"] = "Alice",
 ["age"] = 30,
 ["scores"] = new JsonArray(95, 87, 92),
 ["address"] = new JsonObject
 {
 ["city"] = "Beijing"
 }
};

string json = node.ToJsonString();
// {"name":"Alice","age":30,"scores":[95,87,92],"address":{"city":"Beijing"}}
// ToJsonString 方法支持传入 options

与 Newtonsoft 的 new JObject { ["key"] = value } 语法几乎相同，ToJsonString() 对应 Newtonsoft 的 ToString()。

修改 DOM

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


JsonNode root = JsonNode.Parse(json)!;

// 添加 / 修改
root["email"] = "alice@example.com";
root["age"] = 31;

// 删除属性
root.AsObject().Remove("address");

// 向数组追加元素
root["scores"]!.AsArray().Add(100);

Newtonsoft 可以直接将 JToken 强转为 JObject 或 JArray，而 JsonNode 需要调用 .AsObject() / .AsArray() 方法显式转换。

与强类型对象互转

1
2
3
4
5
6
7


var person = new Person("Alice", 30);

// 强类型 → JsonNode
JsonNode node = JsonSerializer.SerializeToNode(person)!;

// JsonNode → 强类型
Person? p = node.Deserialize<Person>();

Newtonsoft 对应的是 JObject.FromObject(person) 和 obj.ToObject<Person>()。

遍历

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 遍历对象的所有键值对
foreach (var (key, value) in root.AsObject())
{
 Console.WriteLine($"{key}: {value}");
}

// 遍历数组
foreach (JsonNode? item in root["scores"]!.AsArray())
{
 Console.WriteLine(item!.GetValue<int>());
}

只读场景：JsonDocument

如果只需要读取、不需要修改，可以使用更早引入（.NET Core 3.0）的 JsonDocument / JsonElement。它在解析时使用池化缓冲区（pooled buffer）来存储数据，读取性能更高，但节点不可修改，且需要手动 Dispose 以归还缓冲区：

1
2
3
4
5


using JsonDocument doc = JsonDocument.Parse(json);
JsonElement root = doc.RootElement;

string name = root.GetProperty("name").GetString()!;
int age = root.GetProperty("age").GetInt32();

Info

需要修改或构建 JSON → 用 JsonNode；只需读取且追求极致性能 → 考虑 JsonDocument。

自定义转换器：JsonConverter

前面介绍的特性标注、Record 支持都是在调整"结构化对象"的映射细节，但类型在 JSON 中终归还是以对象或数组的形式出现。如果某个类型期望的 JSON 表示形式和它的 C# 结构完全不同——比如一个只包裹了单个值的类型，希望直接序列化成该值本身，而不是嵌套对象——就需要继承 JsonConverter<T>，自己接管读写过程。

自定义转换器需要重写两个方法：Read 从 Utf8JsonReader 中解析出目标类型，Write 通过 Utf8JsonWriter 输出目标格式。

示例一：简化 Wrapper 类型

强类型 ID 是很常见的 wrapper 类型，用于避免不同实体的主键在方法签名中被混用：

1

public readonly record struct UserId(int Value);

默认序列化会得到一个嵌套对象，这通常不是我们想要的效果：

1

{ "Value": 123 }

写一个转换器，让它直接以数字形式读写：

1
2
3
4
5
6
7
8


public class UserIdJsonConverter : JsonConverter<UserId>
{
 public override UserId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
 => new UserId(reader.GetInt32());

 public override void Write(Utf8JsonWriter writer, UserId value, JsonSerializerOptions options)
 => writer.WriteNumberValue(value.Value);
}

由于类型是自己定义的，可以直接用 [JsonConverter] 标注在类型上，之后无需在每个使用处重复指定：

1
2


[JsonConverter(typeof(UserIdJsonConverter))]
public readonly record struct UserId(int Value);

序列化结果变为：

1

123

示例二：将 DateTime 转为时间戳

DateTime 默认序列化为 ISO 8601 字符串（如 "2026-07-18T00:00:00Z"），但对接某些第三方接口时，可能需要 Unix 时间戳（自 1970-01-01 起的秒数）：

1
2
3
4
5
6
7
8


public class UnixTimestampConverter : JsonConverter<DateTime>
{
 public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
 => DateTimeOffset.FromUnixTimeSeconds(reader.GetInt64()).UtcDateTime;

 public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
 => writer.WriteNumberValue(new DateTimeOffset(value, TimeSpan.Zero).ToUnixTimeSeconds());
}

与 UserId 不同，DateTime 是内置类型，不能给它加特性，因此只能标注在具体的属性上：

1
2
3
4
5


public class Order
{
 [JsonConverter(typeof(UnixTimestampConverter))]
 public DateTime CreatedAt { get; set; }
}

如果项目里所有 DateTime 都要走同一套时间戳格式，逐个属性标注就太繁琐了，可以改为通过 JsonSerializerOptions.Converters 全局注册，对该类型的所有出现位置统一生效：

1
2


var options = new JsonSerializerOptions();
options.Converters.Add(new UnixTimestampConverter());

Tip

[JsonConverter] 标注在属性上时优先级最高，会覆盖全局注册的转换器；同一类型只需在两者之一处配置即可，不必重复。

源生成器

无论是强类型的 JsonSerializer，还是动态的 JsonNode，它们在底层都依赖同一套机制——反射。而反射在性能和 NativeAOT 场景下都有隐患，源生成器就是为解决这个问题而生的。

默认情况下，System.Text.Json 依赖反射在运行时读取类型的属性和构造函数信息。这存在两个问题：

首次调用时有预热开销，序列化器需要通过多层反射逐一检查所有类型并缓存元数据
阻碍裁剪（trimming）和 NativeAOT，编译器无法静态分析哪些成员会被访问，只能保留全部代码

源生成器（Source Generator）在编译期分析类型并生成序列化代码，完全绕开反射。

基本配置

创建一个继承自 JsonSerializerContext 的 partial 类，用 [JsonSerializable] 注册需要处理的顶层类型：

1
2
3


[JsonSerializable(typeof(Person))]
[JsonSerializable(typeof(List<Person>))]
internal partial class AppJsonContext : JsonSerializerContext { }

编译器会自动生成这个类的实现部分。

Tip

只需注册顶层类型（即直接传入 JsonSerializer 的那个）。成员的类型会自动递归处理，无需单独注册。但集合类型必须明确注册，如 List<Person> 和 Person 需要分别注册。

使用方式

通过 AppJsonContext.Default 访问生成的上下文单例：

1
2
3
4
5
6
7


// 传入 JsonTypeInfo<T>（推荐）
string json = JsonSerializer.Serialize(person, AppJsonContext.Default.Person);
Person? p = JsonSerializer.Deserialize<Person>(json, AppJsonContext.Default.Person);

// 传入 JsonSerializerContext（适合泛型 / 运行时才知道类型的场景）
object obj = person;
string json = JsonSerializer.Serialize(obj, person.GetType(), AppJsonContext.Default);

两种方式均不使用反射。第一种将类型信息完全确定在编译期，还能走序列化优化路径（见下文），是首选。

配置选项

序列化选项通过 [JsonSourceGenerationOptions] 在编译期指定，等效于运行时的 JsonSerializerOptions：

1
2
3
4
5
6


[JsonSourceGenerationOptions(
 WriteIndented = true,
 PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
 DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
[JsonSerializable(typeof(Person))]
internal partial class AppJsonContext : JsonSerializerContext { }

Info

PropertyNamingPolicy 这里使用的是 JsonKnownNamingPolicy（枚举），而非运行时的 JsonNamingPolicy（类）。

两种生成模式

源生成器有两种工作模式，默认同时启用：

元数据模式（JsonSourceGenerationMode.Metadata）：生成 JSON 契约元数据，支持反序列化、循环引用、多态等复杂场景。

序列化优化模式（JsonSourceGenerationMode.Serialization）：直接生成调用 Utf8JsonWriter 的序列化代码（又称 fast-path），跳过运行时选项检查，序列化性能最高。但它不支持反序列化。

可以在单个类型上指定模式：

1
2
3


[JsonSerializable(typeof(Person), GenerationMode = JsonSourceGenerationMode.Serialization)]
[JsonSerializable(typeof(Order), GenerationMode = JsonSourceGenerationMode.Metadata)]
internal partial class AppJsonContext : JsonSerializerContext { }

NativeAOT 与裁剪

发布 NativeAOT 时，由于反射 API 不可用，必须使用源生成器。建议同时显式关闭默认反射（JsonSerializerIsReflectionEnabledByDefault=false），这样在开发调试阶段就能提前发现仍走反射路径的代码，而不是等到发布时才报错：

1
2
3
4


<PropertyGroup>
 <PublishAot>true</PublishAot>
 <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
</PropertyGroup>

Info

如果你只是启用裁剪（PublishTrimmed=true）而非 NativeAOT，.NET 8 起会自动将 JsonSerializerIsReflectionEnabledByDefault 设为 false，无需手动配置。但显式设置仍然有助于在调试阶段尽早发现问题。

与 ASP.NET Core 集成

ASP.NET Core 内部的 JSON 序列化可以通过 TypeInfoResolverChain 接入源生成上下文：

1
2
3
4


builder.Services.ConfigureHttpJsonOptions(options =>
{
 options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

TypeInfoResolverChain（.NET 8+）支持链接多个上下文：当一个上下文找不到某个类型的信息时，会自动尝试链中的下一个。这在将多个库的上下文合并使用时尤为有用。

总结

System.Text.Json 是 .NET 平台上现代化的 JSON 序列化方案。相比 Newtonsoft.Json，它在性能、内存分配和 NativeAOT 支持上都有显著优势，并且自 .NET Core 3.0 起就作为框架内置库随附，无需额外引入第三方依赖。

如果你正在从 Newtonsoft.Json 迁移，本文梳理的 JsonNode、Record 支持、特性标注和 JsonConverter 自定义转换等内容应该能覆盖大多数日常场景。而对于追求极致性能或需要 NativeAOT 发布的项目，源生成器则是必选项。随着 .NET 的持续演进，System.Text.Json 的功能覆盖已经相当完善，完全可以在大多数项目中替代 Newtonsoft.Json。

WPF TabControl 控件的子元素的加载事件该如何对待

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

TabControl 是 WPF 中一个相当常用的控件。当我们需要设计一个多页面的界面时，借助 TabControl 可以很方便地实现页面的切换。然而，TabControl 的一些行为可能不太符合我们的预期，尤其是关于子元素的加载与卸载的时机。具体是怎么一回事呢？

TabItem 的原理

在探讨后面的内容之前，我们先简单分析一下 TabControl 及 TabItem 的底层原理，或者说在切换 Tab 后，相应的 Content 是如何呈现出来的。

从实现上来看，TabControl 主要可以拆成两部分：

上方用于切换的页签头，也就是每个 TabItem 的 Header
下方用于承载当前页内容的内容展示区域

其中，页签头通常会全部生成出来，因为用户需要看到所有可以切换的标签；但内容展示区域在同一时刻通常只会显示当前选中的那一项。微软文档在 TabControl 的默认模板里明确给出了一个名为 PART_SelectedContentHost 的部件，它的类型是 ContentPresenter，并且通过 ContentSource="SelectedContent" 来展示当前选中项的内容。当选项卡切换时，这个属性会更新为当前活动 TabItem 的 Content。

所以当切换 Tab 后，并不是 TabItem 本身被加载到内容展示区域，而是它的 Content 被加载。TabItem 本身仍然是内容的拥有者，只是负责实际呈现的是内容区里的 ContentPresenter。

另外，如果应用了 MVVM 模式，那么通常还会跟视图模型打交道。如果 Content 没有单独显式设置 DataContext，它会继承 TabItem 的 DataContext。也就是说，切换时进入内容区的是 Content 这棵界面树，而它绑定时所使用的数据上下文，默认仍然往往来自对应的 TabItem。

TabItem 的 Loaded 事件

然后我们来看一看 TabItem 的 Loaded 是什么时候触发的。稍加尝试后，我们会轻易地发现，TabItem 的 Loaded 事件只会在第一次被加载到界面树时触发一次。不仅如此，它们的加载顺序还有一些规律可循：它们会按照顺序加载，并且第一个被呈现的 Tab 的 Loaded 事件会在其他 TabItem 之后触发。

例如有 A、B、C 三个 TabItem，A 是默认选中的，那么它们的 Loaded 事件触发顺序是 B、C、A。如果此时将 B 设为默认选中，那么顺序就是 A、C、B。

不过这通常没有什么好关注的，因为 TabItem 的 Loaded 事件只会在第一次加载时触发一次，之后即使切换 Tab，也不会再触发。而且我们基本上也不会在它的 Loaded 事件里做什么事情。

Content 的 Loaded 事件

当涉及到 TabItem.Content 时，问题就变得复杂了一些。首先我们尝试直接将 Content 声明在 TabItem 中，类似：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<TabControl>
 <TabItem Header="A">
 <StackPanel Loaded="Content_Loaded" Unloaded="Content_Unloaded">
 <TextBlock Text="Content A" Loaded="Content_Loaded" Unloaded="Content_Unloaded"/>
 </StackPanel>
 </TabItem>
 <TabItem Header="B">
 <StackPanel Loaded="Content_Loaded" Unloaded="Content_Unloaded">
 <TextBlock Text="Content B" Loaded="Content_Loaded" Unloaded="Content_Unloaded"/>
 </StackPanel>
 </TabItem>
 <TabItem Header="C">
 <StackPanel Loaded="Content_Loaded" Unloaded="Content_Unloaded">
 <TextBlock Text="Content C" Loaded="Content_Loaded" Unloaded="Content_Unloaded"/>
 </StackPanel>
 </TabItem>
</TabControl>

此时我们会观察到，TabItem 与 Content 是交替加载的，而 Content 又会先加载默认显示的页面的，然后再按顺序加载其他的。这就会产生一个很有意思的现象。还是以 A、B、C 三个页面举例子。我们如果默认显示 A，那么各控件的 Loaded 顺序将会是：

A 的 Content
B 的 TabItem
B 的 Content
C 的 TabItem
C 的 Content
A 的 TabItem

是不是感觉被绕晕了？其实只要把 Content 和 TabItem 分开看，就会看出规律：它们各自符合前面提到的规律，然后交替进行。感兴趣的话，也可以想象一下如果将 B 设为默认选中，那么顺序会是怎么样，然后可以写个小程序来验证一下。

答案

B 的 Content
A 的 TabItem
A 的 Content
C 的 TabItem
C 的 Content
B 的 TabItem

其实这个顺序并不是很重要（而且看起来就像是脑筋急转弯），真正重要的是：所有 Content 都会在刚一开始就被触发，即便它们并没有被显示出来。这恐怕并不符合我们的直觉，更不是我们期望的效果。我们通常期望的效果是，页面只有在被切换到时才会加载，而不是在一开始就全部加载。

Content 的 Unloaded 事件

幸运的是，Content 的 Unloaded 事件是符合我们预期的。它会在切换到其他 Tab 时触发，并且只会触发当前显示的页面的 Unloaded 事件。所以当切换页面时，比如从 A 切换到 B，我们会观察到：

A 的 Content 的 Unloaded 事件触发
B 的 Content 的 Loaded 事件触发

所以关于这一部分，就没有太多可以赘述的内容了。

如何解决 Loaded 事件被多次触发的问题

现在我们很容易发现一个问题：Content 的 Loaded 事件在一开始就会被触发，并且在切换 Tab 时也会再次触发，这就导致了一个问题：如果我们在 Loaded 事件里做一些初始化操作，那么这些操作可能会被执行多次，甚至在页面还没有显示出来时就已经执行了，这显然不是我们想要的效果。

为了解决这个问题，我们通常的做法是引入一个局部变量，用来标记当前页面是否已经被加载过。这样在 Loaded 事件里，我们就可以先检查这个标记，如果已经加载过，就不再执行初始化操作。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


private bool _isContentALoaded = false;

private void ContentLoaded(object sender, RoutedEventArgs e)
{
 if (_isContentALoaded) return;

 Initialize();

 _isContentALoaded = true;
}

如果是在视图模型中实现初始化的逻辑，也可以用相同的方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class TabViewModel
{
 private bool _isInitialized = false;

 public void Loaded()
 {
 if (_isInitialized) return;

 Initialize();

 _isInitialized = true;
 }
}

如果借助行为库，通常我们会这样实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<TabControl>
 <TabItem Header="A" DataContext="{Binding TabViewModel}">
 <Grid>
 <i:Interaction.Triggers>
 <i:EventTrigger EventName="Loaded">
 <i:InvokeCommandAction Command="{Binding LoadedCommand}" />
 </i:EventTrigger>
 </i:Interaction.Triggers>
 <TextBlock Text="Content A" />
 </Grid>
 </TabItem>
</TabControl>

如何解决 Loaded 事件在一开始就被触发的问题

现在我们来讨论另一个问题：Content 的 Loaded 事件在一开始就会被触发，这可能会导致一些不必要的初始化操作在页面还没有显示出来时就已经执行了。那么这个问题又该如何解决呢？

首先有一个方式，就是我们额外添加一个判断，即 Tab 只有在被选中，或者可见时，才会执行初始化操作。这样就可以避免在页面还没有显示出来时就执行初始化操作了。以判断是否可见为例，除了可以在 Loaded 事件里判断 IsVisible 属性外，还可以借助行为库的条件行为来实现。具体的实现方式如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<i:EventTrigger EventName="Loaded">
 <i:Interaction.Behaviors>
 <i:ConditionBehavior>
 <i:ConditionalExpression>
 <i:ComparisonCondition LeftOperand="{Binding RelativeSource={RelativeSource AncestorType=UserControl}, Path=IsVisible}" RightOperand="True" />
 </i:ConditionalExpression>
 </i:ConditionBehavior>
 </i:Interaction.Behaviors>
 <i:InvokeCommandAction Command="{Binding LoadedCommand}" />
</i:EventTrigger>

这个看起来很复杂的实现，其实就是在 Loaded 事件触发时，额外添加了一个条件。如果条件不满足，则不执行后面的 Action。这样就可以确保只有在页面可见时，才会执行初始化操作。

除此之外还有一种不太能想到的方式，就是借助 TabItem.ContentTemplate 来实现，也就是不借助 Content 属性。形如：

1
2
3
4
5
6
7
8
9


<TabControl>
 <TabItem Header="A">
 <TabItem.ContentTemplate>
 <DataTemplate>
 <TextBlock Text="Content A" />
 </DataTemplate>
 </TabItem.ContentTemplate>
 </TabItem>
</TabControl>

通过这样的方式，Content 的 Loaded 事件就不会在一开始就被触发了，而是只有在切换到该 Tab 时才会触发。这一方式的原理是，模板只是告诉控件如何生成界面元素，而并没有直接生成界面元素。只有在切换到该 Tab 时，控件才会根据模板生成界面元素，从而触发 Loaded 事件。

总结

TabControl 在切换页面时，真正进入和离开内容区的通常不是 TabItem 本身，而是当前选中项的 Content。也正因为如此，TabItem 自身的 Loaded 往往只在初次进入界面树时触发一次，而 Content 的 Loaded / Unloaded 则会随着切换被重复触发；如果是直接把内容内联写在 TabItem 里，甚至还可能在初始阶段就先触发。

所以在实际开发中，最好不要把 Loaded 直接等同于“用户第一次看到这个页面”。更稳妥的做法通常是：要么给初始化逻辑加上幂等保护，避免重复执行；要么结合选中状态、可见性，或者改用 ContentTemplate，让初始化发生在真正合适的时机。

如何正确使用 WPF 中 Application 的 MainWindow 及 ShutdownMode 属性

Tue, 26 May 2026 00:00:00 +0000

提起 MainWindow，很多人的第一反应都是在创建 WPF 项目后，默认生成的那个 MainWindow 类。但其实我们这次要讨论的，是 Application 类中的 MainWindow 属性，或者大家更熟悉的访问方式是 Application.Current.MainWindow。可能有些人还不太清楚，但实际上它也是有一点使用技巧的，尤其是在与 ShutDownMode 配合使用时。

单例模式

首先，这个 MainWindow 属性是一个单例模式的实现，所以我们可以在项目中的任何地方通过 Application.Current.MainWindow 来访问它。这个功能非常方便，尤其是在需要在多个地方访问主窗口的情况下，比如在视图模型中或者其他服务类中。我们可以直接通过 Application.Current.MainWindow 来获取主窗口的引用，而不需要想尽办法来获取或传递它的引用。这样的需求常见于需要在主界面展示消息、弹窗、导航等操作时。

不过这里有一个稍微需要注意的地方，就是虽然它与我们的 MainWindow 类同名，但它本身是一个 Window 类型的属性，所以我们在使用时需要进行类型转换，这样才能拿到我们定义的 MainWindow 类中的特定方法和属性，或者有名字的界面控件。

配合 ShutDownMode 使用

这部分才是我们今天讨论的重点。WPF 开发者在刚入门的时候，可能会理所当然地认为，MainWindow 就一定是 Application.Current.MainWindow 的实例，并且主窗口关闭了，程序就应该退出了，这是天经地义的。但实际上这个事情恐怕没这么简单。

为什么 MainWindow 属性通常就是 MainWindow？

一个简单的 WPF 程序中，我们通常可以在 App.xaml 中看到类似这样的代码：

1
2
3
4
5


<Application x:Class="WpfApp.App"
 ...
 StartupUri="MainWindow.xaml">
 ...
</Application>

这段代码的意思是，当应用程序启动时，自动创建一个 MainWindow 的实例，并将它设置为 Application.Current.MainWindow。所以在这种情况下，MainWindow 属性确实就是我们定义的 MainWindow 类的实例。

或者如果我们不希望 App 自动帮我们创建主窗口，比如我们希望在程序刚开始的时候读取配置，为 DI 容器注册服务，或者做一些其他的初始化工作，我们可能会删掉 App.xaml 中的 StartupUri，并在 App.xaml.cs 的 OnStartup 方法中手动创建主窗口：

1
2
3
4
5
6
7
8


protected override void OnStartup(StartupEventArgs e)
{
 base.OnStartup(e);

 // 这里我们手动创建 MainWindow 实例
 var mainWindow = new MainWindow();
 mainWindow.Show();
}

在这种情况下，我们同样可以通过 Application.Current.MainWindow 来访问这个主窗口，因为 WPF 默认会自动将第一个显示的窗口设置为 MainWindow 属性的值。

ShutdownMode 是什么？

ShutdownMode 是 Application 类中的一个属性，它决定了当应用程序应该退出的条件。它有三个选项：

OnLastWindowClose：当最后一个窗口关闭时，应用程序退出。这是默认值。
OnMainWindowClose：当主窗口关闭时，应用程序退出。
OnExplicitShutdown：只有当调用 Shutdown() 方法时，应用程序才会退出。

虽然它的默认值是 OnLastWindowClose，但实际上往往 OnMainWindowClose 更加符合我们的预期，因为我们通常希望当主窗口关闭时，整个应用程序就退出了，而不需要担心其他窗口是否还在。因此主窗口本身还常常承载着很多善后工作，例如在 Closed 事件中进行资源清理、保存数据和配置等操作。

如果我们在主窗口的 Closed 事件中再去额外调用 Application.Current.Shutdown() 来保证其他窗口也会被关闭，这显然是不高明的。所以更好的做法是，直接将 ShutdownMode 设置为 OnMainWindowClose，这样当主窗口关闭时，整个应用程序就会自动退出了。我们只需要在 App.xaml 或 App.xaml.cs 中显式设置即可。

Info

关于 Application.Current.Shutdown() 方法，还有一些值得提及的细节：

通过调用它来关闭所有窗口，正常情况下是可以触发每个窗口的 Closing 及 Closed 事件的。
如果窗口还订阅了 Closing 事件，那么即便里面有 e.Cancel = true 的代码逻辑，也不会阻止窗口的关闭。
如果在 Closing 事件中抛出了未经捕获的异常，可能会干扰事件链，导致 Closed 事件不被触发。

第一个窗口不是 `MainWindow` 该怎么办？

有时候，主窗口可能并不是第一个弹出的窗口。一个典型的例子是，我们在应用程序启动时，先弹出一个登录窗口，用户登录成功后才显示主窗口。在这种情况下，Application.Current.MainWindow 可能会指向登录窗口，而不是我们真正的主窗口。那么此时我们该如何使用 OnMainWindowClose 来确保主窗口关闭时应用程序退出呢？

一个并不十分优雅，但也足够应付这个问题的方案是，我们先设置 ShutdownMode 为 OnExplicitShutdown，然后在登录窗口关闭后，再将 ShutdownMode 设置为 OnMainWindowClose，并且在登录窗口关闭时手动将主窗口设置为 Application.Current.MainWindow。这样就能保证当主窗口关闭时，应用程序能够正确退出了。比如在 App.xaml.cs 中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


protected override void OnStartup(StartupEventArgs e)
{
 base.OnStartup(e);

 // 先设置 ShutdownMode 为 OnExplicitShutdown
 this.ShutdownMode = ShutdownMode.OnExplicitShutdown;

 // 显示登录窗口
 var loginWindow = new LoginWindow();
 var result = loginWindow.ShowDialog();

 if (result == true)
 {
 // 登录成功，创建主窗口
 var mainWindow = new MainWindow();
 mainWindow.Show();

 // 将主窗口设置为 MainWindow 属性
 this.MainWindow = mainWindow;

 // 设置 ShutdownMode 为 OnMainWindowClose
 this.ShutdownMode = ShutdownMode.OnMainWindowClose;
 }
 else
 {
 // 登录失败，直接退出应用程序
 this.Shutdown();
 }
}

这个方法不够优雅的地方在于，我们需要在登录窗口关闭后，手动设置 MainWindow 属性，并且多次切换 ShutdownMode 的值，从而让它们两个正确配合。

更优雅的方式

一个更优雅的方式为，我们可以先创建 MainWindow 的实例，并且赋值给 Application.Current.MainWindow，但不立即显示它。然后我们先显示登录窗口，等用户登录成功后，再显示主窗口。这样就能保证 MainWindow 属性始终指向我们真正的主窗口了，同时也不需要频繁切换 ShutdownMode 的值了。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


protected override void OnStartup(StartupEventArgs e)
{
 base.OnStartup(e);

 // 先创建 MainWindow 实例，但不显示
 this.MainWindow = new MainWindow();
 this.ShutdownMode = ShutdownMode.OnMainWindowClose;

 // 显示登录窗口（省略判断登录成功的逻辑）
 var loginWindow = new LoginWindow();
 loginWindow.ShowDialog();

 // 登录成功后显示主窗口
 this.MainWindow.Show();
}

但这时候肯定会有人会问：如果登录失败，那么 MainWindow 不就白创建了？尤其是如果 MainWindow 中包含巨量的初始化逻辑，会不会导致很大的开销，甚至让登录窗口都出现不流畅的情况？

如果你有这样的担忧，那么很有可能是因为你的 MainWindow 的实现方式并不合理，尤其是你将初始化逻辑直接放在了构造函数中。一般来说，我们应该将初始化逻辑放在 Loaded 事件中，或者通过一些惰性加载的方式来实现，这样就能避免在创建 MainWindow 实例时就进行大量的初始化工作了。

或者，如果我们的项目采用了 MVVM 模式，那么我们可以将初始化逻辑放在 MainViewModel 中，并在合适的时机（通常仍然是主窗口的 Loaded 事件）调用它。这样同样可以避免上面的担忧。具体的做法可以是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public partial class MainWindow : Window
{
 public MainWindow()
 {
 InitializeComponent();
 this.Loaded += MainWindow_Loaded;
 }

 private void MainWindow_Loaded(object sender, RoutedEventArgs e)
 {
 // 在这里进行初始化逻辑
 var viewModel = (MainViewModel)this.DataContext;
 viewModel.Initialize();
 }
}

或者如果你不想在 .xaml.cs 文件里面写太多逻辑，还可以用行为库：

1
2
3
4
5
6
7
8
9


<Window ...
 xmlns:i="http://schemas.microsoft.com/xaml/behaviors">
 <i:Interaction.Triggers>
 <i:EventTrigger EventName="Loaded">
 <i:InvokeCommandAction Command="{Binding InitializeCommand}" />
 </i:EventTrigger>
 </i:Interaction.Triggers>
 ...
</Window>

Tip

除了将视图模型中的 Initialize 方法包装为 ICommand 来调用，还可以使用行为库中的 CallMethodAction 来直接调用视图模型中的方法。不过不太推荐这样做，因为 ICommand，尤其是 CommunityToolkit MVVM 中的 AsyncRelayCommand，可以更好地处理异步操作、错误处理和命令状态管理等问题，而直接调用方法则需要我们自己来处理这些细节了。

总结

总的来说，Application.Current.MainWindow 是一个非常方便的属性，可以让我们在项目中的任何地方访问主窗口的实例。但我们需要注意它与 ShutDownMode 的配合使用，尤其是在一些特殊的场景下，比如登录窗口和主窗口的关系。通过合理地设置 ShutdownMode 和正确地初始化主窗口，我们就能确保当主窗口关闭时，整个应用程序能够正确退出了。

Jab：基于源生成器的编译时依赖注入容器

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

最近在研究 Avalonia 的一款名为 ShadUI 的主题库时，发现它的示例项目使用了 Jab 这款 DI 容器来注册各种服务。

源生成器诞生以来，越来越多曾经需要大量借助反射来实现的功能，都可以通过源生成器来实现，而无需再依赖反射。从 .NET 内置的 JSON 序列化和正则表达式，到 Mapperly 这款基于源生成器的映射库，他们每一个都跑分喜人。那么 Jab 会让我们失望吗？

基本用法

Jab 的使用非常简单。安装它的 NuGet 包，或者在 .csproj 中添加以下内容即可：

1
2
3


<ItemGroup>
 <PackageReference Include="Jab" Version="0.12.0" PrivateAssets="all" />
</ItemGroup>

Info

这里的 PrivateAssets="all" 是为了防止 Jab 被打包到最终的 NuGet 包中。这个包本身的作用是为基于源生成器来生成 ServiceProvider 以及注册各种服务的代码提供具体的实现。但是在生成后，我们直接使用这些生成出来的类即可，就不再需要 Jab 本身了。

然后就可以使用了。我们可以这样注册服务：

1
2
3


[ServiceProvider]
[Transient(typeof(IService), typeof(ServiceImpl))]
internal partial class MyServiceProvider { }

对于上面的代码，还有一点点“改进空间”：

1
2
3
4
5


[ServiceProvider]
// C# 11 为我们带来了泛型特性
[Transient<IService, ServiceImpl>]
// 在有了主构造函数之后，我们声明一个空的类现在可以把花括号给省掉
internal partial class MyServiceProvider;

注册好服务之后，直接实例化容器，然后调用 GetService<T>() 获取服务即可：

1
2


var provider = new MyServiceProvider();
IService service = provider.GetService<IService>();

Info

Jab 没有类似 Microsoft.Extensions.DependencyInjection 中 GetRequiredService<T>() 的方法，但这并不是缺失——Jab 的 GetService<T>() 返回的就是非空的 T 而非可空的 T?。如果你请求了一个未注册的服务，编译器会在编译期直接报错，而不是等到运行时才抛出异常。这正是编译时 DI 的核心优势之一。

特殊用法

它的使用总体上来说是非常直观且符合直觉的。这里我再简单列举一些写法上稍微复杂一点的典型场景供大家快速参考。更多边界场景推荐直接阅读源代码仓库的 README。

将某个对象作为单例服务的实例

有时候，某个服务的实例需要通过特定的构建过程来创建，而不能简单地交给 DI 容器来实例化。典型的例子是 Serilog 的 ILogger——它通常需要通过 LoggerConfiguration 来配置和构建：

1
2
3
4


ILogger logger = new LoggerConfiguration()
 .WriteTo.Console()
 .WriteTo.File("logs/app.log", rollingInterval: RollingInterval.Day)
 .CreateLogger();

对于这种情况，Jab 提供了工厂方法的注册方式，让我们可以将这个已经构建好的实例作为单例注入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[ServiceProvider]
[Singleton<ILogger>(Factory = nameof(CreateLogger))]
internal partial class MyServiceProvider
{
 private ILogger CreateLogger() =>
 new LoggerConfiguration()
 .WriteTo.Console()
 .WriteTo.File("logs/app.log", rollingInterval: RollingInterval.Day)
 .CreateLogger();
}

这样，每次从容器中请求 ILogger 时，都会返回同一个由工厂方法创建的实例。

如果 logger 实例已经在容器外部创建好了，也可以直接通过实例属性的方式注册：

1
2
3
4
5
6


[ServiceProvider]
[Singleton<ILogger>(Instance = nameof(LoggerInstance))]
internal partial class MyServiceProvider
{
 public ILogger LoggerInstance { get; set; }
}

使用时，在容器创建后再将实例赋给该属性：

1
2
3
4
5
6
7
8


ILogger logger = new LoggerConfiguration()
 .WriteTo.Console()
 .CreateLogger();

var provider = new MyServiceProvider();
provider.LoggerInstance = logger;

ILogger resolved = provider.GetService<ILogger>();

命名服务

当同一个接口有多个不同的实现需要同时注册时，可以通过 Name 属性为每个注册取一个名字，然后在构造函数参数上用 [FromNamedServices("...")] 来指定要注入哪一个：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[ServiceProvider]
[Singleton<INotificationService, EmailNotificationService>(Name = "email")]
[Singleton<INotificationService, SmsNotificationService>(Name = "sms")]
[Singleton<Notifier>]
internal partial class MyServiceProvider;

class Notifier
{
 public Notifier(
 [FromNamedServices("email")] INotificationService email,
 [FromNamedServices("sms")] INotificationService sms)
 { }
}

Info

Jab 同样支持 Microsoft.Extensions.DependencyInjection 中的 [FromKeyedServices] 特性，两者可以互换使用。

模块

如果你用过 Autofac，对它的 Module 机制一定不陌生。模块可以将一组相关的服务注册封装成一个独立单元，然后在不同的容器中复用，这样可以实现批量注册一些相关的服务的效果，从而更好地管理服务。Jab 也提供了类似的能力，同样叫做 Module。

定义模块时，创建一个接口并标注 [ServiceProviderModule]，然后在接口上声明服务注册：

1
2
3


[ServiceProviderModule]
[Singleton<IService, ServiceImplementation>]
public interface IMyModule;

在服务容器中用 [Import] 引入模块即可：

1
2
3


[ServiceProvider]
[Import<IMyModule>]
internal partial class MyServiceProvider;

模块之间也可以互相引入，便于将大型应用的注册拆分成多个职责清晰的模块来管理。

Info

Microsoft.Extensions.DependencyInjection 本身没有 Module 的概念，通常的做法是为 IServiceCollection 编写扩展方法（如 AddMyFeature(this IServiceCollection services)）来实现类似的分组注册。Jab 将这一能力内置进来，写法上更加统一。

局限性

Jab 虽然在性能和编译期安全性上表现亮眼，但在实际项目中引入之前，有几点局限性值得考量：

生态兼容性：绝大多数第三方库（如 EF Core、Serilog、MediatR 等）都只针对 MEDI 提供 IServiceCollection 扩展方法，无法直接用于 Jab，需要手动桥接或改用工厂方式注册。
没有 ServiceCollection：Jab 没有运行时动态添加注册的能力，所有注册必须在编译期通过特性声明。这也导致所有针对 IServiceCollection 的扩展方法及中间件（如 Scrutor 的扫描注册）均无法使用。
缺乏 Host 生态支持：Microsoft.Extensions.Hosting 体系中的 IConfiguration、IOptions<T>、DbContext 等基础设施与 Jab 并无原生集成，若项目依赖这些能力，引入成本会较高。
不适合动态插件系统：插件通常需要在运行时发现并注册服务，而 Jab 的注册完全发生在编译期，无法支持这类场景。
特性数量随项目增长：服务全部通过特性在容器类上声明，项目规模较大时，容器类顶部可能会堆积大量特性，可读性有所下降。不过借助 Module 可以在一定程度上缓解这个问题。

总结

Jab 是一个思路清晰的编译时 DI 容器。如果你的项目对启动性能敏感（如桌面应用、命令行工具、AOT 场景），或者希望在编译期就捕获依赖配置错误，Jab 是一个值得尝试的选择。

但如果项目重度依赖 MEDI 生态（EF Core、ASP.NET Core 中间件、Generic Host 等），或者需要运行时动态注册，那么 Jab 并不适合作为主容器，继续使用 MEDI 会是更务实的选择。

在 C# 15 的 Union 类型到来之前我们都是怎么过的？

Sat, 09 May 2026 00:00:00 +0000

截止到目前，.NET 11 已经出了三个预览版了，并且也为我们带来了万众期待的 Union 类型。关于这个类型，有不少大佬已经讨论过了，这里贴两个供大家参考：

所以这里我们就不赘述关于 Union 类型的语法、作用、底层原理之类的内容了。我们这次要聊一聊的是，在 Union 类型到来之前，我们都是怎么过的，或者说我们面临的问题都是如何解决的。通过对以往方式的讨论，我们或许会更加意识到 Union 类型有多么棒。

Union 类型的核心目标

在回顾旧方案之前，我们先明确一下 Union 类型想要解决的核心问题：

归类某些类型，但是不必共享行为：我们希望把几种相关的类型归为一组，但它们之间不需要有继承关系或共同的接口实现。
在编译时能够穷尽各种情况：当我们对一个联合类型的值进行处理时，编译器能够检查我们是否覆盖了所有可能的情况。
减少心智负担和运行时错误：类型系统应该在编译期就帮我们排除掉"忘记处理某种情况"的隐患。
锦上添花，最好还能减少装箱的开销。

带着这些目标，我们来看看过去 C# 开发者们是怎么做的。

枚举类型 enum

在了解 Union 类型时，我们常常会看到诸如返回不同状态的代码，比如：

1
2
3


public union Result(Success, Error);

public Result GetResult() { /* 最终返回 Result 中的某种具体类型的实例 */ }

在没有 Union 类型的时候，很多人第一反应就是使用枚举：

1
2
3
4
5
6
7


public enum Status
{
 Success,
 Failed
}

public Status GetResult() { /* ... */ }

枚举类型本质上是值类型，只能包含单个分类，不能包含更多的内部信息。如果 Success 需要携带返回数据，Failed 需要携带错误信息，枚举就无能为力了。你不得不额外定义配套的字段或类来传递这些信息，导致数据和状态分离，增加了维护成本。

包含多个属性的类

既然枚举无法携带数据，很自然的想法就是定义一个"大而全"的类，把所有可能用到的属性都放进去：

1
2
3
4
5
6


class Result<T>
{
 public T? Data { get; set; }
 public Exception? Error { get; set; }
 public bool IsSuccess => Error is null;
}

这样的类型无法限制类成员之间的关系，只能依靠人为的约束和尽可能多的防御性编程。

比如上面这个例子，可能会出现 Data 和 Error 同时存在的情况，导致 IsSuccess 不可靠。如果成员变多，会更加不可控，势必会出现更多人为的检查：

1
2
3
4
5
6
7


var result = GetResult();
if (result.IsSuccess)
{
 // 编译器无法保证 result.Data 不为 null
 // 我们只能祈祷调用方遵守约定
 Console.WriteLine(result.Data!.ToString());
}

类型系统在这里完全帮不上忙，正确性全靠程序员的自觉和代码审查。

object 类型

将变量声明为 object 类型确实可以一定程度上实现表示多种类型的能力，并且借助模式匹配及 switch 语法可以实现灵活的功能：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


object result = GetSomething();

switch (result)
{
 case int i:
 Console.WriteLine($"Integer: {i}");
 break;
 case string s:
 Console.WriteLine($"String: {s}");
 break;
 default:
 throw new NotSupportedException();
}

但有几个明显的问题：

编译时无法得知变量类型，缺乏代码提示：object 可以表示任何东西，IDE 无法给出有意义的智能提示。
难以涵盖所有情况：编译器不会检查你是否处理了所有可能的类型，必须手动提供兜底方案（default 分支）。
可能存在装箱拆箱的开销：值类型赋值给 object 时会发生装箱，带来额外的性能开销。
类型安全性差：任何类型都可以赋值进去，运行时出错的风险很高。

空的抽象基类或接口

比 object 类型稍微好一点的做法是定义一个空的抽象基类或接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public abstract class Result { }

public class Success<T> : Result
{
 public T Data { get; }
 public Success(T data) => Data = data;
}

public class Error : Result
{
 public string Message { get; }
 public Error(string message) => Message = message;
}

这样可以一定程度上限制可能性，提高编译时期的严谨性，但仍然有几个问题：

必须保证所有类型都继承自该抽象类：对于内置类型（如 int、string）或者来自第三方库的类型，我们完全无能为力，无法把它们纳入这个联合体系。
仍然需要提供兜底方案：switch 表达式中编译器不知道有哪些派生类，所以 exhaustive check 无从谈起。
无法保证封闭性：其他开发者随时可以写出新的继承该抽象类的类型，而你无法阻止。这就破坏了"有限种可能"的语义。

OneOf 第三方库

在 C# 社区中，OneOf 是一个非常流行的用于模拟 Union 类型的库。它的基本用法如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


using OneOf;

public OneOf<User, NotFound, ValidationError> GetUser(int id)
{
 if (id <= 0)
 return new ValidationError("Invalid ID");
 
 var user = _db.FindUser(id);
 if (user is null)
 return new NotFound();
 
 return user;
}

// 使用
var result = GetUser(42);
result.Match(
 user => Console.WriteLine(user.Name),
 notFound => Console.WriteLine("User not found"),
 error => Console.WriteLine(error.Message)
);

这个库确实可以实现类型的联合，以及编译时的穷尽检查（通过 Match 方法要求你处理所有类型）。但存在一些弊端：

缺乏语言级别的语法糖

它不是语言特性，无法享受 C# 语法糖带来的便捷。你只能用它自己的 Match 等方法，不能用原生的 switch 语句、模式匹配等：

1
2
3
4
5
6
7
8


// 这是做不到的：
var result = GetUser(42);
var message = result switch // ❌ 编译错误
{
 User u => u.Name,
 NotFound _ => "Not found",
 ValidationError e => e.Message
};

代码繁杂

当联合的类型较多时，代码会显得繁杂。类型声明变成 OneOf<T1, T2, ..., Tn>，而 Match 语法中需要大量的 lambda 表达式：

1
2
3
4
5
6
7
8
9


OneOf<int, string, double, bool, DateTime> value = ...;

value.Match(
 i => HandleInt(i),
 s => HandleString(s),
 d => HandleDouble(d),
 b => HandleBool(b),
 dt => HandleDateTime(dt)
);

缺乏领域签名

OneOf<User, NotFound, ValidationError> 这样的类型虽然能表达联合，但缺乏语义上的清晰度。每次看到这个类型，你都需要在脑海中翻译一遍它的含义。

相比之下，union Result(User, NotFound, ValidationError) 这样的语法更直观，能够直接从类型定义中理解它的用途和意义。

OneOf<int, string> 则更是难以理解它的用途——它到底表示什么业务含义？无法从类型定义中推断出它的意义。

泛型参数顺序泄露到 API 设计里

OneOf<User, NotFound> 和 OneOf<NotFound, User> 是两个不同的类型，虽然它们表达的语义是一样的。这意味着如果你在一个地方用了 OneOf<A, B>，另一个地方用了 OneOf<B, A>，它们之间无法直接兼容，这会给 API 设计带来不必要的约束和混乱。

Union 类型的到来

现在，让我们看看 C# 15 的 Union 类型如何解决上述所有问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


public record class User(string Name);
public record class NotFound();
public record class ValidationError(string Message);

public union Result(User, NotFound, ValidationError);

public Result GetUser(int id)
{
 if (id <= 0)
 return new ValidationError("Invalid ID");
 
 var user = _db.FindUser(id);
 if (user is null)
 return new NotFound();
 
 return user; // 隐式转换
}

// 使用
var result = GetUser(42);

// ✅ 原生支持 switch 表达式和模式匹配
var message = result switch
{
 User u => $"Found: {u.Name}",
 NotFound _ => "User not found",
 ValidationError e => $"Error: {e.Message}"
 // 不需要兜底分支！编译器知道只有这三种可能
};

底层原理

本质上，Union 类型是编译器帮你生成的一个结构体，加上一个 object? 字段和隐式转换。当声明 union Pet(Cat, Dog, Bird) 时，实际上编译器后台会生成类似下面的代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[System.Runtime.CompilerServices.Union]
public struct Pet : System.Runtime.CompilerServices.IUnion
{
 // 为每个情况类型生成构造函数
 public Pet(Cat value) => Value = value;
 public Pet(Dog value) => Value = value;
 public Pet(Bird value) => Value = value;

 // 核心存储：单个 object? 字段
 public object? Value { get; }
}

核心组件是 IUnion 接口，以及 [Union] 特性：

1
2
3
4


public interface IUnion
{
 object? Value { get; }
}

编译器会借助隐式转换等方式，在后台实现相关逻辑：

1
2
3
4
5
6
7
8
9


Pet pet = new Dog("Rex");
// 实际上是 new Pet(new Dog("Rex"))

pet switch
{
 Dog d => d.Name, // 编译器检查：pet.Value is Dog d
 Cat c => c.Name,
 Bird b => b.Name,
};

Tip

如果你现在就想体验 Union 类型，可以下载 .NET 11 预览版 SDK。不过需要注意的是，早期预览版中 UnionAttribute 和 IUnion 尚未内置在运行时中，需要手动添加 Polyfill 代码。

总结

回顾过去，C# 开发者为了模拟 Union 类型的能力，尝试过枚举、“大而全"的类、object、抽象基类、第三方库等各种方案。但它们各自都有明显的缺陷：要么无法携带数据，要么缺乏类型安全，要么语法繁琐，要么语义不清晰。

C# 15 引入的原生 Union 类型，不仅提供了简洁优雅的语法，更重要的是它让类型系统能够在编译期就帮我们保证正确性——穷尽检查、隐式转换、原生模式匹配支持，这些都是过去任何方案都无法同时满足的。

Union 类型的到来，标志着 C# 在类型系统上又迈出了一大步。对于那些熟悉 F#、Rust 或 TypeScript 中联合类型的开发者来说，绝对算得上等来了自己的“福报”。期待 C# 在未来能继续引入更多强大的类型特性，让我们的代码更安全、更简洁、更易维护。

不要轻易使用大而全的扩展库

Thu, 05 Feb 2026 00:00:00 +0000

NuGet 上有很多大而全的 C# 扩展库。它们通常会为各种常用的类型提供相当多的扩展方法，从而辅助我们的开发。最常见的功能有：

字符串处理
集合处理
文件操作
序列化与反序列化
网络请求
日期时间处理

等等。但我的建议是，不要轻易使用这些大而全的扩展库。我们今天就来探讨一下这个问题。为了避免高级黑或者拉踩之类的嫌疑，这次我不会点名具体的库，但是会通过一些例子教大家如何判断一个库是否适合使用，以及该如何正确地学习和利用它们。

原因一：功能大多数用不上，而且污染基本类型

首先最重要的一个原因就是，这些扩展库往往会提供上百个扩展方法，但是我们实际用得到的通常只有 10 个以内。而为了用这几个功能，我们却不得不引入整个库，从而导致我们的项目变得臃肿。

更糟糕的是，这些扩展库因为充分扩展了常见的数据类型（比如 string、IEnumerable<T>、DateTime 等等），会导致代码补全时出现大量无关的扩展方法，影响开发效率。如果我们将这个库引入到团队项目中，那就更麻烦了，团队成员在编写代码时也会被这些无关的扩展方法干扰。

可能有人会说，这些扩展库都会将方法放在特定的命名空间下，我们只需要不引入这个命名空间就行了。理论上是这样没错，但实际上现在的 IDE 都相当智能。即便你没有引入命名空间，通常也会看到这些方法的提示，并且如果你不慎使用，IDE 还会自动帮你添加 using 语句，从而引入了整个扩展库。所以只要你的项目添加了这个扩展库，就很难避免污染。

原因二：扩展库可能引入不必要的依赖

有些扩展库为了充分向前兼容，往往会使用一些比较老旧的实现方式，甚至现在已经被标记为过时的 .NET 内置方法。比如为了实现序列化反序列化，它可能会引入 Newtonsoft.Json，而不是使用现在更推荐的 System.Text.Json，甚至有的可能还在使用 System.Runtime.Serialization.Json 命名空间下的老旧方法；又比如网络请求，它可能会使用 HttpWebRequest，而不是现在更推荐的 HttpClient。

这些都会导致我们的项目引入一些不必要的依赖，从而增加项目的复杂度和体积。

原因三：使用过时的标准库方法

这些扩展库可能因为要兼容更早版本的 .NET，或因为过于庞杂难以更新，往往会使用一些已经过时的标准库方法，从而影响我们的代码质量和性能。

案例一：哈希

我见过一些情形，比如计算 MD5，它虽然使用了 .NET 内置的 MD5 类，但却没有使用现在更推荐的方式：

1
2
3
4
5
6
7
8


// 过时的用法
using (var md5 = MD5.Create())
{
 var hash = md5.ComputeHash(data);
}

// 现代的用法
var hash = MD5.HashData(data);

这看起来可能没什么，但实际上这两种方式的性能差别还是很可观的。传统的 MD5.Create() 会在托管堆上创建一个加密算法实例，而 .NET 5 新增的 MD5.HashData 是静态方法，内部通常会复用或通过更底层（往往是无状态的）的方式直接调用操作系统或运行时的加密库。

不仅如此，HashData 提供支持 ReadOnlySpan<byte> 的重载。必要的情况下，我们可以将哈希值直接写入预先分配好的缓冲区（如 stackalloc 分配的栈内存），从而实现完全不分配堆内存。

简单跑一个分，可以看到新方法不仅效率高，而且几乎没有 GC 开销：

Method	Mean	Error	StdDev	Gen0	Gen1	Allocated
ComputeHash	335.7 ns	35.04 ns	1.92 ns	0.0172	0.0005	216 B
HashData	192.1 ns	11.67 ns	0.64 ns	0.0031	0.0002	40 B

因此，如果我们使用这些大而全的扩展库，可能会无意中引入一些过时的实现方式，影响我们的代码质量和性能。

案例二：字符串处理

字符串处理也是一个重灾区。因为在最近几年，Span 和 Memory 的引入，.NET 在字符串处理方面有了很大的改进。很多以前需要分配堆内存的操作，现在都可以通过 Span<char> 来实现零分配的高效处理。除此之外，现在的 .NET 底层还会利用 SIMD 指令集来加速字符串处理操作。

比如我见过有一个库提供了 ContainsAll 方法，用于检查一个字符串是否包含多个子串。这个方法的实现是这样的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public static bool ContainsAll(this string source, IEnumerable<string> values)
{
 foreach (var value in values)
 {
 if (source.IndexOf(value) < 0)
 {
 return false;
 }
 }
 return true;
}

这是一个在现在看来比较糟糕的实现。对于判断是否包含子字符串这样的需求，用 Contains 的效率是显著高于 IndexOf 的，因为 Contains 方法在底层已经做了很多优化，比如借助 Span，以及利用 SIMD 指令集来加速搜索过程。这里就不贴跑分了，我在自己的设备上测出了超过 40 倍的性能提升。

所以一个更加高效的实现方式可以是：

1
2
3
4


public static bool ContainsAll(this string source, IEnumerable<string> values)
{
 return values.All(value => source.Contains(value));
}

是的，LINQ 在最近几个版本的 .NET 中也迎来了相当多的更新。许多常用的方法现在都可以做到没有 GC 开销。但遗憾的是，这些新变化在那些扩展库诞生的年代可能还没有出现，所以它们的实现方式往往比较落后。

我的建议

虽然我上面提到了这些问题，而且我确实不建议（至少是在现在）使用这些大而全的扩展库，但我并不是说它们完全没有价值。我们可以用下面几种方式来充分利用或学习它们：

我们要面对的是很老的项目（例如 .NET Framework 4.x）。这种情况下，.NET 的后续很多优化和新的标准库方法都还没有出现，所以就更谈不上性能问题了。我们可以直接使用这些扩展库来提升开发效率，和弥补旧标准库缺失的一些功能。
我们可以学习和借鉴这些扩展库的设计思路和实现方式。虽然它们可能在性能上不够理想，但在功能设计和 API 设计上，还是有很多值得我们学习的地方的。
我们可以从这些扩展库中挑选出我们真正需要的功能，然后自己实现一个轻量级的版本，或者只是简单地复制粘贴到我们自己的项目中。这样既能满足我们的需求，又能避免引入不必要的依赖和性能问题。

总之，不要轻易使用大而全的扩展库，我们应该根据自己的实际需求来选择和使用这些库，同时也要注意它们可能带来的性能和依赖问题。

如何在本地客户端使用 EF Core

Mon, 02 Feb 2026 00:00:00 +0000

Entity Framework Core (EF Core) 是一个强大的对象关系映射（ORM）框架，通常用于服务器端应用程序中与数据库交互。通常我们会将它用于 ASP.NET Core 应用程序，并且它的配置方式也绝对可以说是相当成熟了。但有时候我们在做本地客户端应用程序（例如 WPF、WinForms 或 Avalonia 应用程序）时，也希望利用 EF Core 来简化数据访问层的开发。那么我们需要注意些什么？最佳实践是怎样的？这篇文章我们就来探讨这个问题。

回顾 EF Core 在 ASP.NET Core 中的使用

首先我们来快速回顾一下在 ASP.NET Core 应用程序中使用 EF Core 的典型方式。以一个比较新（.NET 6+）的项目为例，通常我们会在程序入口进行如下的配置：

1
2
3
4
5
6
7
8


var builder = WebApplication.CreateBuilder(args);

// 配置 DbContext
builder.Services.AddDbContext<AppDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

// 其他服务配置
// ...

这里其实有一个隐式的配置，就是我们将 DbContext 的生命周期设置为了作用域（Scoped）。在 ASP.NET Core 中，每个 HTTP 请求都会创建一个新的作用域，因此每个请求都会有一个独立的 DbContext 实例。这种方式有助于确保数据的一致性和隔离性。

这个方案在服务器端应用程序中可以说是非常标准且正确的，但是这个问题到了本地客户端，情况就不太相同了。对于客户端程序来说，通常并没有作用域这么一个概念。客户端程序一般是单用户的，整个应用程序的生命周期就是一个大的作用域。如果我们直接将 DbContext 注册为作用域生命周期，那么实际上它就会变成单例生命周期，这样就会带来一些问题：

线程安全问题：DbContext 不是线程安全的，如果在多线程环境下（例如 UI 线程和后台线程）共享同一个实例，可能会导致数据损坏或异常。
内存泄漏：长时间持有 DbContext 实例可能会导致内存泄漏，因为它会跟踪所有的实体状态，随着时间的推移，这些状态会不断累积。

因此，如何解决这两个问题就成了我们在客户端使用 EF Core 时需要重点考虑的内容。

方法一：注册为瞬态（Transient）生命周期

首先我们来看一种相对来说比较简单的方式。既然注册为作用域，实际上就相当于单例，那么我们可以直接将 DbContext 注册为瞬态生命周期。这样在每个被注入服务的类中，它都会获得一个新的 DbContext 实例，从而一定程度上避免了一些问题。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 注册 DbContext 服务
builder.Services.AddDbContext<AppDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")),
 ServiceLifetime.Transient);

// 使用 DbContext 的服务
public class MyViewModel
{
 private readonly AppDbContext _dbContext;

 public MyViewModel(AppDbContext dbContext)
 {
 _dbContext = dbContext;
 }

 public void LoadData()
 {
 var items = _dbContext.Items.ToList();
 // 处理数据
 }
}

Info

对于一个客户端程序，尤其是 MVVM 模式，一个典型的情况是我们将 DbContext 注入到 ViewModel 中使用。当然对于更复杂的场景，我们可能会将数据访问逻辑封装到一个 Repository 或 Service 层中，然后再将这些服务注入到 ViewModel 中。至于没有使用 MVVM 模式的情形，我们基本上也不会搞 DI 容器，所以也就不考虑这些问题了。

那么这有没有问题呢？答案是有的，而且这个方案并不理想。比如我们看下面这个例子。在这个例子中，我们使用了 CommunityToolkit.Mvvm 来简化 ViewModel 的编写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


public partial class MainViewModel : ViewModelBase
{
 private readonly AppDbContext _dbContext;

 [ObservableProperty]
 private ObservableCollection<Item> _loadedItems;

 public MainViewModel(AppDbContext dbContext)
 {
 _dbContext = dbContext;
 }
 
 [RelayCommand(AllowConcurrent = true)]
 private async Task LoadDataAsync()
 {
 var items = await _dbContext.Items.ToListAsync();
 LoadedItems = new(items);
 }
}

在这个例子中，我们将 DbContext 注入到了 MainViewModel 中，并且在 LoadDataAsync 方法中使用它来加载数据。这里其实就已经出现不少问题了：

MainViewModel 的实例通常生命周期非常长（可能与整个应用程序相同），而 DbContext 被注册为瞬态生命周期，这就意味着每次调用 LoadDataAsync 方法时，实际上都是在使用同一个 DbContext 实例。那这其实并没有比单例强多少，最多就是不用和其他服务共用同一个实例而已。长时间使用下去，DbContext 仍然会积累大量的状态，导致内存泄漏的问题。
这里我故意将 LoadDataAsync 方法设置为允许并发执行（AllowConcurrent = true）。这就意味着如果用户快速多次点击加载按钮，就会导致多个线程同时访问同一个 DbContext 实例，从而引发线程安全问题。

所以说，虽然将 DbContext 注册为瞬态生命周期在某些情况下可以工作，但它并不是一个理想的解决方案。除非我们能保证使用它的代码绝对不会并发执行，并且生命周期比较短（比如一个表单的视图模型），否则我们还是需要寻找更好的方法。

方法二：为服务注入作用域

既然上面的思路走不通，我们恐怕就不能简单地给视图模型直接注入 DbContext 了。为了解决上面的问题，我们应该让视图模型操作数据库的方法有机会每次都创建一个新的实例。顺着这个思路，我们可以让 DbContext 继续注册为作用域生命周期，然后为视图模型注入一个 IServiceScopeFactory，每次需要访问数据库时，就创建一个新的作用域，从而获得一个新的 DbContext 实例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public partial class MainViewModel : ViewModelBase
{
 private readonly IServiceScopeFactory _scopeFactory;

 [ObservableProperty]
 private ObservableCollection<Item> _loadedItems;

 public MainViewModel(IServiceScopeFactory scopeFactory)
 {
 _scopeFactory = scopeFactory;
 }
 
 [RelayCommand(AllowConcurrent = true)]
 private async Task LoadDataAsync()
 {
 using var scope = _scopeFactory.CreateScope();
 var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
 
 var items = await dbContext.Items.ToListAsync();
 LoadedItems = new(items);
 }
}

Info

这里我们为 scope 使用了 using 语句，这样就可以确保在方法执行完成后，作用域会被正确地释放，从而避免内存泄漏的问题；另一方面，我们没有为 dbContext 使用 using 语句，因为它是由 scope 管理的，而后者会在 using 块结束时自动释放它所创建的所有服务实例。

方法三：使用 `IDbContextFactory`

或者我们还可以更简单一些，我们直接将 DbContext 注册为瞬态生命周期，然后为视图模型注入一个 IDbContextFactory<AppDbContext>，每次需要访问数据库时，就通过工厂创建一个新的 DbContext 实例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public partial class MainViewModel : ViewModelBase
{
 private readonly IDbContextFactory<AppDbContext> _dbContextFactory;

 [ObservableProperty]
 private ObservableCollection<Item> _loadedItems;

 public MainViewModel(IDbContextFactory<AppDbContext> dbContextFactory)
 {
 _dbContextFactory = dbContextFactory;
 }
 
 [RelayCommand(AllowConcurrent = true)]
 private async Task LoadDataAsync()
 {
 using var dbContext = _dbContextFactory.CreateDbContext();
 
 var items = await dbContext.Items.ToListAsync();
 LoadedItems = new(items);
 }
}

如果使用这种方式，我们还要稍微修改一下服务的注册。这次我们就不用 AddDbContext 了，而是使用 AddDbContextFactory 来注册 DbContext 工厂：

1
2
3


// 注册 DbContext 工厂
builder.Services.AddDbContextFactory<AppDbContext>(options =>
 options.UseSqlServer(connectionString));

Info

使用工厂方法创建一个 DbContext 的实例就类似于我们手动使用 new 关键字创建一个对象一样。每次调用 CreateDbContext 方法时，都会返回一个新的 DbContext 实例，这样就可以避免线程安全和内存泄漏的问题。但因此我们也要手动处理它的生命周期，确保在使用完成后正确地释放它。所以上面我们对它使用了 using 语句。

总结

总的来说，在本地客户端应用程序中使用 EF Core 时，我们需要特别注意 DbContext 的生命周期以及线程安全。只要解决了这两个问题，我们就可以放心地在客户端程序中使用 EF Core 来简化数据访问层的开发。

如何在类外移除类的事件订阅？

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

某些时候，我们出于对第三方类库的定制需求，可能需要在类外移除该类的事件订阅。然而，事件本身就是一个封装良好的成员，直接访问和修改事件的订阅列表并不容易。不仅如此，为事件注册的方法可能还是私有的，这更是增加了难度。我们这次就来探讨如何通过反射机制实现这一目标。

简单情况

我们先来看一个最基本的例子。这里有一个 Demo 类，它定义了一个事件 MyEvent，并在构造函数中为该事件注册了一个事件处理器 MyEventHandler，并且也是这个类的私有方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class Demo
{

 public Demo()
 {
 MyEvent += MyEventHandler;
 }

 public event EventHandler? MyEvent;

 void MyEventHandler(object? sender, EventArgs e)
 {
 Console.WriteLine("MyEvent event triggered");
 }
}

在这个情况下，我们可以借助反射来拿到 MyEvent 事件的底层字段，然后将它置空，从而移除所有的事件订阅。

1
2
3


var demo = new Demo();
var eventField = typeof(Demo).GetField("MyEvent", BindingFlags.Instance | BindingFlags.NonPublic);
eventField.SetValue(demo, null);

这样一来，MyEvent 事件的所有订阅都被移除了。

事件声明在基类上

有时候，事件可能声明在类的基类上，比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class Base
{
 public event EventHandler? MyEvent;
}

class Demo : Base
{
 public Demo()
 {
 MyEvent += MyEventHandler;
 }

 void MyEventHandler(object? sender, EventArgs e)
 {
 Console.WriteLine("MyEvent event triggered");
 }
}

这时候上面的方法就不奏效了。我们需要在反射时指定正确的类型：

1
2


var eventField = typeof(Base).GetField("MyEvent", BindingFlags.Instance | BindingFlags.NonPublic);
eventField.SetValue(demo, null);

如果再复杂一点，我们甚至都不知道这个事件到底声明在哪个类上，这时候我们可以通过遍历继承链来查找：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Type? type = typeof(Demo);
FieldInfo? eventField = null;
while (type != null)
{
 eventField = type.GetField("MyEvent", BindingFlags.Instance | BindingFlags.NonPublic);
 if (eventField != null)
 {
 break;
 }
 type = type.BaseType;
}
eventField.SetValue(demo, null);

移除特定的事件处理方法

上面的方法都会移除所有的事件订阅。如果我们只想移除特定的方法怎么办？此时我们有两种方式。首先我们可以尝试获取事件的委托实例，然后从中移除特定的方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var eventField = typeof(Demo).GetField("MyEvent", BindingFlags.Instance | BindingFlags.NonPublic);
var eventDelegate = (MulticastDelegate?)eventField.GetValue(demo);
if (eventDelegate != null)
{
 foreach (var handler in eventDelegate.GetInvocationList())
 {
 if (handler.Method.Name == "MyEventHandler")
 {
 eventDelegate = (MulticastDelegate?)Delegate.Remove(eventDelegate, handler);
 }
 }
 eventField.SetValue(demo, eventDelegate);
}

Info

C# 中事件是基于委托实现的。每个事件在底层都有一个与之关联的委托字段，这个字段保存了所有注册到该事件的处理方法。当事件被触发时，实际上是调用这个委托，从而依次调用所有注册的方法。具体来说，这个委托通常是一个多播委托（Multicast Delegate），它上面有一个方法列表，包含了所有注册的事件处理器。

另一种方式是直接通过反射获取特定的方法，然后借助 Delegate 创造这个方法的委托实例，再从事件中移除：

1
2
3
4


var methodInfo = typeof(Demo).GetMethod("MyEventHandler", BindingFlags.Instance | BindingFlags.NonPublic);
var eventInfo = typeof(Demo).GetEvent("MyEvent", BindingFlags.Instance | BindingFlags.Public);
var handlerDelegate = Delegate.CreateDelegate(eventInfo.EventHandlerType, demo, methodInfo!);
eventInfo.RemoveEventHandler(demo, handlerDelegate);

通过以上方法，我们就可以在类外成功地移除类的事件订阅了。

整理为通用方法

最后，结合上面的方法，我们可以得到两个通用的方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


static void ClearEventHandler(object obj, string eventName, string handlerName)
{
 Type? type = obj.GetType();
 FieldInfo? eventField = null;
 while (type != null)
 {
 eventField = type.GetField(eventName, BindingFlags.Instance | BindingFlags.NonPublic);
 if (eventField != null) break;
 type = type.BaseType;
 }
 if (eventField is null)
 throw new InvalidOperationException($"Event field '{eventName}' not found.");
 var eventDelegate = eventField.GetValue(obj) as MulticastDelegate;
 if (eventDelegate != null)
 {
 foreach (var handler in eventDelegate.GetInvocationList())
 {
 if (handler.Method.Name == handlerName)
 eventDelegate = (MulticastDelegate?)Delegate.Remove(eventDelegate, handler);
 }
 }
 eventField.SetValue(obj, eventDelegate);
}

static void ClearAllEventHandlers(object obj, string eventName)
{
 Type? type = obj.GetType();
 FieldInfo? eventField = null;
 while (type != null)
 {
 eventField = type.GetField(eventName, BindingFlags.Instance | BindingFlags.NonPublic);
 if (eventField != null) break;
 type = type.BaseType;
 }
 if (eventField != null)
 {
 eventField.SetValue(obj, null);
 }
}

这两个方法分别用于移除特定的事件处理方法和移除所有的事件订阅。并且它们都能处理事件声明在任意基类上的情况。

如何在 C# 中获取本机真实 IP 地址？

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

获取本机 IP 地址听起来是一个非常简单的需求，但实际操作起来却并不容易。虚拟网卡、IPv6、APIPA 地址等因素会让我们获取到一大堆 IP，而如何从中筛选出真正想要的局域网 IP 才是我们要解决的问题。

常见的坑

1. 获取到一堆 IP 地址

最直接的想法可能是使用 Dns.GetHostAddresses 或 Dns.GetHostEntry 来获取本机所有的 IP 地址：

1
2
3
4
5
6
7


var hostName = Dns.GetHostName();
var ipAddresses = Dns.GetHostEntry(hostName).AddressList;

foreach (var ip in ipAddresses)
{
 Console.WriteLine(ip);
}

运行后你可能会看到类似这样的输出：

1
2
3
4
5
6
7


192.168.1.100
169.254.123.45
172.17.0.1
10.0.75.1
192.168.56.1
fe80::1234:5678:abcd:ef01%12
::1

这么多 IP 地址，到底哪个才是我们想要的真实局域网 IP？

2. 虚拟网卡的干扰

现代计算机上通常会存在多种类型的网络适配器：

物理网卡：真实的以太网卡或 Wi-Fi 适配器
虚拟网卡：
- VMware、VirtualBox、Hyper-V 等虚拟机软件创建的虚拟网卡
- Docker Desktop 创建的虚拟网卡（如 vEthernet）
- VPN 软件创建的虚拟适配器
- WSL2 创建的虚拟网卡
- 蓝牙适配器
- 回环地址（Loopback）

这些虚拟网卡都会有自己的 IP 地址，导致我们获取到一大堆无用的地址。

3. IPv4 vs IPv6

除了虚拟网卡的问题，还有 IPv4 和 IPv6 的区别：

IPv4：如 192.168.1.100（我们通常想要的）
IPv6：如 fe80::1234:5678:abcd:ef01%12（链路本地地址）
IPv6 本地回环：::1（相当于 IPv4 的 127.0.0.1）

在大多数局域网场景中，我们想要的是 IPv4 地址。

解决方案

方法一：使用 NetworkInterface 获取

这个方法通过 NetworkInterface 获取所有网络接口，过滤出正在运行的网卡，排除虚拟网卡，然后根据接口索引排序选择最佳 IP。下面的例子中排除了 VMware 虚拟网卡：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


static string? GetBestIPByMetric()
{
 var bestIp = NetworkInterface.GetAllNetworkInterfaces()
 .Where(n => n.OperationalStatus == OperationalStatus.Up)
 .Where(n => !n.Description.ToLower().Contains("vmware")) // 排除 VMware 虚拟网卡
 .SelectMany(n => n.GetIPProperties().UnicastAddresses
 .Where(a => a.Address.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork)
 .Select(a => new
 {
 IP = a.Address.ToString(),
 Description = n.Description,
 // 获取网卡的 IPv4 接口指标
 Metric = n.GetIPProperties().GetIPv4Properties()?.Index
 }))
 .OrderBy(x => x.Metric) // 索引通常反映了绑定顺序
 .FirstOrDefault();

 return bestIp?.IP;
}

这个方法的优点是精确可控，可以根据需求添加过滤条件，且不依赖路由表。缺点是需要手动维护虚拟网卡的排除列表，不同虚拟网卡的名称和描述可能不同。

Tip

接口索引（Index）通常反映了网卡的绑定顺序和优先级，索引越小优先级越高。通过 GetIPv4Properties().Index 可以获取这个值。

方法二：使用 Socket 连接外部地址

这是一个非常经典且巧妙的方法。通过创建一个 UDP Socket 并"连接"到外部地址（如 Google DNS 的 8.8.8.8），让操作系统根据路由表自动选择最合适的本地 IP。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


static string? GetLocalIp()
{
 using Socket socket = new Socket(AddressFamily.InterNetwork, SocketType.Dgram, 0);

 try
 {
 // 这里使用一个伪造的外部地址。
 // 即使断网，系统也会根据路由表返回最匹配的物理网卡 IP
 socket.Connect("8.8.8.8", 65530);
 var endPoint = socket.LocalEndPoint as IPEndPoint;
 return endPoint?.Address.ToString();
 }
 catch
 {
 // 如果没有任何网卡连接，会进入这里
 return "127.0.0.1";
 }
}

Tip

这里使用的是 UDP 协议（SocketType.Dgram），Connect 方法只是设置默认目标地址，不会真正发送数据包。因此即使断网也能正常工作，系统会根据路由表返回最匹配的本地 IP。

这个方法代码最简洁，能自动避开虚拟网卡。但如果局域网与外网完全隔离，路由表中没有相应路由时可能失效。

方法三：使用 WMI 查询物理网卡

这个方法利用 Windows Management Instrumentation (WMI) 来查询系统中标记为物理适配器的网卡，然后与 NetworkInterface 的 DeviceID 进行匹配，从而准确过滤出物理网卡的 IP。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


static void GetRealIP()
{
 // 使用 WMI 查询物理网卡
 var searcher = new ManagementObjectSearcher("SELECT * FROM Win32_NetworkAdapter WHERE PhysicalAdapter = True");
 var physicalIds = searcher.Get()
 .Cast<ManagementBaseObject>()
 .Select(x => x["DeviceID"].ToString())
 .ToList();
 var interfaces = NetworkInterface.GetAllNetworkInterfaces();
 foreach (var ni in interfaces)
 {
 // 匹配物理网卡 ID 并且状态为 Up
 if (physicalIds.Contains(ni.Id) && ni.OperationalStatus == OperationalStatus.Up)
 {
 var props = ni.GetIPProperties();
 var ipv4 = props.UnicastAddresses
 .FirstOrDefault(x => x.Address.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork);
 if (ipv4 != null)
 {
 // 排除掉 169.254.x.x (自动配置地址)
 if (ipv4.Address.ToString().StartsWith("169.254")) continue;
 Console.WriteLine($"网卡名称: {ni.Description}");
 Console.WriteLine($"真实局域网 IP: {ipv4.Address}");
 }
 }
 }
}

这个方法从准确性来说是最可靠的，能从操作系统底层识别物理网卡。但它有明显的局限性：

需要引用 System.Management NuGet 包
只能在 Windows 平台使用，不支持跨平台
WMI 查询相对较慢，性能敏感场景需要缓存结果

Tip

169.254.x.x 是 APIPA（Automatic Private IP Addressing）地址段，当 DHCP 服务器不可用时，Windows 会自动分配这个范围的地址。这通常不是我们想要的真实局域网地址。

方法四：NetworkInterface 评分机制（终极方案）

兜兜转转尝试了各种方法后，发现还是回到 NetworkInterface 最简单且有效。下面这个方案相当于方法一的增强版，通过更全面的过滤条件和评分机制来选择最佳 IP 地址：

排除更多种类的虚拟网卡（Clash、ZeroTier、Tailscale、WireGuard、VMware、Docker 等）
排除特殊 IP 段（Docker 的 172.16-31.x.x、网络基准测试的 198.18.x.x、APIPA 的 169.254.x.x）
使用评分系统综合评估：有网关 +100 分，以太网/无线网卡 +50 分，知名厂商（Intel、Realtek 等）+30 分

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


static string GetRealLocalIP()
{
 var allInterfaces = NetworkInterface.GetAllNetworkInterfaces();
 var candidates = new List<(IPAddress Ip, int Score)>();
 foreach (var ni in allInterfaces)
 {
 if (ni.OperationalStatus != OperationalStatus.Up) continue;
 if (ni.NetworkInterfaceType == NetworkInterfaceType.Loopback) continue;
 if (ni.NetworkInterfaceType == NetworkInterfaceType.Tunnel) continue;

 string desc = ni.Description.ToLower();
 string name = ni.Name.ToLower();
 if (desc.Contains("wintun") ||
 desc.Contains("clash") ||
 desc.Contains("virtual") ||
 desc.Contains("vmware") ||
 desc.Contains("vbox") ||
 desc.Contains("hyper-v") ||
 desc.Contains("zerotier") ||
 desc.Contains("tailscale") ||
 desc.Contains("wireguard") ||
 desc.Contains("docker") ||
 name.Contains("vethernet") ||
 name.Contains("wsl"))
 continue;

 var ipProps = ni.GetIPProperties();
 var ipv4Addrs = ipProps.UnicastAddresses
 .Where(a => a.Address.AddressFamily == AddressFamily.InterNetwork);

 foreach (var addr in ipv4Addrs)
 {
 string ipStr = addr.Address.ToString();
 if (ipStr.StartsWith("169.254")) continue;
 if (ipStr.StartsWith("198.18.")) continue;
 if (ipStr.StartsWith("172."))
 {
 var parts = ipStr.Split('.');
 if (parts.Length == 4 && int.TryParse(parts[1], out int secondOctet))
 {
 if (secondOctet >= 16 && secondOctet <= 31) continue;
 }
 }

 int score = 0;
 if (ipProps.GatewayAddresses.Any(g => !g.Address.ToString().Equals("0.0.0.0")))
 score += 100;
 if (ni.NetworkInterfaceType == NetworkInterfaceType.Ethernet ||
 ni.NetworkInterfaceType == NetworkInterfaceType.Wireless80211)
 score += 50;
 if (desc.Contains("intel") || desc.Contains("realtek") || desc.Contains("atheros") || desc.Contains("broadcom"))
 score += 30;

 candidates.Add((addr.Address, score));
 }
 }

 if (candidates.Count == 0)
 return "192.168.1.100";

 return candidates.OrderByDescending(c => c.Score).First().Ip.ToString();
}

这个版本覆盖了几乎所有常见场景，通过多维度评分确保选择的是真正在使用的物理网卡 IP。评分机制比简单的索引排序或依赖路由表更智能，能适应各种复杂网络环境。

Warning

虽然这个方法提供了最大的灵活性和准确性，但代码较长，维护成本相对较高。需要根据实际遇到的虚拟网卡类型持续更新过滤列表。

总结

获取本机真实 IP 地址看似简单，实则需要处理虚拟网卡、特殊 IP 段、多网卡等复杂情况。本文介绍了四种方法，各有优劣：

方法	优点	缺点	适用场景
方法一（基础 NetworkInterface）	可控性强，代码相对简单	需要手动维护排除列表	一般场景
方法二（Socket 连接）	代码最简洁，自动选择	完全隔离网络可能失效	快速实现
方法三（WMI 查询）	最准确，系统层面识别	仅限 Windows，性能较慢	Windows 专用
方法四（评分机制）	最灵活准确，覆盖全面	代码较长，维护成本高	复杂网络环境

大家可以根据自己的实际需求选择合适的方法，或者结合多种方法以获得最佳效果。

如何在不使用 .gitignore 的情况下忽略代码仓库中的文件或文件夹

Thu, 06 Nov 2025 00:00:00 +0000

我们在管理代码仓库时，有时候会在项目中引入一些额外的文件或文件夹，常见的比如我们想临时测试效果的 test 文件，或 .vscode、.idea、.github 等配置文件夹。这些文件或文件夹可能不适合被提交到版本控制系统中，但我们又不想使用 .gitignore 文件来忽略它们，因为这样我们就需要将 .gitignore 文件也提交到仓库中，影响其他协作者（或者让其他人察觉到你可能在本地仓库做了什么 :)

有一个笨方法，就是修改本地的 .gitignore 文件，但是不提交它。这样虽然可以达到忽略文件的目的，但拉取代码时，如果其他协作者更新了 .gitignore 文件，你的本地修改就会被覆盖，导致忽略设置失效。或者者你需要频繁地手动合并 .gitignore 文件，增加了维护成本。

那么，有没有一种方法可以在不使用 .gitignore 的情况下，忽略这些文件或文件夹呢？答案是肯定的。下面我们就简单介绍几种方式。

使用 `git update-index --assume-unchanged`

Git 提供了一个命令 git update-index --assume-unchanged <file>，可以让 Git 忽略对指定文件的更改。这样，即使你在本地修改了该文件，Git 也不会将其标记为已更改状态。

例如，如果你有一个名为 test.py 的文件，你可以运行以下命令：

1

git update-index --assume-unchanged test.py

然后就会发现，它不会出现在 git status 的输出中了。

如果你想恢复对该文件的跟踪，可以使用以下命令：

1

git update-index --no-assume-unchanged test.py

但是这个方法有一个缺点，就是它不能使用通配符来忽略多个文件或文件夹，你需要对每个文件单独执行该命令。

此外，假如这个文件已经被提交到了仓库中，并且其他协作者修改了它后被拉取到了本地，那么你可能无法察觉到这些更改。

使用 `.git/info/exclude`

另一个方法是使用 Git 仓库中的 .git/info/exclude 文件。这个文件的作用类似于 .gitignore，但它是本地的，不会被提交到远程仓库。而且它的语法规则是和 .gitignore 一样的，支持使用通配符。

你可以在 .git/info/exclude 文件中添加你想忽略的文件或文件夹路径。例如：

1
2
3
4
5


test.*
.vscode/
.idea/
.github/
[Pp]ublish/

这个方式就比较适合忽略多个文件或文件夹，而且不会影响其他协作者。

另外，.git 文件夹通常是隐藏的，并且在 VS Code 等编辑器中默认也是隐藏的。如果你需要编辑 .git/info/exclude 文件，可以在编辑器中打开隐藏文件夹，或者使用命令行编辑器进行修改。以 VS Code 为例，可以打开终端，进入项目根目录，然后运行以下命令：

1

code .git/info/exclude

这样就可以直接在 VS Code 中编辑该文件了。

分享一些针对 WPF 开发者的 Avalonia 开发技巧

Thu, 23 Oct 2025 00:00:00 +0000

Avalonia 在设计上借鉴了 WPF 的许多概念，开发体验来说也有很多相似之处。比如 XAML 语法、数据绑定、样式与模板等等，这使得 WPF 开发者能够较快上手 Avalonia。然而，Avalonia 也有其独特之处和最佳实践。如果对这些不够了解，WPF 开发者可能会将一些 WPF 的习惯直接套用到 Avalonia 上，导致代码不够高效或难以维护。

本文将分享一些针对 WPF 开发者在使用 Avalonia 时的实用建议，帮助大家更好地适应和利用 Avalonia 的特性，从而提升开发效率和应用性能。

布局控件的改良

子控件间距

Avalonia 为一些常用的布局控件提供了方便好用的属性。其中最方便的就是与 Spacing 相关的一些属性。在 WPF 中，如果想让控件之间有间距，通常需要使用 Margin 属性，导致代码看起来非常冗长：

1
2
3
4
5


<StackPanel Orientation="Horizontal">
 <Button Content="Button 1" Margin="0,0,10,0"/>
 <Button Content="Button 2" Margin="0,0,10,0"/>
 <Button Content="Button 3"/>
</StackPanel>

但是在 Avalonia 中，可以直接使用 Spacing 属性来设置控件之间的间距，使代码更加简洁：

1
2
3
4
5


<StackPanel Orientation="Horizontal" Spacing="10">
 <Button Content="Button 1"/>
 <Button Content="Button 2"/>
 <Button Content="Button 3"/>
</StackPanel>

除了 StackPanel，WrapPanel、Grid 和 UniformGrid 也支持 Spacing 属性。具体来说：

StackPanel：
- Spacing：设置子项之间的间距
WrapPanel：
- ItemSpacing：设置子项之间的间距
- LineSpacing：设置行之间的间距
- ItemsAlignment：设置整行（或列，取决于方向）的对齐方式
Grid 与 UniformGrid：
- RowSpacing：设置行之间的间距
- ColumnSpacing：设置列之间的间距

使用这些属性可以让布局代码更加简洁易读，避免了大量的 Margin 设置。

`Grid` 控件

在 Avalonia 中，Grid 也迎来了一些开发体验的优化。除了上面提到的 RowSpacing 和 ColumnSpacing 属性外，Grid 还支持 RowDefinitions 和 ColumnDefinitions 的简化语法。我们现在可以用字符串的形式来快速定义行和列：

1
2
3
4
5
6
7
8


<Grid ColumnDefinitions="Auto,*,100">
 <!-- WPF 的做法 -->
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 <RowDefinition Height="100"/>
 </Grid.RowDefinitions>
</Grid>

Tip

如果需要操作这些 Definition，比如在运行时动态调整它们的可见性、尺寸等，那我们仍然需要使用传统的方式来定义。

此外，如果我们的布局要求非常简单，比如并不会用到行与列，只是简单地将子控件堆叠在一起，最多是借助它们的 Alignment 属性来调整位置，那么我们可以使用更加轻量的 Panel 控件来替代 Grid，以提升性能。而 WPF 因为缺乏这样的轻量级容器，往往会过度使用 Grid，导致性能下降。也因此，不少第三方控件库提供了诸如 SimplePanel 之类的轻量级容器来弥补这一缺陷。

集合类型

在 WPF 中，我们都知道，如果想要让前台的 ItemsControl（及其子类，如 ListBox、ComboBox 等）能够响应集合的变化，我们需要使用 ObservableCollection<T> 作为数据源，因为它实现了 INotifyCollectionChanged 接口，能够在集合发生变化时通知 UI 更新。

而在 Avalonia 中，我们可以考虑使用它提供的 AvaloniaList<T> 作为集合类型。简单来说，AvaloniaList<T> 提供了以下几条额外的功能：

可以设置 ResetBehavior 属性来控制集合被清空时触发的是 NotifyCollectionChangedAction.Reset 还是 Remove：Reset 仅通知，但事件参数不包含具体删除了哪些元素，而 Remove 则会包含被删除的元素列表
提供了 Validate 方法，可以在添加元素时进行验证
提供了 AddRange 和 RemoveRange 方法，可以一次性添加或移除多个元素

这些新功能可以说是显著提升了 ObservableCollection<T> 的使用体验。

Avalonia 还提供了 AvaloniaDictionary<,>，它是一个具备通知功能的字典类型。WPF 因为缺乏类似 ObservableDictionary<,> 的类型，往往需要开发者自行实现，而 Avalonia 则直接提供了现成的解决方案供我们使用。

此外，对于 DataGrid 控件，Avalonia 还提供了 DataGridCollectionView，它是一个支持排序、过滤、分组等功能的集合视图类型，可以大大提高数据展示的灵活性。在 11.3.x 版本的 Avalonia 中，它被迁移到了 Avalonia.Controls.DataGrid 包中，方便我们单独引用。

值转换器

在 WPF 中，我们常常需要与值转换器（IValueConverter）打交道，以便在数据绑定时对数据进行转换。WPF 原生几乎只提供了一个我们用得上的转换器——BooleanToVisibilityConverter。其他的转换器通常需要我们自己实现。这同时也因为 WPF 的绑定语法不够灵活，导致连一个简单的布尔值取反都需要我们自己写转换器。

而在 Avalonia 中，情况则大不相同。甚至可以说，在遇到看似需要我们写值转换器的场景时，我们应该先考虑是否可以通过 Avalonia 提供的内置功能来实现，并且很多时候都是可以的。

内置转换器

Avalonia 提供了丰富的内置值转换器，涵盖了常见的转换需求。比如：

BoolConverters
- 提供了一些多值转换器（IMultiValueConverter），如 AndConverter、OrConverter 等，可用于 MultiBinding
- 提供了布尔值的取反转换器 NotConverter，但通常可以用绑定表达式的特殊语法来实现
StringConverters
- 提供了一些与字符串有关的转换器，如 IsNullOrEmpty、IsNullOrWhiteSpace 等
ObjectConverters
- 提供了一些与对象有关的转换器，如 IsNull、IsNotNull、Equal、NotEqual 等

运用这些内置的转换器，我们可以轻易实现很多常见的需求，比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<!-- 只有当所有开关都打开时，提交按钮才可用 -->
<ToggleSwitch x:Name="Toggle1" />
<ToggleSwitch x:Name="Toggle2" />
<ToggleSwitch x:Name="Toggle3" />
<Button Content="Submit">
 <Button.IsEnabled>
 <MultiBinding Converter="{x:Static BoolConverters.AndConverter}">
 <Binding ElementName="Toggle1" Path="IsChecked"/>
 <Binding ElementName="Toggle2" Path="IsChecked"/>
 <Binding ElementName="Toggle3" Path="IsChecked"/>
 </MultiBinding>
 </Button.IsEnabled>
</Button>

<ListBox x:Name="MyListBox" />
<TextBlock IsVisible="{Binding #MyListBox.SelectedItem, Converter={x:Static ObjectConverters.IsNotNull}}">
 An item is selected
</TextBlock>

绑定表达式

Avalonia 的绑定表达式语法也比 WPF 更加灵活强大。我们可以在绑定路径中直接使用一些特殊的语法来实现简单的转换需求，而无需借助值转换器。

比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 布尔值取反 -->
<ToggleSwitch x:Name="MyToggle" />
<TextBlock IsVisible="{Binding #MyToggle.IsChecked, Path=!}">
 The toggle is off
</TextBlock>

<!-- 字符串不为空 -->
<TextBox x:Name="MyTextBox" />
<TextBlock IsVisible="{Binding !!#MyTextBox.Text}">
 Text is not empty
</TextBlock>

通过这些内置的转换器和灵活的绑定表达式语法，我们可以大大减少自定义值转换器的编写，从而简化代码，提高开发效率。

函数值转换器

如果上面的这些方式还不能满足，那么或许依然不必急于去写值转换器。Avalonia 还提供了函数值转换器（FuncValueConverter），它允许我们快速地在后台代码中定义一个转换函数，并将其直接用于绑定中，而无需创建一个完整的转换器类。

1
2
3
4
5


public class MyViewModel
{
 public static FuncValueConverter<string, bool> StringToBoolConverter { get; }
 = new(str => !string.IsNullOrEmpty(str));
}

1
2
3
4


<TextBox x:Name="MyTextBox" />
<TextBlock IsVisible="{Binding #MyTextBox.Text, Converter={x:Static local:MyViewModel.StringToBoolConverter}}">
 Text is not empty
</TextBlock>

通过这种方式，我们可以快速地实现一些简单的转换逻辑，而无需编写冗长的转换器类，从而提高开发效率。如果希望传入参数（ConverterParameter），它还有一个 FuncValueConverter<TIn, TParam, TOut> 的重载版本，可以满足这一需求。此外，我们还有 FuncMultiValueConverter 可供使用，适用于多值绑定的场景。

但需要注意，这种方式存在一定局限性：它只支持正向转换（Convert 方法），不支持反向转换（ConvertBack 方法）。因此，如果需要更复杂的转换逻辑，仍然需要编写完整的值转换器类。

xmlns 命名空间

在 WPF 中，如果我们想要引入一个程序集中的控件或类型，通常需要在 XAML 文件的开头使用 xmlns 声明一个命名空间，并指定程序集名称：

1
2
3


<Window xmlns:md="http://materialdesigninxaml.net/winfx/xaml/themes"
 xmlns:local="clr-namespace:MyApp.Controls"
 xmlns:classlib="clr-namespace:ClassLibrary.Controls;assembly=ClassLibrary" />

如果在当前程序集，那么我们只需要 clr-namespace 即可；如果是其他程序集，则需要加上 assembly 部分。

这样的方式在 Avalonia 中同样适用，但 Avalonia 还提供了更加简洁的 using 语法，允许我们直接使用程序集名称来引入命名空间：

1
2
3


<Window xmlns:md="http://materialdesigninxaml.net/winfx/xaml/themes"
 xmlns:local="using:MyApp.Controls"
 xmlns:classlib="using:ClassLibrary.Controls" />

另外，Avalonia 的默认 x 命名空间也为我们提供了不少便利。在 WPF 中，如果我们想在 XAML 中使用一些常见的类型，比如 String、Int32、Boolean 等，通常需要显式地引入 System 命名空间：

1
2
3
4
5
6
7


<Window xmlns:sys="clr-namespace:System;assembly=mscorlib">
 <Window.Resources>
 <sys:String x:Key="MyString">Hello, World!</sys:String>
 <sys:Int32 x:Key="MyInt">42</sys:Int32>
 <sys:Boolean x:Key="MyBool">True</sys:Boolean>
 </Window.Resources>
</Window>

Tip

对于 .NET Framework 项目，我们必须引入 mscorlib 程序集；而对于 .NET 5+ 项目，我们还将多一些选择，比如：

System.Core
System.Runtime
netstandard

而在 Avalonia 中，我们可以直接使用 x 命名空间来引用这些常见类型，无需额外的 xmlns 声明：

1
2
3
4
5
6
7


<Window>
 <Window.Resources>
 <x:String x:Key="MyString">Hello, World!</x:String>
 <x:Int32 x:Key="MyInt">42</x:Int32>
 <x:Boolean x:Key="MyBool">True</x:Boolean>
 </Window.Resources>
</Window>

结语

本文介绍了一些针对 WPF 开发者在使用 Avalonia 时的实用建议。通过了解和运用这些 Avalonia 的特性和最佳实践，WPF 开发者可以更好地适应 Avalonia 的开发环境，从而提升开发效率和应用性能。

我们在使用 Avalonia 时，应该充分利用其提供的丰富功能和灵活语法，避免简单地将 WPF 的习惯直接套用到 Avalonia 上。希望本文的内容能够帮助大家更好地理解和使用 Avalonia，打造出高质量的跨平台应用程序。

在 C# 中使用 IComparer 实现自定义排序

Thu, 09 Oct 2025 00:00:00 +0000

在 C# 中处理数据时，我们有时候会想给某种数据一种特殊的排列顺序。比如对于公司员工排序时，我们希望按照员工所属的部门进行排序，并且希望按照一定的优先级，比如“行政、财务、人力资源、市场、销售、运营、研发”这样的顺序。这种情况下，如果我们使用默认的排序（即字典序），就无法满足我们的需求。

幸运的是，C# 提供了一个非常强大的接口 IComparer，它允许我们自定义排序逻辑。通过实现这个接口，我们可以定义任何我们想要的排序规则。

IComparer 接口的定义

IComparer<T> 接口定义了一个方法 Compare，它接受两个参数，并返回一个整数值。这个整数值的含义就是我们熟知的 CompareTo 方法的返回值：

-1：表示第一个参数小于第二个参数
0：表示两个参数相等
1：表示第一个参数大于第二个参数

所以，如果想要在使用各种常见排序方法（如 Array.Sort、List<T>.Sort 以及 LINQ 的 OrderBy 等）时使用自定义的排序逻辑，我们需要有一个实现了这个接口的类，并且将一个实例传给这些方法。

Tip

这个接口还有一个非泛型版本 IComparer，它的 Compare 方法接受两个 object 类型的参数。虽然非泛型版本在某些情况下可能会用到，但通常我们更倾向于使用泛型版本，因为它提供了类型安全性，并且也减少了很多我们在实现过程中可能遇到的类型转换问题。

一个简单的例子

以我们前面提到的员工排序为例，假设我们有一个 Employee 类：

1
2
3
4
5


public class Employee
{
 public string Name { get; set; }
 public string Department { get; set; }
}

我们可以创建一个 EmployeeComparer 类来实现 IComparer<Employee> 接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


class EmployeeComparer : IComparer<Employee>
{
 private static readonly List<string> DepartmentOrder = new List<string>
 {
 "行政", "财务", "人力资源", "市场", "销售", "运营", "研发"
 };

 public int Compare(Employee? x, Employee? y)
 {
 if (x is null || y is null)
 throw new ArgumentNullException();

 int xIndex = DepartmentOrder.IndexOf(x.Department);
 int yIndex = DepartmentOrder.IndexOf(y.Department);

 if (xIndex == -1) xIndex = int.MaxValue;
 if (yIndex == -1) yIndex = int.MaxValue;

 int deptComparison = xIndex.CompareTo(yIndex);
 if (deptComparison != 0)
 return deptComparison;

 return string.Compare(x.Name, y.Name, StringComparison.Ordinal);
 }
}

非泛型版本与上面类似，只是参数类型变成了 object，并且需要进行类型转换。这里不再赘述。

接下来，我们可以使用这个比较器来排序一个员工列表：

1
2
3
4
5
6
7
8
9


List<Employee> employees = await GetEmployeesAsync();
var comparer = new EmployeeComparer();
employees.Sort(comparer);

// 或者使用 LINQ
var sortedEmployees = employees
 .OrderBy(e => e, comparer)
 .ThenBy(e => e.Name)
 .ToList();

一个更通用的例子

如果在我们的项目中，时常会遇到这样的情形，也就是我们希望手动指定一种数据类型的排序方式。那么上面的方式可能就不够灵活了，因为我们需要为每一种数据类型都创建一个比较器类。

此时，我们可以写一个更加通用的比较器类 CustomComparer<T>，它接受一个排序规则列表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


sealed class CustomComparer<T> : IComparer<T>
{
 private readonly Dictionary<T, int> _customOrder;

 public CustomComparer(params T[] customOrder)
 {
 _customOrder = customOrder.Index().ToDictionary(x => x.Item, x => x.Index);
 }

 public int Compare(T? x, T? y)
 {
 if (x == null && y == null) return 0;
 if (x == null) return -1;
 if (y == null) return 1;

 var i = _customOrder[x];
 var j = _customOrder[y];
 return i.CompareTo(j);
 }
}

使用这个通用比较器，我们可以很方便地为任何类型指定排序规则：

1
2
3
4
5
6


var departments = new[] { "行政", "财务", "人力资源", "市场", "销售", "运营", "研发" };
var departmentComparer = new CustomComparer<string>(departments);
var sortedEmployees = employees
 .OrderBy(e => e.Department, departmentComparer)
 .ThenBy(e => e.Name)
 .ToList();

Tip

和前面的例子略有不同的是，这里我们只针对 string 这个类型定制了比较器。因此在使用时，我们需要指定 OrderBy 的第一个参数为 e => e.Department，而不是直接传入 e。而在前面的例子中，我们直接针对的比较对象就是 Employee 类型，然后我们在 Compare 方法中处理了 Department 属性。

通过实现 IComparer 接口，我们可以轻松地为任何数据类型定制排序逻辑。这不仅提升了代码的灵活性，也使得我们能够更好地控制数据的展示顺序，从而满足各种业务需求。

其他方式

除了使用 IComparer 接口，我们还有一些别的方法。比如 Sort、OrderBy 等方法允许我们传入一个 Comparison<T> 委托。它的声明如下：

1

public delegate int Comparison<in T>(T x, T y);

所以我们可以使用 lambda 表达式来定义排序逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


List<Employee> employees = GetEmployees();
Comparison<Employee> comparison = (x, y) =>
{
 var departmentOrder = new List<string> { "行政", "财务", "人力资源", "市场", "销售", "运营", "研发" };
 int xIndex = departmentOrder.IndexOf(x.Department);
 int yIndex = departmentOrder.IndexOf(y.Department);
 if (xIndex == -1) xIndex = int.MaxValue;
 if (yIndex == -1) yIndex = int.MaxValue;
 int deptComparison = xIndex.CompareTo(yIndex);
 if (deptComparison != 0)
 return deptComparison;
 return string.Compare(x.Name, y.Name, StringComparison.Ordinal);
};
employees.Sort(comparison);

另外，我们还可以直接修改类型本身，来实现 IComparable 接口，从而定义默认的排序逻辑。这种方法我们就不再做具体介绍了，因为它存在显著的局限性：每个类型只能有一种默认排序方式。如果我们将 Employee 类型的比较方式硬性定义为了“先部门，后姓名”的方式，那么此后如果我们想在使用 LINQ 时采用别的排序方式，就会变得非常麻烦。这种方式只适合非常简单的数据类型及场景，比如我们定义了一种包装类，它实际排序依靠的是内部的某个数值属性。

总结

通过实现 IComparer 接口，我们可以为任何数据类型定制排序逻辑，从而满足各种复杂的业务需求。无论是为特定类型创建专用的比较器，还是使用通用的比较器类，我们都能够灵活地控制数据的排序方式。此外，使用 Comparison<T> 委托也是一种简便的方法，适用于简单的排序需求。总之，掌握这些技术，可以让我们在处理数据时更加得心应手。

盘点 LINQ 在最近几个 .NET 版本中新增的功能和特性

Thu, 25 Sep 2025 00:00:00 +0000

LINQ 表达式相信每一位 C# 开发者都不陌生，LINQ 作为 C# 语言的核心功能之一，极大地简化了数据查询和操作的过程。随着 .NET 平台的不断发展，LINQ 也在不断地引入新的特性和改进，以提升开发者的生产力和代码的可读性。本文将介绍最近几个版本的 .NET 中新增的 LINQ 特性。

.NET 6

.NET 5 作为首次合并了 .NET Framework 和 .NET Core 的版本，标志着 .NET 生态系统的统一。这一版本并没有引入什么新的 LINQ 特性，但是在随后的第一个 LTS 版本 .NET 6 中，微软引入了很多新功能。

1. Chunk 方法

Chunk 方法允许开发者将一个序列分割成多个固定大小的块。这在处理大数据集时非常有用，可以帮助减少内存占用和提高性能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var numbers = Enumerable.Range(1, 10);
var chunks = numbers.Chunk(3);
foreach (var chunk in chunks)
{
 Console.WriteLine(string.Join(", ", chunk));
}
// 输出:
// 1, 2, 3
// 4, 5, 6
// 7, 8, 9
// 10

如果最后一块的元素数量不足指定大小，它将包含剩余的所有元素。

2. MinBy & MaxBy

在以前我们有 Min 和 Max 方法，用来获取序列中的最小值和最大值。这对于最传统的值类型，尤其是数字类型来说是非常易用且易懂的：

1
2
3


var numbers = new List<int> { 1, 2, 3, 4, 5 };
var min = numbers.Min(); // 1
var max = numbers.Max(); // 5

但如果我们面对的是一个较为复杂的对象，比如：

1
2
3
4
5


public class Person
{
 public string Name { get; set; }
 public int Age { get; set; }
}

现在我们想获取年龄最大的人，使用传统的方式就会比较繁琐且性能低下了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var people = new List<Person>
{
 new Person { Name = "Alice", Age = 30 },
 new Person { Name = "Bob", Age = 25 },
 new Person { Name = "Charlie", Age = 35 }
};

// 方法一
var oldestPerson = people.OrderByDescending(p => p.Age).First();

// 方法二
var oldestAge = people.Max(p => p.Age);
var oldestPerson = people.First(p => p.Age == oldestAge);

而在 .NET 6 中，我们可以直接使用 MaxBy 和 MinBy 方法来简化这个过程：

1
2


var oldestPerson = people.MaxBy(p => p.Age);
var youngestPerson = people.MinBy(p => p.Age);

3. DistinctBy 等

与上面的 MinBy 和 MaxBy 类似，DistinctBy 等方法也是允许我们基于某个属性来进行去重、交集和差集操作，并最终返回原始对象。比如下面的例子中，我们可以得到所有名字不重复的人：

1
2
3
4
5
6
7
8
9


var people = new List<Person>
{
 new Person { Name = "Alice", Age = 30 },
 new Person { Name = "Bob", Age = 25 },
 new Person { Name = "Charlie", Age = 35 },
 new Person { Name = "Alice", Age = 28 }
};

var distinctByName = people.DistinctBy(p => p.Name);

IntersectBy 和 ExceptBy 也是类似的用法。它们允许我们基于某个属性来进行交集和差集操作。具体的代码这里就不展示了，大家在用到的时候相信很快就能上手。

4. FirstOrDefault 等方法的重载

在这个版本中，FirstOrDefault、LastOrDefault、SingleOrDefault 这些方法允许传入一个自定义的默认值，而不是返回类型的默认值（例如 null 或 0）。这在某些情况下可以减少代码量，提高可读性。

1
2
3


var num = numbers.FirstOrDefault(n => n > 10, -1); // 如果没有找到符合条件的元素，返回 -1

var student = students.SingleOrDefault(s => s.Id == 1, new Student { Id = 0, Name = "Unknown" }); // 如果没有找到符合条件的元素，返回一个新的 Student 对象，而不是 null

这对于引用类型来说，或许可以借助 ?? 操作符来实现类似的功能；但对于值类型来说，这个重载就显得非常好用了。

5. Take

C# 8 引入了索引和范围的概念，这使得我们可以更方便地从集合中获取子集。比如：

1
2
3
4


var numbers = Enumerable.Range(1, 10).ToArray();
var firstThree = numbers[..3]; // 获取前3个元素
var lastThree = numbers[^3..]; // 获取后3个元素
var middleThree = numbers[3..6]; // 获取第4到第6个元素

现在，Take 方法也支持传入一个范围。这样我们就不需要再搭配使用 Skip 等方法了：

1
2
3
4
5
6


var numbers = Enumerable.Range(1, 10);

// 以前的做法
var middleThree = numbers.Skip(3).Take(3);
// 现在可以直接使用范围
var middleThree = numbers.Take(3..6);

6. Zip

对于 Zip 方法，现在多了一个重载，允许我们组合三个序列。或许在特定情况下，这一功能会派上用场。但奇怪的是，微软并没有提供更多的重载来支持更多的序列。

如果我们有组合更多序列的需求，可以考虑多次使用 Zip 方法来实现：

1
2
3
4
5
6


var numbers1 = new[] { 1, 2, 3 };
var numbers2 = new[] { 4, 5, 6 };
var numbers3 = new[] { 7, 8, 9 };
var zipped = numbers1
 .Zip(numbers2, (n1, n2) => (n1, n2))
 .Zip(numbers3, (pair, n3) => (pair.n1, pair.n2, n3));

.NET 7

这个版本虽然在方法上仅新增了两个，但 LINQ 在性能上得到了显著提升。微软对 LINQ 的实现进行了优化，减少了内存分配和提高了执行速度。

Order & OrderDescending

在 .NET 7 中，微软引入了 Order 和 OrderDescending 方法，这两个方法允许我们对序列进行排序，而不需要指定排序的键。它们会根据元素默认的比较器进行排序。

有了这个新方法，当我们不需要指定排序键时，代码会更加简洁，而且因为减少了委托的使用，也会略微减小一些性能开销：

1
2
3


var numbers = new List<int> { 3, 1, 4, 1, 5, 9 };
var sortedNumbers = numbers.OrderBy(x => x);
var sortedNumbers = numbers.Order();

不过这里仍然有必要强调一下，对于传统的集合类型，比如数组和 List<T>，我们如果有原地（in-place）排序的需求，还是应该使用它们自带的 Sort 方法，因为它们会直接修改原始集合。这种时候如果使用 LINQ 的 Order().ToArray() 等方法，反而会带来不必要的内存分配和性能开销：

1
2
3
4
5


var arr = new[] { 3, 1, 4, 1, 5, 9 };
var list = new List<int> { 3, 1, 4, 1, 5, 9 };

Array.Sort(arr); // 原地排序
list.Sort(); // 原地排序

.NET 8

这个版本并没有引入新的 LINQ 方法，但值得一提的是，Random 新引入了 Shuffle 方法，也就是洗牌算法。这个方法可以随机打乱一个序列的顺序：

1
2
3


var numbers = Enumerable.Range(1, 10);

var shuffledNumbers = Random.Shared.Shuffle(numbers);

.NET 9

Index

在 .NET 9 中，微软引入了 Index 方法。这个方法并不是类似 IndexOf，而是可以将一个序列包装为一些包含了 Index 和 Item 的元组（ValueTuple），方便我们在遍历时获取元素的索引。

1
2
3
4
5
6


IEnumerable<int> numbers = new[] { 10, 20, 30, 40, 50 };

foreach (var (index, item) in numbers.Index())
{
 Console.WriteLine($"Index: {index}, Item: {item}");
}

其实在以前，我们借助 Select 方法也可以实现类似的功能。Select 方法有一些重载，允许我们在选择元素的同时获取它们的索引：

1
2
3
4


foreach (var pair in numbers.Select((item, index) => (index, item)))
{
 Console.WriteLine($"Index: {pair.index}, Item: {pair.item}");
}

不过 Index 方法的语义会更加明确一些，也更加易用了。

CountBy

CountBy 方法允许我们根据某个键对序列进行分组，并计算每个组的元素数量。它返回一个包含键和值的元组序列。

比如我们有一个产品列表：

1
2
3
4
5


public class Product
{
 public string Name { get; set; }
 public string Category { get; set; }
}

我们可以使用 CountBy 方法来统计每个类别的产品数量：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var products = new List<Product>
{
 new Product { Name = "Apple", Category = "Fruit" },
 new Product { Name = "Banana", Category = "Fruit" },
 new Product { Name = "Carrot", Category = "Vegetable" },
 new Product { Name = "Broccoli", Category = "Vegetable" },
 new Product { Name = "Chicken", Category = "Meat" }
};

var categoryCounts = products.CountBy(p => p.Category);
// 结果:
// [("Fruit", 2), ("Vegetable", 2), ("Meat", 1)]

在以前，我们可以借助 GroupBy 方法来实现类似的功能：

1
2
3


var categoryCounts = products
 .GroupBy(p => p.Category)
 .Select(g => (Category: g.Key, Count: g.Count()));

AggregateBy

AggregateBy 方法允许我们根据某个键对序列进行分组，并对每个组应用一个聚合函数。它返回一个包含键和值的元组序列。

首先我们简单回顾一下 Aggregate 方法。这个方法允许我们对序列中的元素进行累积操作，比如计算总和、乘积等：

1
2
3


var numbers = new[] { 1, 2, 3, 4, 5 };
var sum = numbers.Aggregate((acc, n) => acc + n); // 15
var product = numbers.Aggregate((acc, n) => acc * n); // 120

现在，AggregateBy 方法允许我们先根据某个键对序列进行分组，然后对每个组应用一个聚合函数。比如我们有一些订单，我们想计算每个客户的订单总金额：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class Order
{
 public string Customer { get; set; }
 public decimal Amount { get; set; }
}

var results = orders.AggregateBy(
 order => order.Customer, // 分组键
 (acc, order) => acc + order.Amount, // 聚合函数
 0m // 初始值
);

Info

这个例子看似可以用 GroupBy 和 Select 来实现，但实际上 AggregateBy 的性能会更好一些，因为它避免了中间集合的创建。GroupBy 会创建一个中间的分组集合，而 AggregateBy 则直接在遍历时进行聚合操作。

关于 By 的思考

在 LINQ 中，名称带有 By 的方法有很多。这里的 By 虽然都表示要基于某个方式（比如属性、键等）来进行操作，但它们为方法带来的语义并不完全相同。一般来说分为两种情形：

基于某个键进行操作，并在最后返回对象本身（而不是这个键）
- MinBy、MaxBy、OrderBy、DistinctBy、IntersectBy、ExceptBy
基于某个键进行分组（再进行后续操作）
- GroupBy、CountBy、AggregateBy

因为两种不同的语义，某些方法其实是有可能引起误会的。比如 DintinctBy，到底应该是以某个键来去重，还是应该以某个键分组后再在每组中进行去重呢？

细心观察会发现，LINQ 并没有提供诸如 SumBy、AverageBy 等方法。因为这些方法首先没有什么必要，其次也会引起歧义。比如 SumBy，它是应该先分组再求和，还是直接对某个键求和呢？如果是前者，那它的语义就和 AggregateBy 很接近了；如果是后者，那它其实和传了一个 selector 的 Sum 一样。

那么 CountBy 又该怎么去理解呢？如果将 Count 理解为一种聚合操作，那么它其实和 AggregateBy 的语义是类似的。那么是不是说，对于一个聚合操作，它的 By 意思就是分组了呢？其实也未必，因为 Max 同样也可以看作是一种聚合操作，或者最起码我们确实可以用一个 Aggregate 来实现不是吗？所以这些方法的名称可能有点绕，需要大家在使用时多加注意。

总结

随着 .NET 平台的不断发展，LINQ 也在不断地引入新的特性和改进。这些新特性不仅提升了开发者的生产力，也使代码更加简洁和易读。希望本文能帮助大家更好地理解和使用这些新特性，提升开发效率。同时也鼓励大家，在有条件的情况下，尽量使用最新版本的 .NET，以便享受到这些改进和优化带来的好处。

C# 获取文件大小的几种方式及它们的性能比较

Sat, 06 Sep 2025 00:00:00 +0000

我们在操作文件时，经常需要获取文件的大小。相信大家都知道 FileInfo 类有一个 Length 属性可以获取文件大小，但实际上我们还有一些别的方式，并且其他方式可能比 FileInfo 有更好的性能。这篇文章我们就来盘点一下 C# 中获取文件大小的几种方式，并简单比较一下它们的性能。

使用 FileInfo.Length

这个是最常见的方式，FileInfo 类提供了一个 Length 属性，可以直接获取文件的大小，单位是字节（bytes）。

1
2
3
4


using System.IO;

FileInfo fileInfo = new FileInfo(filename);
long fileSize = fileInfo.Length;

这种方式的优点是代码简洁易懂，并且几乎适用于所有场景，包括跨平台开发。它唯一美中不足的地方在于，FileInfo 在使用前需要实例化，这会带来一点 GC 开销。

另外，如果觉得返回的 long 类型不够直观，我们也可以将其转换为更常见的单位，比如 KB、MB、GB 等。对于这个需求，除了自己写转换代码，我们还可以使用 Humanizer 这个库，它提供了非常方便的文件大小格式化功能。

1
2
3
4


using Humanizer;

FileInfo fileInfo = new FileInfo(filename);
string humanizedSize = fileInfo.Length.Bytes().Humanize("0.00"); // e.g. "1.23 MB"

使用 RandomAccess

RandomAccess 是一个在。NET 6 中引入的静态类，旨在提供高性能、线程安全的文件随机访问 I/O 操作。它提供的 GetLength 方法可以直接获取文件的大小。但稍微有些可惜的是，虽然它的 GetLength 方法是静态且不需要创建对象的，但它需要传入一个文件句柄（file handle），而后者是一个 SafeFileHandle 对象，这就不可避免地引入了 FileStream 对象的创建开销。

1
2
3
4


using System.IO;

using var handle = File.OpenHandle(filename, FileMode.Open, FileAccess.Read, FileShare.Read, FileOptions.RandomAccess);
long fileSize = RandomAccess.GetLength(handle);

那么实际上这个方式的效果怎么样呢？在后面的跑分环节会揭晓答案。

使用 P/Invoke 调用 Windows API

当程序运行的平台是 Windows 时，我们还可以通过 P/Invoke 调用 Windows API 来获取文件大小。这个方式的好处是它不需要创建任何托管对象，因此理论上它的性能应该是最好的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Runtime.InteropServices.ComTypes;

[DllImport("kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
static extern bool GetFileAttributesEx(
 string lpFileName,
 int fInfoLevelId,
 out WIN32_FILE_ATTRIBUTE_DATA lpFileInformation);

public static long GetFileSizeWin32(string path)
{
 if (!GetFileAttributesEx(path, 0, out var data))
 throw new System.ComponentModel.Win32Exception();

 return ((long)data.nFileSizeHigh << 32) + data.nFileSizeLow;
}

[StructLayout(LayoutKind.Sequential)]
struct WIN32_FILE_ATTRIBUTE_DATA
{
 public uint dwFileAttributes;
 public FILETIME ftCreationTime,
 ftLastAccessTime,
 ftLastWriteTime;
 public uint nFileSizeHigh, nFileSizeLow;
}

然后我们就可以使用上面的 GetFileSizeWin32 方法来获取文件大小了。

Info

如果是在 Linux 或 macOS 上运行的程序，那么虽然可以采用诸如引入 Mono.Posix 之类的库来调用系统 API，但这样做的复杂度和维护成本会比较高，所以推荐直接使用 FileInfo。

使用 VisualBasic.FileIO

最后这种方式可能有凑数的嫌疑，但是我们确实可以借助 Microsoft.VisualBasic 命名空间下的 FileSystem 类来获取文件大小。

1
2
3


using Microsoft.VisualBasic.FileIO;

long fileSize = FileSystem.FileLen(filename).Length;

性能比较

以上就是四种可行的获取文件大小的方式。接下来我们来比较一下它们的性能。结果如下：

Method	Mean	Error	StdDev	Allocated
UseFileInfo	7.888 μs	0.0522 μs	0.0462 μs	96 B
UseWin32Api	7.732 μs	0.0740 μs	0.0692 μs	-
UseFileSystem	15.779 μs	0.2104 μs	0.1968 μs	96 B
UseRandomAccess	10.627 μs	0.1137 μs	0.1063 μs	72 B

从结果中我们不难得出以下几个结论：

使用 Windows API 的方式性能最好，并且没有任何托管内存分配。但它只能在 Windows 平台使用。
使用 FileInfo 的方式性能也不错，适用于绝大多数场景。
使用 RandomAccess 的方式性能一般，虽然它不需要创建 FileInfo 对象，但它需要创建 FileStream 对象来获取文件句柄，这带来了无法避免的开销（虽然比 FileInfo 少了一点）。
使用 VisualBasic.FileIO 的方式性能最差，并且还会有内存分配，基本上没有任何优势。

总结

综上所述，几乎在任何情况下，我们都可以优先考虑使用 FileInfo.Length 来获取文件大小。只有在对于性能有极致要求，并且程序运行的平台确定是 Windows 的情况下，才考虑使用 P/Invoke 调用 Windows API 的方式。

原生 WPF 框架中体现出的设计模式

Mon, 11 Aug 2025 00:00:00 +0000

我们在做软件开发时，经常会使用设计模式，比如单例模式、工厂模式、观察者模式等。这些设计模式帮助我们更好地组织代码，提高代码的可维护性和可扩展性。

但是这次我们换一个角度，来看一看框架本身有没有体现出这些设计模式。希望这篇文章可以给大家一个不一样的视角。

观察者模式

对于观察者模式，相信大多数人可能首先会想到的是在 MVVM 模式下，ViewModel 作为数据的提供者，而 View 作为数据的消费者。当 ViewModel 中的数据发生变化时，它会通知所有绑定的 View 进行更新（具体做法为实现 INotifyPropertyChanged 接口，并触发相应的事件）。这种模式使得 View 和 ViewModel 之间的交互变得简单而高效。

但实际上，原生 WPF 就已经充分体现出了观察者模式。对于大多数控件，本身它就提供了两种实现了观察者模式，或者说可以被观察的特性：

事件：控件的事件机制允许开发者注册事件处理程序，从而在特定事件发生时接收通知。例如，当用户点击按钮时，按钮会触发 Click 事件；当用户修改文本框的内容时，文本框会触发 TextChanged 事件。
依赖属性：控件的依赖属性发生变化时，如果有绑定的目标，它会自动通知这些目标进行更新。这种机制使得控件的状态变化能够被及时“观察”到，从而实现了观察者模式的效果。

所以，在 WPF 开发中，观察者模式并不仅仅体现在 MVVM 模式上，它在控件的事件和依赖属性中也得到了充分的体现。

桥接模式

我们简单回顾一下桥接模式大概是怎么一回事：

如果我们的某一个类存在多个维度的变化（比如不同的外观和不同的行为），比如图形类可能有不同的形状（Shape）以及颜色（Color），那么假如我们采用传统的 OOP 的思想，就不可避免地会引入大量的子类，比如 RedRectangle、BlueCircle 等，这显然是不理想的。

此时，我们就可以使用桥接模式将这两个维度分离开来。这样一来，我们就可以独立地对这两个维度进行扩展，而不必相互影响。

这时候我们回来看 WPF，比如 Control 类就包含了多种不同的实现，包括 Button、Label、TextBox 等；同时，它们又都包含 Background、Foreground 等属性，用于控制它们实际的外观。这是否就和我们上面的例子不谋而合了？

所以，WPF 的 Control 类就是一个典型的桥接模式的实现。它将控件的外观（如样式、模板）和行为（如事件、命令）分离开来，使得我们可以独立地对这两个维度进行扩展。当然，体现桥接模式的不仅仅是 Control 类，其他很多控件也都遵循了这一模式。

装饰器模式

装饰器模式（Decorator Pattern）是一种结构性设计模式，它允许在不改变对象自身的情况下，动态地给对象添加一些额外的职责。装饰器模式通常用于遵循开闭原则（对扩展开放，对修改关闭）。

在 WPF 中，装饰器模式的一个典型应用就是附加属性和行为了。通过附加属性，我们可以在不修改原有控件的情况下，为其添加新的功能。例如，我们可以为一个 TextBox 控件添加一个附加属性，用于控制其是否显示占位符文本。

1

<TextBox local:TextBoxHelper.Placeholder="请输入内容" />

在这个例子中，TextBoxHelper 就是一个提供了附加属性的类，它可以为任意 TextBox 控件添加占位符文本（Placeholder）属性。然后我们就可以在 TextBox 的 Style 或 Template 中响应这个附加属性，从而真的为文本框添加占位符。

行为也类似，而且行为本质上也是附加属性，或者说就是依靠附加属性来实现的。所以这里不再赘述。

所以我们可以说，附加属性利用了装饰器模式。不仅如此，其实它还体现出了其他一些设计模式，比如我们开头提到的观察者模式，此外还有享元模式（附加属性与依赖属性为同一类型的控件提供了相同的属性元数据）、中介者模式（比如一些与布局相关的附加属性，如 DockPanel.Dock、Grid.Row 等）等等。

适配器模式

在 WPF 的绑定中，我们常常会利用到值转换器（ValueConverter），它就是适配器模式的典型体现。

这里我们看一个最典型的例子：我们要将一个布尔属性绑定到控件的 Visibility 属性上。为了能够实现源类型（bool）到目标类型（Visibility）的转换，最常见的方式就是借助 BooleanToVisibilityConverter 了：

1
2
3
4
5
6
7


<Window.Resources>
 <BooleanToVisibilityConverter x:Key="BooleanToVisibilityConverter" />
</Window.Resources>

<Grid>
 <TextBlock Text="Hello, World!" Visibility="{Binding IsTextVisible, Converter={StaticResource BooleanToVisibilityConverter}}" />
</Grid>

另外，值转换器不仅体现出了适配器模式，还体现出了一定程度的策略模式。它们把“如何将一个值转换成另一个值”的算法抽象成一个接口（IValueConverter），并通过不同的实现类来提供具体的转换逻辑，这正是策略模式的核心思想——把一系列可互换的算法封装为独立的策略对象，并在运行时根据需要选择使用哪一个策略。

责任链模式

前面我们提到，控件的事件体现出了观察者模式。其实不仅如此，WPF 在传统 C# 事件的基础上，还引入了路由事件（RoutedEvent）这一概念。

路由事件允许事件在控件的视觉树中沿着特定的路径进行传播，这种传播机制使得我们可以在父级控件中处理子级控件的事件，或者反过来。具体要看路由的方式是冒泡（Bubble）还是隧道（Tunnel）。

但不管哪一种方式，我们都可以在事件的处理过程中形成一个责任链。对于这一点，最明显的体现方式就是对于 e.Handled 的使用。比如我们触发了一个鼠标事件，并且希望在某个父级控件中处理这个事件，那么我们可以在到达该控件时将 e.Handled 设置为 true，从而阻止事件继续向上传播。

1
2
3
4
5
6
7
8


private void OnMouseDown(object sender, MouseButtonEventArgs e)
{
 if (sender is Border)
 {
 // 处理边框的鼠标按下事件
 e.Handled = true; // 阻止事件继续向上传播
 }
}

这一操作就和责任链模式不谋而合：我们可以将事件的处理过程看作是一个链条，每个处理节点都可以选择是否将事件继续传递下去，从而形成一个灵活的事件处理机制。

其他设计模式

除了上面这些典型的例子外，WPF 还体现出了很多其他的设计模式，比如：

状态模式：控件的视觉状态（如鼠标悬停、按下等）可以通过 VisualStateManager 进行管理，这实际上就是一种状态模式的应用。
组合模式：WPF 的控件树结构使得我们可以将多个控件组合成一个复合控件，这正是组合模式的体现。
单例模式：Application.Current 就是一个单例模式的实现。
原型模式：WPF 中资源的 Freezable 以及 Style 被多个控件使用，都体现出了对于原型实例的“克隆”。

总结

在软件开发中，设计模式为我们提供了高效、灵活的解决方案，帮助提升代码的可维护性和可扩展性。本文通过分析 WPF 中的几个经典设计模式，如观察者模式、桥接模式、装饰器模式、适配器模式和责任链模式，展示了这些模式如何在 WPF 框架中得以体现。

通过控件的事件机制、依赖属性、附加属性等机制，WPF 为开发者提供了丰富的设计模式支持，帮助开发者更好地组织和扩展应用程序。除此之外，WPF 还体现了状态模式、组合模式、单例模式等其他设计模式，为开发者提供了多种优秀的架构思想。

借助 ObservableCollections 获得更多具有通知功能的集合类型

Fri, 11 Jul 2025 00:00:00 +0000

如果大家在做基于 C# 的 WPF、Avalonia、Win UI 等开发，尤其是遵循 MVVM 模式时，遇到过下面的这些烦恼：

ObservableCollection 没有批量操作的功能（例如 AddRange）
缺少 ObservableDictionary、ObservableSet、ObservableQueue 等集合类型
难以实现诸如过滤、映射等功能

那么，ObservableCollections 这个 NuGet 包一定可以帮到你。没错，它就提供了一系列实用的具有通知功能的集合类型，使我们在 WPF、Avalonia、甚至 Unity 开发中都能够用得上。

安装

它的源代码链接在 GitHub 上。

如果想要安装它，我们只需要在 NuGet 包管理器中搜索 ObservableCollections，或者直接在项目中运行以下命令：

1

dotnet add package ObservableCollections

安装之后即可使用。注意它还有一个结尾包含 R3 的版本，是为它开发的 R3 库而准备的，通常我们不需要使用。这个 R3 库简单来说，就是一个更加高性能的 Rx.NET。

Info

说起它的开发者 Cysharp，那可真的可以说是如雷贯耳。比如他们开发的 Unitask，就是一个非常流行的适用于 Unity 的异步编程库；而他们开发的 ZLinq，最近也是非常有名。油管上的 Nick Chapsas 也曾经介绍过这个库。

支持批量操作的可观测集合

我们先来看一看它最简单的 ObservableList。它是一个具有通知功能的列表，并且支持批量操作。我们只需要实例化，然后就可以使用它了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


class MainViewModel
{
 private readonly ObservableList<string> _items = new();

 public MainViewModel()
 {
 // 添加单个元素
 _items.Add("Item 1");
 
 // 批量添加元素
 _items.AddRange(GetItems());
 }

 private IEnumerable<string> GetItems()
 {
 // 假定这个方法可以从某个数据源获取一些数据
 }
}

通过观察可以发现，这个集合类型提供了 CollectionChanged 事件，我们可以通过订阅它来监听集合的变化。但是先不要想当然地认为它和 ObservableCollection 一样。实际上，它的 CollectionChanged 事件并不是来自我们熟悉的那个 INotifyCollectionChanged 接口，而是这个库自带的一个接口。所以我们在上面的代码中，并没有直接将这个集合声明为 public 的属性，从而在 XAML 中绑定。

那么它为什么要这样做，让我们不能方便地使用呢？其实原因很简单：这个库不单单适用于 WPF，它还可以用于 Avalonia、Unity 等框架。为了兼容更多的框架，它就没有使用 INotifyCollectionChanged 接口，而是提供了一个更通用的接口。

但不必担心，它并没有止步于此，而是专门提供了方便我们在 WPF、Avalonia 等框架中使用的额外类型。简单来说，我们只需要调用它的下面这个方法，即可将它转为可以用于 XAML 绑定的集合对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class MainViewModel
{
 private readonly ObservableList<string> _items = new();

 public INotifyCollectionChangedSynchronizedViewList<string> Items { get; }

 public MainViewModel()
 {
 Items = _items.ToNotifyCollectionChanged();
 }
}

这里的 INotifyCollectionChangedSynchronizedViewList 就继承了 INotifyCollectionChanged 接口，因此实现了该接口的对象就可以直接在 XAML 中绑定使用，例如：

1

<ListBox ItemsSource="{Binding Items}" />

接下来，我们只需要在后台操作 _items 集合，它的变化即可同步到 Items 集合中，从而在 UI 上自动更新。

创建集合视图

实际上，对于 ObservableList，我们除了可以使用 ToNotifyCollectionChanged 方法将其转换为可以用于 XAML 绑定的集合类型外，还可以使用 ToNotifyCollectionChangedSlim 方法，将它转为一个更加轻量级的集合类型。这个类型同样实现了 INotifyCollectionChanged 接口，但它的性能更高，适用于需要频繁更新的场景。代价是，它将不提供 AddRange 等批量操作方法。

这时候可能有同学就会问了：我用 ObservableList 而不是原生的 ObservableCollection，不就是为了它提供的批量操作方法吗？如果我不需要批量操作，直接用 ObservableCollection 不就行了吗？

这就引出了我们即将介绍的下一个功能，同时也是这个库相当重要的功能：View。这个 View 不是我们常说的 MVVM 中的视图，而是指对集合的视图。它可以让我们在不改变原始集合的情况下，对集合进行过滤、映射等操作。我们不需要关注视图的实现细节，只需要操作后台的集合，即可将更改同步到界面中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


class MainViewModel
{
 private readonly ObservableList<string> _items = new();

 private readonly ISynchronizedView<string, string> _syncView;

 public INotifyCollectionChangedSynchronizedViewList<string> Items { get; }

 public MainViewModel()
 {
 _syncView = _items.CreateView(s => s.ToUpper());
 Items = _syncView.ToNotifyCollectionChanged();
 }

 public void ToggleFilter(bool useFilter)
 {
 if (useFilter)
 {
 _syncView.AttachFilter(s => s.StartsWith("A")); // 过滤以 "A" 开头的元素
 }
 else
 {
 _syncView.ResetFilter(); // 清除过滤器
 }
 }
}

Tip

如果我们只是想使用映射功能，那么使用 ToNotifyCollectionChanged 方法即可。它有一个重载，可以传入一个表示映射方式的 Func。另外，它还支持传入一个类似 Dispatcher 的参数，用于在 UI 线程上执行映射操作。至于为什么不是 WPF 中的 Dispatcher，而是一个它自己声明的类型，这也是为了兼容更多的框架。

在上面的代码中，我们创建了一个视图 _syncView。在创建时，我们就指定了一个映射函数，将集合中的每个元素转换为大写形式。然后在 ToggleFilter 方法中，我们可以通过 AttachFilter 及 ResetFilter 方法来添加或移除过滤器。就这样，我们轻松地实现了对集合的过滤和映射功能。

简单想象一下，这些功能在 WPF、Avalonia 等框架中原本实现起来会多么麻烦。对于映射，我们可以借助 DataTemplate 以及 ValueConverter 来实现；而对于过滤，我们可能需要使用 CollectionView 或者 ICollectionView 等。这些都需要我们编写大量的样板代码。

可观测的字典

WPF 中其实有一个 ObservableDictionary，但它并不是 public 的，只是标准库内部使用。或许我们可以使用一个 ObservableCollection<KeyValuePair<TKey, TValue>> 来模拟一个字典，但这效率并不高，因为字典的添加、删除、查找等操作都是 $O(1)$ 的，而 ObservableCollection 的这些操作都是 $O(n)$ 的。

至于 Avalonia，我们就比较幸运了，它直接提供了 AvaloniaList 和 AvaloniaDictionary，这两个集合类型，前者支持批量操作，后者则是一个可观测的字典。

下面我们用一个简单的例子来演示如何使用这个 ObservableDictionary。它的使用方式和 ObservableList 类似，我们只需要实例化它，然后就可以使用了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class MainViewModel
{
 private readonly ObservableDictionary<string, string> _items = new();

 public INotifyCollectionChangedSynchronizedViewList<string> Items { get; }

 public MainViewModel()
 {
 Items = _items.ToNotifyCollectionChanged(pair => pair.Value);

 _items.Add("Key1", "Value1");
 }
}

可观测的队列

队列有时候也是一个我们用得上的集合类型。它的特点是先进先出（FIFO），适用于需要按照顺序处理元素的场景。比如我们希望存储一些实时的消息，并且希望仅展示最新的几十条，而当超过这个数量时，自动删除最旧的消息。这就要求我们需要能够高效地删除队列头部的元素。这对于传统的列表来说是比较麻烦的，因为这会引入 $O(n)$ 的时间复杂度。

ObservableCollections 库提供了一个 ObservableQueue<T>，不过我不打算详细介绍它，因为我们上面提到的需求有一个更加合适的集合类型，等下就会介绍到。但这里我们还是用一个简单的例子来演示它的用法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


class MainViewModel
{
 private readonly ObservableQueue<LogMessage> _logQueue = new();

 public INotifyCollectionChangedSynchronizedViewList<LogMessage> LogMessages { get; }

 public MainViewModel()
 {
 LogMessages = _logQueue.ToNotifyCollectionChanged();

 // 添加日志消息
 AddLogMessage("Application started");
 }

 public void AddLogMessage(string content)
 {
 var logMessage = new LogMessage(DateTime.Now.ToString("o"), content);

 // 如果队列超过 100 条，则删除最旧的消息
 if (_logQueue.Count >= 100)
 {
 _logQueue.Dequeue();
 }
 _logQueue.Enqueue(logMessage); 
 }
}

record LogMessage(string Timestamp, string Content);

Tip

事实上，如果我们的需求只是比如说保留最近的几十到一百条消息，那么直接使用传统的 ObservableCollection 也是完全可以接受的。虽然有点性能损失，但对于现在的 CPU 来说，这点复杂度完全是微不足道的。通过简单的 Benchmark，我们可以看到，List 可能只比 Queue 慢 50% 左右；甚至当数据量比较小（例如十几条）时，List 更是能在性能上超过 Queue。另外，List 的使用显然比 Queue 简单了不少。

可观测的环形缓冲区

下面我们要介绍的这个集合类型，正是这个包最推荐我们用来实现这个保留最近的一些消息的集合类型：RingBuffer。它是一个环形缓冲区，具有固定的大小。当添加新元素时，如果缓冲区已满，则会覆盖最旧的元素。这使得它非常适合用于存储最近的消息或数据。

这个包提供了两种环形缓冲区：ObservableRingBuffer 和 ObservableFixedSizeRingBuffer。前者支持动态调整大小，而后者则是一个固定大小的环形缓冲区。借助后者，我们前面的例子可以简化为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class MainViewModel
{
 private readonly ObservableFixedSizeRingBuffer<LogMessage> _logBuffer = new(100);

 public INotifyCollectionChangedSynchronizedViewList<LogMessage> LogMessages { get; }

 public MainViewModel()
 {
 LogMessages = _logBuffer.ToNotifyCollectionChanged();

 // 添加日志消息
 AddLogMessage("Application started");
 }

 public void AddLogMessage(string content)
 {
 var logMessage = new LogMessage(DateTime.Now.ToString("o"), content);
 _logBuffer.Add(logMessage); // 添加新消息，自动覆盖最旧的消息
 }
}

就这样，我们轻松地实现了一个保留最近 100 条日志消息的集合。

线程安全

接下来这个部分相当重要，也是大家在使用这个包时需要尤其注意的，就是关于线程安全的问题。首先，这个包提供的每个集合都是线程安全的。它们内部会用一个线程锁，保证它的添加、删除等操作是线程安全的。但这并不意味着我们就可以高枕无忧了，因为虽然这些集合线程安全，但是从它们创建出的视图在同步它们的修改时，可能出现线程安全问题。那么，我们该怎么办呢？

首先，在使用 ToNotifyCollectionChanged 方法时，我们可以传入一个 Dispatcher 参数。前面提到，这个参数是该类库自己声明的类型。但是它提供了一个方便我们使用的单例：SynchronizationContextCollectionEventDispatcher.Current。借助它，我们就可以确保该方法创建出的视图在 UI 线程上执行修改操作，从而避免线程安全问题。

但是这还不够。实测发现，虽然背后的集合本身线程安全，但是它创建出来的视图在操作时仍面临着线程安全问题。尤其是数据不一致。比如我们在删除元素之后立刻添加了元素，那么这两次动作在同步到视图的过程中就可能会出现问题。对于这个问题，如果我们确实有在多线程上操作背后集合的需求，那么我们可以考虑让这些操作都发生在主线程上。以 WPF 为例，我们可以这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


class MainViewModel
{
 private readonly ObservableList<string> _items = new();

 public INotifyCollectionChangedSynchronizedViewList<string> Items { get; }

 public MainViewModel()
 {
 Items = _items.ToNotifyCollectionChanged(SynchronizationContextCollectionEventDispatcher.Current);
 }

 public void AddItem(string item)
 {
 // 确保在 UI 线程上执行添加操作
 Application.Current.Dispatcher.InvokeAsync(() => _items.Add(item));
 }

 public void RemoveItem(string item)
 {
 // 确保在 UI 线程上执行删除操作
 Application.Current.Dispatcher.InvokeAsync(() => _items.Remove(item));
 }
}

当然，在 ViewModel 中访问 Application.Current 可能并不是一个十分遵守 MVVM 模式的好习惯。因此在更加严谨的项目中，我们可以考虑将 Dispatcher 作为参数传入 ViewModel，或者使用依赖注入的方式来获取它。这样可以更好地遵循 MVVM 模式，同时也能确保在 UI 线程上执行操作。

总结

ObservableCollections 是一个非常实用的 NuGet 包，它提供了多种具有通知功能的集合类型，适用于 WPF、Avalonia、Win UI 等框架。它不仅支持批量操作，还提供了过滤、映射等功能，使得我们在开发中可以更加高效地处理集合数据。

在使用时，我们需要注意线程安全问题，尤其是在多线程环境下操作集合时。通过合理地使用 Dispatcher，我们可以确保集合的操作在 UI 线程上执行，从而避免数据不一致的问题。

.NET 原生有哪些 Timer 以及它们分别是怎么用的？

Mon, 07 Jul 2025 00:00:00 +0000

相信很多 .NET 新手（甚至有几年经验的老手）都会搞不清楚这个问题：.NET 原生有哪些计时器（Timer）？它们分别是做什么用的？该如何选择以及如何正确地使用？

这篇文章我们就来盘点一下吧。

一共有多少种 Timer？

首先我们来回答一下这个问题。在 .NET 源代码中搜索 Timer，我们可以找到答案。排除掉一些 internal 或 abstract 的类型（例如 System.Net.Timer、Microsoft.ML.Trainers.FastTree.Timer 等），我们可以找到以下几种计时器：

System.Threading.Timer
System.Timers.Timer
System.Threading.PeriodicTimer
System.Windows.Threading.DispatcherTimer
System.Windows.Forms.Timer
System.Web.UI.Timer
Windows.UI.Xaml.DispatcherTimer

这里，后面四个可以从命名空间看出，它们适用于特定的 UI 框架（即 WPF、WinForms、ASP.NET Forms、Win UI 等），而前面三个则是更通用的计时器，适用于大多数场景。这篇文章我们主要介绍前三个，并且在后四个中选择适用于 WPF 的 DispatcherTimer 进行介绍。

System.Threading.Timer

源代码：System.Threading.Timer.cs

System.Threading.Timer 是 .NET 中最常用也是最轻量的计时器之一。它是基于线程池的，所以不与某个特定线程（如 UI 线程）关联，并且也不会阻塞调用线程。

它没有提供诸如 Start 和 Stop 方法，而是通过设置回调函数和周期来启动（还可以通过 Change 方法来调整周期）。当不需要使用时，可以通过调用 Dispose 方法来结束它并释放资源。

下面是一个简单的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using System;
using System.Threading;

// 第三个参数是初始延迟时间，第四个参数是周期时间（单位都是毫秒）
// 这里的传参意味着，计时器将会没有初始延迟，且每隔 1 秒执行一次回调函数
var timer = new Timer(TimerCallback, null, 0, 1000);
Console.WriteLine("Timer started. Press Enter to exit...");
Console.ReadLine();

timer.Dispose();
Console.WriteLine("Timer stopped and disposed.");

void TimerCallback(object? state)
{
 Console.WriteLine($"Timer callback executed at {DateTime.Now}, thread id: {Environment.CurrentManagedThreadId}");
}

输出结果形如：

1
2
3
4
5
6


Timer started. Press Enter to exit...
Timer callback executed at 2025/7/6 19:27:27, thread id: 11
Timer callback executed at 2025/7/6 19:27:28, thread id: 9
Timer callback executed at 2025/7/6 19:27:29, thread id: 9
Timer callback executed at 2025/7/6 19:27:30, thread id: 9
Timer stopped and disposed.

我们不难发现几个现象：

计时器在创建后立刻就开始执行了，不需要调用类似 Start 的方法；
计时器没有阻塞创建它的线程，它类似于启动了一个后台服务；
计时器的回调函数是在不同的线程上执行的，而且每次执行的线程 ID 可能不同，这取决于线程池的调度；
计时器可以通过 Dispose 方法来停止及释放资源。

因为它的一些局限性，这在实际开发中可能会让我们遇到一些困难，比如我们无法灵活地控制它的开始与结束，以及暂停和重启等。另外，因为它每次的回调可能都发生在不同的线程上，所以我们需要特别注意线程安全问题，尤其是在访问共享资源，或者需要某些操作发生在特定线程（如 UI 线程）时。

关于这些问题，我们会在后续介绍的其他计时器中看到更好的解决方案。

System.Timers.Timer

源代码：System.Timers.Timer.cs

System.Timers.Timer 是一个更高级的计时器，它基于（或者可以理解为封装了） System.Threading.Timer，并提供了更多的功能和更易用的 API。比如它提供了开始、停止、关闭等功能，还提供了一些属性来控制计时器的行为，比如：

Interval：设置计时器的间隔时间（毫秒），不再需要使用 Change 方法了；
Enabled：设置计时器是否启用（Start 和 Stop 方法其实就是在控制它）；
AutoReset：设置计时器是否自动重置（即是否在回调函数执行完毕后立即重新开始计时，默认为 true）。或者换一种理解方式，有时候我们不希望计时器会每周期都触发一次，而是真的像一个简单的定时器那样，在开始后到达设定的周期就触发，然后停在那里，等待下一次启动。

下面是一个简单的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


using System;
using System.Timers;

var timer = new Timer(); // 创建一个计时器（默认的周期为 100 毫秒）
timer.Elapsed += TimerElapsedHandler; // 订阅 Elapsed 事件
timer.Interval = 1000; // 设置间隔为 1 秒

timer.Start();
Console.WriteLine("Timer started. Press Enter to exit...");
Console.ReadLine();

timer.Stop();
Console.WriteLine("Timer stopped and disposed.");

timer.Dispose();

void TimerElapsedHandler(object? sender, ElapsedEventArgs e)
{
 Console.WriteLine($"Timer elapsed at {e.SignalTime}, thread id: {Environment.CurrentManagedThreadId}");
}

现在我们可以稍微探讨一下这个计时器的另外一个特性了：如果它的回调函数比较耗时，甚至超过了它的周期，会怎么样？

答案非常简单：计时器依旧会按照设定的周期继续触发回调函数，虽然看起来（比如从控制台的输出）可能会表现出延迟，甚至可能因为每次回调的延迟不同而使得输出顺序变得混乱。这也就是它使用线程池的原因之一：即便上一次回调还没有完成，导致它所在的线程仍处于阻塞状态，下一次回调依旧可以在其他线程上继续执行。

Note

还有一个值得注意的点：当计时器停止（甚至释放）后，之前每次 Elapsed 触发的回调如果还没有执行完毕，那么将仍会处于执行状态，尤其是它们内部有耗时的操作时。这是因为计时器每次触发时，都会将回调函数放入线程池中执行，而线程池中的线程会继续执行这些任务，直到它们完成。

System.Threading.PeriodicTimer

源代码：System.Threading.PeriodicTimer.cs

这是一个比较新的计时器（.NET 6+），它不仅现代，而且精确，还支持异步操作。正如它的名称所提示的，它旨在提供一个周期性的计时器，允许我们在每个周期结束时执行一个异步操作。它与传统的 Timer 类不同，不使用事件或回调，而是通过 await 一个异步方法来控制每次操作的发生。

它的使用方式也非常简单，下面是一个例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


using System;
using System.Threading;

var timer = new PeriodicTimer(TimeSpan.FromSeconds(1)); // 创建一个周期为 1 秒的计时器
var cts = new CancellationTokenSource();
var token = cts.Token;

try
{
 while (await timer.WaitForNextTickAsync(token))
 {
 token.ThrowIfCancellationRequested();

 Console.WriteLine($"Periodic timer tick at {DateTime.Now}, thread id: {Environment.CurrentManagedThreadId}");
 }
}
catch (OperationCanceledException)
{
 Console.WriteLine("Periodic timer canceled.");
}
finally
{
 timer.Dispose();
 cts.Dispose();
}

这个计时器还有一个常见的使用情形，就是在 ASP.NET Core 中借助它来创建一个后台的定时任务。因为它不仅准时，而且支持异步操作。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class MyService : BackgroundService
{
 private readonly ILogger<MyService> logger;

 private readonly PeriodicTimer timer;

 public MyService(ILogger<MyService> logger)
 {
 this.logger = logger;
 this.timer = new(TimeSpan.FromMilliseconds(1000));
 }

 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
 while (await timer.WaitForNextTickAsync(stoppingToken) && !stoppingToken.IsCancellationRequested)
 {
 logger.LogInformation("Hello, world!");
 }
 }
}

然后我们就可以在入口处注册这个服务了：

1

builder.Services.AddHostedService<MyService>();

这样即便每次循环体中的操作比较耗时，它仍然可以保证每次触发的时间是准确的。它绝对比在循环中使用 await Task.Delay() 要准确得多。

System.Windows.Threading.DispatcherTimer

源代码：DispatcherTimer.cs

最后我们再来简单地看一下适用于 WPF 的 DispatcherTimer。看到 Dispatcher 这个词，我们很容易联想到诸如 Application.Current.Dispatcher，所以它主要用于在 UI 线程上执行操作。它的使用方式与 System.Timers.Timer 类似，也提供了 Start、Stop 等方法，以及 Interval 属性和 Tick 事件等。

下面是一个简单的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


using System;
using System.Windows.Threading;

public partial class MainWindow : Window
{
 private readonly DispatcherTimer timer;

 public MainWindow()
 {
 InitializeComponent();

 timer = new DispatcherTimer();
 timer.Interval = TimeSpan.FromSeconds(1);
 timer.Tick += Timer_Tick;
 timer.Start();
 }

 private void Timer_Tick(object sender, EventArgs e)
 {
 listBox.Items.Add($"Dispatcher timer tick at {DateTime.Now}, thread id: {Environment.CurrentManagedThreadId}");
 }
}

DispatcherTimer 有几个构造函数，可以指定它的优先级以及所使用的 Dispatcher。默认情况下，它会使用 DispatcherPriority.Background 以及 Dispatcher.Current。只要你在 UI 线程上创建它，它就会在 UI 线程上执行回调函数。

总结

在这篇文章中，我们介绍了 .NET 中常用的几种计时器，包括它们各自的功能和特点，以及所适合的场景。简单来说：

System.Threading.Timer 是最轻量的计时器，适用于大多数非 UI 线程的场景，但因为缺少灵活的控制方法和线程安全问题，可能需要一些额外的处理；
System.Timers.Timer 提供了更易用的 API 和更多的功能，适用于大多数需要定时操作的场景；
System.Threading.PeriodicTimer 是一个现代的计时器，支持异步操作，适用于需要精确控制周期性操作的场景，以及异步编程；
DispatcherTimer 适用于 WPF，能够在 UI 线程上执行操作，适合需要与 UI 交互的场景。

希望这篇文章能帮助你更好地理解 .NET 中的计时器，并在实际开发中选择合适的计时器来满足你的需求。如果你有任何问题或建议，欢迎在评论区留言讨论！

常见与不常见哈希函数

Mon, 30 Jun 2025 00:00:00 +0000

在前面的文章中，我们已经探讨了有关密码加盐哈希的话题。这次我们围绕着哈希函数再做一些补充。

哈希函数是计算机科学和密码学中非常重要的工具。它们用于数据完整性验证、数字签名、密码存储等多个领域。哈希函数的种类有很多，它们有的是常见的，有的则相对不那么常用。本文将介绍一些常见和不常见的哈希函数，以及它们的特点和应用场景。

早期哈希函数

说起早期的哈希函数，MD5 和 SHA-1 是最广为人知的。当然，在它们之前还有更早的，比如 MD4 和 SHA-0，但它们早已不再被广泛使用。MD5 和 SHA-1 在 1990 年代和本世纪初期非常流行，广泛应用于文件完整性校验、数字签名等场景。

它们虽然曾被广泛使用，但由于安全性问题，现在已不再推荐用于安全敏感的应用。尽管如此，它们仍然非常流行，比如许多软件下载等场景都会提供文件的 MD5 或 SHA-1 校验和，以方便用户验证下载的文件是否完整。所以，即便一个技术有缺点（甚至有严重漏洞），只要它足够流行，仍然会被广泛使用。就像 JPG 图片格式一样，虽然它有很多缺点（比如不支持透明度、不支持无损压缩、容易出现伪影等），但它仍然是最常用的图片格式之一。

那么它们到底有什么安全性问题呢？简单来说，MD5 和 SHA-1 都存在碰撞攻击的风险。碰撞攻击是指两个不同的输入数据经过哈希函数处理后，得到相同的哈希值。这意味着攻击者有可能构造一个恶意文件，使其哈希值与合法文件相同，从而绕过完整性验证。

就拿上面提到的验证下载文件的完整性来说。比如网站告诉你，该文件的哈希值是 d41d（这里为方便起见，仅使用前 4 位）。然后你下载了一个文件，计算出来的哈希值也是这个。一般来说，你可以确定这个文件没有被篡改，从而可以放心使用。但是黑客可以构造一个哈希值同样是 d41d 的恶意文件，并借助一些手段向你提供这个文件。你下载后，就会误以为这个文件是安全的，最终运行了病毒程序。除了病毒程序，还可能是伪造的证书文件等。这些都可能带来严重的后果。

即便如此，碰撞攻击依旧是成本巨大的。再加上 MD5 的广泛适配性以及高效的计算速度，使得它在很多场景下仍然被使用。比如在一些非安全敏感的应用中，MD5 仍然被用来快速计算文件的哈希值，以便进行完整性校验。

说起哈希碰撞，这里还有一个有趣的例子。在 2017 年，谷歌的研究人员制作了下面这张 GIF 动图。这张动图神奇的地方在于，它可以展示自己的 MD5 值！

更多有意思的例子可以看看这篇文章。

SHA-2 系列

因为 MD5 和 SHA-1 的安全性问题，SHA-2 系列（包括 SHA-256、SHA-384、SHA-512 等）成为了新的标准。SHA-2 系列的哈希函数在设计上更为复杂，提供了更高的安全性。它们被广泛应用于数字签名、证书颁发机构（CA）等领域。

一般来说，如果我们想要将它用于数据库中存储用户的密码，那么通常还会给它加上一个随机的盐值（salt），这样可以防止彩虹表攻击。彩虹表攻击是指攻击者预先计算出大量常见密码的哈希值，并存储在一个表中。当攻击者获取到哈希值后，可以通过查找这个表来快速破解密码。通过添加盐值，即使两个用户的密码相同，它们的哈希值也会不同，从而增加了破解的难度。

以 C# 为例，使用 SHA-256 哈希函数和盐值来存储密码的代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


using System;
using System.Text;
using System.Security.Cryptography;

static byte[] GenerateSalt()
{
 using (var rng = new RNGCryptoServiceProvider())
 {
 byte[] salt = new byte[16];
 rng.GetBytes(salt);
 return salt;
 }

 // 上面的方法会提示已过时，可以使用下面的方式
 // return RandomNumberGenerator.GetBytes(16);
}

static byte[] HashPassword(string password, byte[] salt)
{
 using (var sha256 = SHA256.Create())
 {
 byte[] passwordBytes = Encoding.UTF8.GetBytes(password);
 byte[] saltedPassword = new byte[passwordBytes.Length + salt.Length];
 Buffer.BlockCopy(passwordBytes, 0, saltedPassword, 0, passwordBytes.Length);
 Buffer.BlockCopy(salt, 0, saltedPassword, passwordBytes.Length, salt.Length);
 return sha256.ComputeHash(saltedPassword);
 }

 // 新版本还提供了更简便的静态方法，比如 SHA256.HashData
}

然后将加盐哈希后的密码与盐值一起存储到数据库中就可以了。需要验证密码时，先从数据库中获取盐值，然后使用相同的哈希函数和盐值对输入的密码进行哈希，再与存储的哈希值进行比较即可。

不必担心盐值泄露的问题，因为即使攻击者获取了盐值，也无法直接破解密码。盐值的作用是增加哈希值的唯一性和复杂性，使得攻击者无法使用预先计算的彩虹表来破解密码。

SHA-3 系列

SHA-2 系列虽然解决了 MD5 和 SHA-1 的安全性问题，但它仍然是基于与前代相同的架构（Merkle-Damgård）。科学家担心之前的碰撞方式继续发展和研究下去有可能破解 SHA-2 系列，并且随着量子计算的发展，SHA-2 系列的安全性也可能受到威胁。因此，NIST（美国国家标准与技术研究院）在 2015 年发布了 SHA-3 系列。

SHA-3 系列采用了全新的设计理念，基于 Keccak 算法。它不仅提供了更高的安全性，还可以根据需要选择不同的输出长度（如 SHA3-224、SHA3-256、SHA3-384、SHA3-512 等）。

不过 SHA-3 系列目前的应用并不算广泛，它更多的是作为 SHA-2 的一个备选，以便未来在 SHA-2 系列被破解时可以迅速切换到更安全的哈希函数。此外，虽然它提供了更好的安全性和灵活性，但是在实际的场景下，我们通常会选择其他的一些更擅长某一方面的方法。

PBKDF2

在 SHA-2 的基础上，为了进一步提高破解的难度，除了引入盐值外，通常还会引入迭代次数。PBKDF2（Password-Based Key Derivation Function 2）就是一个常用的密码哈希函数，它通过多次迭代哈希计算来增加破解的难度。

PBKDF2 的工作原理是将密码和盐值作为输入，经过多次迭代的哈希计算，生成一个固定长度的输出。迭代次数越多，破解的难度就越大。PBKDF2 通常用于密码存储和密钥派生。

在 C# 中，可以使用 Rfc2898DeriveBytes 类来实现：

1
2
3
4
5
6
7
8
9


using System;
using System.Security.Cryptography;
using System.Text;

static byte[] HashPasswordWithPBKDF2(string password, byte[] salt, int iterations = 10000)
{
 using var pbkdf2 = new Rfc2898DeriveBytes(password, salt, iterations, HashAlgorithmName.SHA256);
 return pbkdf2.GetBytes(32); // 生成 32 字节的哈希值
}

bcrypt 与 Argon2

可惜的是，PBKDF2 在某些情况下可能不够安全，尤其是面对现代硬件的攻击（比如 GPU 超强的并行计算能力）。为了解决这个问题，出现了 bcrypt 和 Argon2 等更安全的密码哈希函数。

bcrypt 是基于 Blowfish 加密算法的密码哈希函数，它通过增加计算复杂度来提高破解难度。bcrypt 的一个重要特性是它可以调整工作因子（cost factor），从而控制哈希计算的时间和资源消耗。工作因子越高，破解的难度就越大。与迭代次数不同的是，这个工作因子是指数级增长的，这意味着每增加一个单位的工作因子，计算时间就会翻倍。在 C# 中，可以使用 BCrypt.Net-Next 等库来实现 bcrypt。

Argon2 是 2015 年密码学竞赛的获胜者，它被认为是目前最安全的密码哈希函数之一。Argon2 具有高度的可配置性，可以调整内存使用量、迭代次数和并行度等参数，从而提供更强的安全性。Argon2 分为三个变种：Argon2d、Argon2i 和 Argon2id，分别针对不同的攻击场景。在 C# 中，可以使用 Konscious.Security.Cryptography.Argon2 等库来使用 Argon2。

BLAKE2

BLAKE2 是一个相对较新的哈希函数（2013 年发布），它在速度和安全性之间取得了很好的平衡。BLAKE2 的设计目标是提供比 MD5 和 SHA-1 更快的速度，同时比 SHA-2 更高的安全性。它非常适合用于文件完整性校验、密码哈希等场景。

它的高性能得益于它充分利用了现代 CPU 的 SIMD 指令集（如 SSE2/AVX 等），在多核处理器上表现尤为出色。不仅如此，它还提供了两个主要版本：BLAKE2b 和 BLAKE2s。BLAKE2b 适用于 64 位平台，输出长度可变，最大为 64 字节；而 BLAKE2s 适用于 8 到 32 位平台，输出长度可变，最大为 32 字节。

除此之外，它还提供了很多特性，比如内置密钥机制、可选盐值和个性化字符串等。这些特性使得 BLAKE2 在很多应用场景中都非常有用。

在 C# 中，可以使用 BouncyCastle 等库来实现 BLAKE2。以下是一个简单的示例：

1
2
3
4
5
6
7


using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Digests;

var digest = new Blake2bDigest(); // 默认 512，可以改为 8~512 的任意 8 的倍数
digest.BlockUpdate(data, 0, data.Length);
var hash = new byte[digest.GetDigestSize()];
digest.DoFinal(hash, 0);

SM3

最后我们再来介绍一个国产的哈希函数：SM3。SM3 是中国国家密码管理局在 2010 年发布的哈希函数标准。它是中国独立设计和开发的哈希算法，不依赖于国外的标准。这对于国家安全和信息安全具有重要意义。

SM3 算法生成 256 位的哈希值，并且安全性及效率与 SHA-256 相当。它在设计上具有良好的抗碰撞性和单向性，旨在抵抗各种密码分析攻击。

作为中国的国家标准，SM3 在国内的应用越来越广泛，尤其是在金融、政府和军工等领域。

总结

哈希函数可谓是种类繁多、各有所长。从早期的 MD5 和 SHA-1，到现在的 SHA-2、SHA-3、PBKDF2、bcrypt、Argon2、BLAKE2 和 SM3，每种哈希函数都有其独特的设计理念和应用场景。

简单来说，一些常见需求及可以选择的哈希函数如下：

数据完整性校验：MD5、SHA-1、SHA-2、BLAKE2
密码存储：PBKDF2、bcrypt、Argon2
数字签名：SHA-2、SHA-3
国产安全：SM3

逆向思考 .NET 一些版本的新特性

Tue, 03 Jun 2025 00:00:00 +0000

.NET 作为一个近年来更新频率稳定的平台，每个版本都会引入一些新的特性和改进。这些新特性往往是为了提高开发效率、增强性能或改善用户体验。然而，很多时候我们可能会对某些新特性的引入感到疑惑，甚至认为它们并不是那么必要。

在这篇文章中，我想借助几个例子来分享我的思考，并给大家提供一个有意思的视角：逆向思考 .NET 新特性背后的逻辑和思考方式。

匿名类型、lambda 表达式和扩展方法

在 C# 3 中，.NET 引入了匿名类型、lambda 表达式和扩展方法等特性。我们先来简单回顾一下这些特性都是什么。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 匿名类型
var mapped = people.Select(p => new { p.Name, p.Age });
// Lambda 表达式
var filtered = people.Where(p => p.Age > 18);
// 扩展方法
public static class StringExtensions
{
 public static IEnumerable<T> Where<T>(this IEnumerable<T> source, Func<T, bool> predicate)
 {
 foreach (var item in source)
 {
 if (predicate(item))
 {
 yield return item;
 }
 }
 }
}

相信大家看了上面我“别有用心”的实例之后，一定不难发现：这些新特性似乎都与 LINQ 有关，而 LINQ 正是在 C# 3.0 中引入的。

因此，我们不难得出结论：这些新特性都是为了支持 LINQ 的语法而添加的。它们使得我们可以更简洁地编写查询代码，提升了代码的可读性和可维护性。

当然了，这三个特性绝不仅仅是为了支持 LINQ 而存在的。它们在其他场景下也有着广泛的应用。例如，匿名类型可以用于快速创建临时数据结构，lambda 表达式可以用于方便地声明事件处理和回调，而扩展方法则可以让我们为现有类型添加新的功能。它们都是相当强大的功能。

丢弃运算符

我们再来看一个例子。C# 7 引入了丢弃运算符（_），它可以用于忽略不需要的值。这看起来似乎是一个小特性，但如果我们再去看这个版本引入的其他几个特性，就不难发现它们之间的关系了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// C# 7.0-
int value;
if (int.TryParse(input, out value))
{
 // ...
}

Tuple<int, string> GetResults() { }
var results = GetResults();
var value = results.Item1; // 忽略 Item2

// C# 7.0+
if (int.TryParse(input, out var _))
{
 // ...
}

(int, string) GetResults() { }
var (value, _) = GetResults(); // 使用元组解构

不难发现，C# 7 还引入了新的 out 变量声明和元组解构语法。而在这些语法中，丢弃运算符都可以起到便捷的作用。因此，我们可以说，这几个新的特性是密不可分的，所以它们也得以在这个版本中同时出现。

`init` 访问器与记录类

C# 9 引入了 init 访问器和记录类（record class）。记录类为我们提供了相当便捷的声明不可变数据类型的方式，并且重写了 Equals、GetHashCode 和 ToString 等方法，来提供更好的语义。

默认情况下，一个记录类中的属性都是只读的，即：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public record Person(string Name, int Age);

// 相当于
public class Person
{
 public string Name { get; init; }
 public int Age { get; init; }

 public override bool Equals(object? obj) { /* ... */ }
 public override int GetHashCode() { /* ... */ }
 public override string ToString() { /* ... */ }
}

因此，init 访问器与记录类一起出现是很自然的。它们共同提供了一种声明不可变数据类型的方式，使得我们可以更方便地创建和使用不可变对象。

顶级语句与隐式引入

C# 9 引入了顶级语句，而 C# 10 引入了隐式引入。这样我们既不用再写 Program 及 Main 方法，也不用再写很多常见的 using 语句了。然后，在那段时间，我们还得到了什么呢？我们得到了 ASP.NET Core Minimal APIs。

1
2
3
4


var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();

这些代码就很大程度上借助了顶级语句和隐式引入的特性。它们使得我们可以更简洁地编写 ASP.NET Core 应用程序。C# 用这层简洁的伪装，让更多的人认为用它开发 Web 应用程序是件很简单的事情（笑）。

另外，从此，C# 也可以用 1 行代码实现 Hello World 了。

1

Console.WriteLine("Hello World!");

接口的抽象静态成员

在以前的 C# 版本中，接口只能包含方法、属性、事件和索引器等成员，而不能包含静态成员。相信这是绝大多数 .NET 开发者的共识，也是绝大多数开发者在入门时的认知，以及在其他编程语言中的经验。

然而，在 C# 11 中，我们可以在接口中声明抽象静态成员了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public interface IShape
{
 double Area { get; }
 static abstract IShape Create(double size);
}

public class Circle : IShape
{
 public double Radius { get; }
 public double Area => Math.PI * Radius * Radius;

 public static Circle Create(double size) => new Circle(size);
}

这样的声明会要求实现该接口的类必须提供这个静态方法。那么这个新特性有什么用呢？

很快，我们在 C# 12 中就看到了它的应用：INumber 接口的引入。这个接口定义了数字类型的通用行为，其中就包含了不少静态的成员，比如 Parse、Zero 等等。

不难想象，如果没有这个新的接口特性，这个接口的实现肯定是做不到的。

结论

其实其他类似的例子还有很多，比如 ref struct、readonly struct 等与 Span 及 Memory 相关的特性，IAsyncEnumerable 与 Channel 等等。

通过这些例子，我们可以看到，.NET 的新特性往往是为了支持某个特定的功能或语法而引入的。它们之间有着密切的关系。有的是为了支持某个功能的实现，有的是为了优化某个语法的使用体验，有的则是为了提供更好的性能或可读性。

至于为什么有的特性并不是完全在同一个版本出现，这也是有一些原因的。其中一个原因是，.NET 的新特性往往需要经过多次迭代和完善才能最终稳定下来。有可能直到某个版本要发布时，想要添加的新特性仍然不够成熟，因此为了辅助它而诞生的特性可能会提前在该版本上线，而它所辅助的特性则会在下一个版本中引入。

希望通过这篇文章，大家能够对 .NET 的新特性有一个更深入的理解。逆向思考这些特性背后的逻辑和思考方式，可以帮助我们更好地理解它们的设计初衷和应用场景，也能让我们在使用这些特性时更加得心应手。这样的例子见得多了，可能会有一种“微软在开发某功能时引入的新特性因为太好用了，所以顺便下放给我们使用”的感觉吧😂。

是不是所有 C# 中实现了 Dispose 方法的类我们都要用完即释放？

Mon, 21 Apr 2025 00:00:00 +0000

C# 作为一个有 GC（垃圾回收）的语言，在使用托管资源时，通常不需要开发者关注资源的释放问题。但如果使用了非托管资源（常见的如文件句柄、数据库连接等），就需要手动释放资源了。为了方便管理资源，并形成一种统一的规范，C# 提供了 IDisposable 接口（后来还提供了 IAsyncDisposable 接口），开发者可以通过这个接口提供的 Dispose 方法来释放资源，还可以借助 C# 的 using 语句来简化资源的释放过程。

那么问题来了：是否所有实现了 IDisposable 接口的类都需要在用后立刻调用 Dispose 方法？答案是：不一定。

这篇文章我们就借助几个典型的例子，来看看在什么情况下可以不调用 Dispose 方法，并从底层的原理出发，给大家提供一个判断是否有必要调用 Dispose 方法的思路。

实现 IDisposable 接口但不涉及资源释放的类

首先我们看第一种情况：有些类实现了 IDisposable 接口，但并不涉及资源的释放。这时候相信有的读者就会问了：这种情况有点太强行凑数了吧？而且这难道不是在滥用 IDisposable 吗，毕竟它本来是用来释放资源的啊？

其实未必。因为 C# 的 using 关键字提供了一个非常方便的语法糖，可以让我们在使用完一个对象后，自动调用它的 Dispose 方法中的逻辑（即便它可能与资源释放无关）。这样我们就可以实现延迟执行，以及在任何情况下（包括抛异常）都能够确保会执行的逻辑了。

首先我们简单回顾一下 using 关键字在幕后做的事情。我们这里看一个简单例子：

1
2


using var fs = new FileStream("test.txt", FileMode.Open);
// 其他逻辑

上面的代码在编译后会变成下面的代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var fs = new FileStream("test.txt", FileMode.Open);
try
{
 // 其他逻辑
}
finally
{
 if (fs != null)
 {
 ((IDisposable)fs).Dispose();
 }
}

Tip

在上面的例子中，using 关键字并没有搭配花括号进行使用。这是 C# 8.0 中新增的语法糖，可以让我们减少一层缩进。它相当于花括号涵盖了从 using 关键字到作用域的结束这个范围。

我们可以看到，using 语句在编译后会变成一个 try...finally 语句块，确保了在 try 块中的代码执行完后，无论是否出现异常，最终都会执行 finally 块中的代码。

于是我们就可以借助这个语法来实现一些延迟执行的逻辑了，尤其是类似 Go 语言中的 defer 语句。Go 语言中，defer 语句会在函数返回时执行，比如下面这个例子：

1
2
3
4


func main() {
 defer fmt.Println("defer")
 fmt.Println("hello")
}

于是我们可以仿照这个思路，在 C# 中实现一个类似的功能：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class Defer : IDisposable
{
 private readonly Action _action;

 public Defer(Action action)
 {
 _action = action;
 }

 public void Dispose()
 {
 _action?.Invoke();
 }
}

它在构建时会传入一个 Action 委托，表示需要延迟执行的逻辑。然后我们就可以像下面这样使用它了：

1
2


using var defer = new Defer(() => Console.WriteLine("defer"));
Console.WriteLine("hello");

所以对于这样的一个类，即便它实现了 IDisposable 接口，我们也不必须在使用完后，手动调用它的 Dispose 方法。因为它的 Dispose 方法并不涉及资源的释放，而只是执行一些延迟逻辑而已。

因为基类或接口的约束而实现 IDisposable 接口的类

除了上面提到的为了借助 using 语句来实现延迟执行的逻辑外，还有一些类实现了 IDisposable 接口，但并不涉及资源的释放。

我们都知道，C# 中有一些原生的数据流，比如 FileStream、MemoryStream、GZipStream 等等。它们的基类 Stream 实现了 IDisposable 接口，并且它们根据自己的实际情况，也各自提供了具体的 Dispose 方法的实现，比如 FileStream 会关闭文件句柄，从而释放文件资源，避免文件被占用。

但这其中的 MemoryStream 就有些非同寻常了。它虽然是一个数据流，但它并不涉及资源的释放。因为它的底层数据是存储在内存中的一个字节数组（byte[]）中，而这个字节数组是一个托管资源。在它的源代码中我们可以看到：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


public class MemoryStream : Stream
{
 private byte[] _buffer; // Either allocated internally or externally.
 private readonly int _origin; // For user-provided arrays, start at this origin
 private int _position; // read/write head.
 private int _length; // Number of bytes within the memory stream
 private int _capacity; // length of usable portion of buffer for stream

 private bool _expandable; // User-provided buffers aren't expandable.
 private bool _writable; // Can user write to this stream?
 private readonly bool _exposable; // Whether the array can be returned to the user.
 private bool _isOpen; // Is this stream open or closed?

 // ...

 protected override void Dispose(bool disposing)
 {
 if (disposing)
 {
 _isOpen = false;
 _writable = false;
 _expandable = false;
 // Don't set buffer to null - allow TryGetBuffer, GetBuffer & ToArray to work.
 _lastReadTask = default;
 }
 }
}

所以对于 MemoryStream 这样的 Dispose 方法并不涉及资源释放的类型，即便我们不调用它的 Dispose 方法，也不会造成资源泄漏。当然了，这并不意味着我们就不需要甚至不应该去做这件事情，因为规范的开发习惯仍旧是可以为我们的代码带来更好的可读性和可维护性的。

在特定情况下可以不调用 Dispose 方法的类

有些类提供了 Dispose 方法，但是在某些情况下，对这一方法的调用并不是至关重要的。这里有一个典型的例子就是我们在异步编程中常见的 CancellationTokenSource（下面简称为 CTS）。

首先我们来写一个简单的代码，并观察它在运行时的内存占用：

1
2
3
4


for (int i = 0; i < 100000000; i++)
{
 var cts = new CancellationTokenSource();
}

运行后我们会发现，内存几乎没有任何变化。这是否意味着，CTS 的 Dispose 方法并不重要呢？其实并不是，但是在上面的这个用法中，调用与否确实没有太大的区别。这是怎么回事呢？

我们来观察 CTS 的 Dispose 方法的实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


protected virtual void Dispose(bool disposing)
{
 if (disposing && !_disposed)
 {
 ITimer? timer = _timer;
 if (timer != null)
 {
 _timer = null;
 timer.Dispose();
 }

 _registrations = null;

 if (_kernelEvent != null)
 {
 ManualResetEvent? mre = Interlocked.Exchange<ManualResetEvent?>(ref _kernelEvent!, null);
 if (mre != null && _state != States.NotifyingState)
 {
 mre.Dispose();
 }
 }

 _disposed = true;
 }
}

可以发现，这里它对两个“可有可无”的对象进行了回收，分别是：

_timer：一个 ITimer 对象，表示一个定时器
_kernelEvent：一个 ManualResetEvent 对象，是一个信号量

它们分别是做什么用的呢？首先我们来看定时器。我们知道，CTS 提供了延时自动取消的功能。比如我们希望在 5 秒后自动取消，那么实现方法可以是：

1
2
3


var delay = TimeSpan.FromSeconds(5);
var cts = new CancellationTokenSource(delay);
// 或者也可以在创建后调用 CancelAfter 方法

此时，CTS 内部就会创建这个定时器，从而实现这个功能。在这一情况下，就会产生需要我们去释放的资源了。

另外一个信号量又是怎么回事呢？

我们都知道，CTS 现在常用于异步编程。它的 CancellationToken 可以传给标准库提供的 Async 结尾的方法，从而实现任务的取消。但是一些老的库函数可能并不支持 CancellationToken，这时候我们就可以借助 token 上的这个 WaitHandle 来实现任务的取消了。下面是 CTS 中关于 WaitHandle 属性的实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


internal WaitHandle WaitHandle
{
 get
 {
 ThrowIfDisposed();

 // Return the handle if it was already allocated.
 if (_kernelEvent != null)
 {
 return _kernelEvent;
 }

 // Lazily-initialize the handle.
 var mre = new ManualResetEvent(false);
 if (Interlocked.CompareExchange(ref _kernelEvent, mre, null) != null)
 {
 mre.Dispose();
 }

 if (IsCancellationRequested)
 {
 _kernelEvent.Set();
 }

 return _kernelEvent;
 }
}

可以发现，它默认是没有值的；当我们第一次访问它时，它便会创建一个新的，并返回它。这样的操作就会产生一个需要我们去释放资源的对象。我们可以做这样的一个实验：

1
2
3
4
5


for (int i = 0; i < 100000000; i++)
{
 var cts = new CancellationTokenSource();
 var handle = cts.Token.WaitHandle;
}

Tip

WaitHandle 在 CTS 上是 internal 的，我们只能也应当在 CancellationToken 上去访问，因为通常情况下，我们传给方法的参数并不是 CTS 对象本身，而是它的 Token。

然后运行程序，就会发现内存在不断增加。只要我们调用了 CTS 的 Dispose 方法，内存便会不再上升。

所以我们可以得出结论：如果我们在使用 CTS 时，既不使用延时自动取消的功能，也不使用 WaitHandle 属性，那么我们不调用 Dispose 方法也不会造成资源的泄漏。

虽然提供了 Dispose 方法，但不应该用完立即释放的类

还有一种情况是，虽然类实现了 IDisposable 接口，但我们并不应该在用完后立即释放它。它被设计出来就是希望我们能够复用的。典型的例子就是 HttpClient。

比如下面这个错误例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


List<string> urls = new List<string>()
{
 "https://www.baidu.com",
 "https://www.sogou.com",
 "https://www.sohu.com",
};

foreach (var url in urls)
{
 using var client = new HttpClient();
 await client.GetAsync(url);
}

这个例子就是一个错误的用法。正确的做法应该是将 HttpClient 的声明移动到循环外部，或者还可以声明为一个静态对象等。这是为什么呢？

简单来说，HttpClient 底层会使用 HttpClientHandler 去处理涉及到连接池、Socket、TCP 连接等资源的管理。TCP 连接因为比较昂贵（比如有三次握手、四次挥手等），所以它通常会被复用。当我们使用 HttpClient 去访问一个链接时，访问结束后这个 TCP 连接并不会立即关闭，而是会被放入连接池中，等待下次的复用。

但是，如果我们在每次请求时都创建一个新的 HttpClient 对象，那么这个 TCP 连接就会占据连接池中的一个位置，还有本地端口等资源，最终可能会导致连接池或本地端口的耗尽，进而抛出 SocketException 等异常。

因为 HttpClient 是一个包装好的功能相当灵活的类，因此我们完全可以只创建一个，并且多次使用。不管我们访问的链接是否可以复用，怎么复用，保持连接状态多久，都会被它妥善处理。所以对于一个本地项目（如控制台应用、WPF 应用等），我们完全可以创建一个单例并处处使用它。

如果我们在项目中还使用了 DI 容器（比如微软官方提供的 Microsoft.Extensions.DependencyInjection），那么我们可以将 HttpClient 注册为一个单例的服务。这样我们就可以在整个项目中复用它了。

1
2
3
4
5


var services = new ServiceCollection();
services.AddSingleton<HttpClient>();
var serviceProvider = services.BuildServiceProvider();

var client = serviceProvider.GetService<HttpClient>();

当然了，这个方式并不是最推荐的方式（不过对于简单的本地项目来说是可取的）。对于复杂些的项目，我们更应该考虑的方式是使用 HttpClientFactory。要使用它，我们还要引入一个包：Microsoft.Extentions.Http（控制台或 WPF 等本地程序通常需要，而 ASP.NET Core 项目会自动引入它，因此就不需要额外安装包了），然后就可以使用了：

1
2
3
4
5
6


var services = new ServiceCollection();
services.AddHttpClient();
var serviceProvider = services.BuildServiceProvider();

var factory = serviceProvider.GetService<IHttpClientFactory>();
var client = factory.CreateClient();

对于更加复杂的情况，比如我们希望为不同的服务类注入配置不同的 HttpClient（比如不同的 BaseAddress、Header、Timeout 等），我们可以使用 AddHttpClient 的“命名客户端”的方法来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


var services = new ServiceCollection();
services.AddHttpClient("baidu", c =>
{
 c.BaseAddress = new Uri("https://www.baidu.com");
 c.Timeout = TimeSpan.FromSeconds(30);
});
services.AddHttpClient("sogou", c =>
{
 c.BaseAddress = new Uri("https://www.sogou.com");
 c.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3");
});
var serviceProvider = services.BuildServiceProvider();

var factory = serviceProvider.GetService<IHttpClientFactory>();
var baiduClient = factory.CreateClient("baidu");
var sogouClient = factory.CreateClient("sogou");

这样我们就可以为不同的服务类注入不同的 HttpClient 了。关于 HttpClientFactory 的更多用法，可以参考官方的教程。

总结

在这篇文章中，我们讨论了在 C# 中是否需要总是调用 Dispose 方法的问题。我们通过几个典型的例子，来看看在什么情况下可以不调用 Dispose 方法，并从底层的原理出发，给大家提供一个判断是否有必要调用 Dispose 方法的思路。

在实际的开发中，与其说我们需要分辨出哪些对象是可以不用释放的，不如说我们应当明白如何对这一操作的必要性进行正确的判断，并养成统一且规范的开发习惯。这样不管是对团队的其他开发者，还是未来的自己，都是有好处的。

在多线程开发中用信号量代替轮询和标志位

Wed, 02 Apr 2025 00:00:00 +0000

我们在多线程开发中，经常会用到标志位和轮询，从而控制一个线程中的执行逻辑。但是这样的方式会导致代码的可读性和可维护性下降，并且也不够优雅。这篇文章我们来看一看如何用信号量等机制来替代轮询标志位的方式，从而实现线程间的通信和控制。

传统方式

首先我们来看一看传统的标志位和轮询是怎么一回事。这里我们用一个简单的例子来探讨：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


class MyService
{
 private volatile bool _shouldStop;

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 private void Worker()
 {
 while (!_shouldStop)
 {
 // 执行一些工作
 Thread.Sleep(50); // 模拟工作
 }
 }
}

上面就是一个典型的例子。这里，_shouldStop 是一个标志位，表示线程是否需要停止。我们在 Start 和 Stop 方法中分别设置和读取这个标志位，并在 Worker 方法中，通过轮询它来判断线程是否需要继续执行。

Info

上面的标志位 _shouldStop 是 volatile 的，这样做能够保证编译器不会对其进行优化，从而保证每次读取都是最新的值。其实一般情况下，如果我们的轮询中包含了 Thread.Sleep 等操作，那么即便不加 volatile，也依旧是可以读到最新的值的。

Warning

注意，这里我们只是用简单的代码大概介绍思路，并没有提供一个稳健的实现。比如上面的例子中，我们并没有处理用户多次调用 Start 方法，也没有处理线程异常等情况。

如果我们想在上面的基础上再添加暂停和继续的功能，那么我们就需要添加更多的标志位和轮询逻辑。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


class MyService
{
 private volatile bool _shouldStop;
 private volatile bool _isRunning;

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunning = true;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunning = false;
 }

 public void Resume()
 {
 _isRunning = true;
 }

 private void Worker()
 {
 while (!_shouldStop)
 {
 if (_isRunning)
 {
 // 执行一些工作
 }

 Thread.Sleep(50); // 暂停时也要休眠，避免 CPU 占用过高
 
 }
 }
}

经典的两个标志位

现在我们来看一看如何使用信号量来替代标志位。

用 `ManualResetEvent` 实现线程的暂停和继续

我们先来思考一下，上面的 _isRunning 的作用和效果是什么。我们想用它的值来控制线程是否要执行操作，但是我们不能在它发生变化时立刻得到通知，因此我们只能每隔一段时间去轮询一下。那么，如果有办法能够在它为 false 时不需要我们轮询，而是直接阻塞在某个地方，等到它变为 true 时再继续执行，是不是就好很多了？

根据这一需求，我们可以使用 WaitHandle 的两个子类——ManualResetEvent 及 AutoResetEvent 来实现。ManualResetEvent 是一个可以手动重置的信号量。当它 Set 后，将会保持放行状态，直到再次 Reset 才会关闭。与它相对的是 AutoResetEvent，它会在每次放行后自动重置。这里更符合我们的需求的是 ManualResetEvent，因为我们希望放行后能够连续执行多次，而不需要每次都 Set 后执行一次。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


class MyService
{
 private volatile bool _shouldStop;
 private ManualResetEvent _isRunningEvent = new ManualResetEvent(false); // 初始是关闭的

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunningEvent.Set(); // 线程开始时放行
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunningEvent.Reset(); // 关闭信号量
 }

 public void Resume()
 {
 _isRunningEvent.Set(); // 放行信号量
 }

 private void Worker()
 {
 while (!_shouldStop)
 {
 _isRunningEvent.WaitOne(); // 等待信号量放行

 // 执行一些工作

 Thread.Sleep(50); // 适当休眠，避免 CPU 占用过高
 }
 }
}

用 `CancellationToken` 实现任务的停止

我们可以进一步优化上面的例子，比如我们可以使用 CancellationToken 来实现任务的停止。CancellationToken 是 .NET 中用于取消操作的机制，它可以在任务中传递一个取消请求，并且可以在任务中检查这个请求。它不仅可以用于异步编程，也可以用于多线程编程。这里，我们用它来取代 _shouldStop 标志位。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


class MyService
{
 private ManualResetEvent _isRunningEvent = new ManualResetEvent(false); // 初始是关闭的

 private Thread? _workerThread;
 private CancellationTokenSource _cancellationTokenSource = new CancellationTokenSource();

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _isRunningEvent.Set(); // 线程开始时放行
 _workerThread.Start();
 }

 public void Stop()
 {
 _cancellationTokenSource.Cancel(); // 取消操作
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunningEvent.Reset(); // 关闭信号量
 }

 public void Resume()
 {
 _isRunningEvent.Set(); // 放行信号量
 }

 private void Worker()
 {
 while (!_cancellationTokenSource.Token.IsCancellationRequested)
 {
 _isRunningEvent.WaitOne(); // 等待信号量放行

 // 执行一些工作

 Thread.Sleep(50); // 适当休眠，避免 CPU 占用过高
 }
 }
}

上面的例子因为比较简单，所以并没有体现出使用 CancellationToken 的优势。实际上，有很多方法都可以接收一个 CancellationToken 参数。这样我们还可以通过传递它来实现停止在 Worker 方法中调用的长时间运行的其他任务；否则我们可能就只能在取消后等待这些任务的结束了。

优化使用消息队列的情形

除了上面的例子，我们还经常会遇到需要使用一个队列来实现生产者消费者模式的情况。比如下面这个例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


class MyService
{
 private readonly Queue<int> _queue = new Queue<int>();
 private readonly object _lock = new object();

 private volatile bool _shouldStop;
 private volatile bool _isRunning;

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunning = true;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 // 省略 Pause 和 Resume 方法的实现

 public void Enqueue(int item)
 {
 lock (_lock)
 {
 _queue.Enqueue(item);
 }
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 lock (_lock)
 {
 if (_queue.Count > 0 && _isRunning) // 也可以使用 TryDequeue
 {
 var item = _queue.Dequeue();
 // 处理 item
 }
 }

 Thread.Sleep(50); // 暂停时也要休眠，避免 CPU 占用过高
 }
 }
}

在上面的例子中，我们具体做了这样几件事情：

使用 Queue 来存储数据，并使用线程锁和 lock 语句来保证线程安全；
使用 _shouldStop 和 _isRunning 来控制线程的执行；
在 Worker 方法中使用 lock 来获取锁，并在队列不为空时获取传入的任务和进行处理；
暴露一个 Enqueue 方法来让生产者添加任务到队列中。

那么我们该如何优化这个例子呢？

用线程安全的集合类型

实际上，.NET 标准库中已经提供了线程安全的集合类型，比如 ConcurrentQueue<T>。它们可以在多线程环境中安全地使用，而不需要我们手动加锁。我们可以直接用它来替代上面的 Queue 和 lock 语句。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class MyService
{
 private readonly ConcurrentQueue<int> _queue = new ConcurrentQueue<int>();

 public void Enqueue(int item)
 {
 _queue.Enqueue(item);
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 if (_isRunning && _queue.TryDequeue(out var item)) // 也可以使用 TryDequeue
 {
 // 处理 item
 }

 Thread.Sleep(50); // 暂停时也要休眠，避免 CPU 占用过高
 }
 }
}

通过这样的方式，我们就不需要手动加锁了。ConcurrentQueue<T> 会自动处理线程安全的问题。

用信号量来取代标志位

上面的代码中，我们又用到了轮询。但是这个轮询本质上做的事情是等待队列中有数据可用。基于这一思路，我们可以考虑用一个只在有新数据到来时才放行一次的信号量——也就是 AutoResetEvent 来替代它。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


class MyService
{
 private readonly ConcurrentQueue<int> _queue = new ConcurrentQueue<int>();
 private readonly AutoResetEvent _queueEvent = new AutoResetEvent(false); // 初始是关闭的

 public void Enqueue(int item)
 {
 _queue.Enqueue(item);
 _queueEvent.Set(); // 放行信号量
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 _queueEvent.WaitOne(); // 等待信号量放行

 if (_isRunning && _queue.TryDequeue(out var item)) // 也可以使用 TryDequeue
 {
 // 处理 item
 }
 }
 }
}

但是这个例子并不好，因为如果同时来了多条数据，那么我们虽然会调用多次 Set，但是信号量只会放行一次。可就有可能出现数据处理不及时的情况。所以更好的方式是使用 Semaphore。它好比一扇宽度可变的大门。每次放行都会让门变宽一些，而不像是 AutoResetEvent 那样只有开和关这两种状态。不过这个例子我们就不演示了，因为我们有更好的方法。

用 `BlockingCollection` 来实现生产者消费者模式

实际上，.NET 中已经提供了一个现成的类来实现生产者消费者模式——BlockingCollection<T>。它是一个线程安全的集合类型，而且它还提供了阻塞和通知的功能。我们可以直接用它来替代上面的 ConcurrentQueue<T> 和 AutoResetEvent。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class MyService
{
 private readonly BlockingCollection<int> _queue = new BlockingCollection<int>();

 public void Enqueue(int item)
 {
 _queue.Add(item); // 添加数据到队列中
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 if (_isRunning && _queue.TryTake(out var item, Timeout.Infinite)) // 等待数据可用
 {
 // 处理 item
 }
 }
 }
}

这样，如果队列为空时，TryTake 会阻塞当前线程，直到有数据可用。当调用 Add 方法时，BlockingCollection<T> 会自动放行等待的线程。这样我们就不需要手动处理信号量了。

Info

其实通过观察 BlockingCollection<T> 的源代码，我们不难发现它在底层用到了 ConcurrentQueue<T> 和 SemaphoreSlim。此外，它底层使用的集合类型也是可变的，比如 ConcurrentStack<T> 和 ConcurrentBag<T> 等。我们可以通过传入不同的集合类型来实现不同的行为。

总结

在这篇文章中，我们探讨了如何用信号量等机制来替代轮询标志位的方式，从而实现线程间的通信和控制。我们使用了 ManualResetEvent、AutoResetEvent、CancellationToken 和 BlockingCollection<T> 等类来实现这些功能。通过这些类，我们可以更优雅地实现多线程编程，避免了轮询和标志位带来的问题。

大家在实际的开发中，也一定要多多关注这些现成的类和工具，而不是盲目地自己造轮子。

BSON 与 MessagePack 的异同及如何选择

Thu, 20 Mar 2025 00:00:00 +0000

BSON 与 MessagePack 是两种常见的二进制数据格式。他们都提供了序列化与反序列化功能，支持灵活的数据格式，也广泛地被各种编程语言所支持。但是它们之间有什么异同呢？它们的性能以及空间利用率如何呢？在实际应用中，我们又该如何选择呢？

基本信息

BSON（Binary JSON）是一种二进制编码的 JSON 格式，由 MongoDB 开发，主要用于 MongoDB 数据库中数据的存储和传输。它扩展了 JSON 格式，增加了对额外数据类型的支持，如日期、时间戳和二进制数据。

MessagePack 是一种高效的二进制序列化格式，旨在实现尽可能小的体积和尽可能快的处理速度。它支持多种编程语言，常用于网络通信和数据存储。

相同点

BSON 和 MessagePack 在多个方面具有相似之处。首先，它们都将数据编码为二进制形式，与基于文本的 JSON 相比，可以减小数据体积，提高传输效率。JSON 虽然具有可读性的优势，但在处理大量数据时，其文本特性会导致解析速度较慢，且占用更多的存储空间。而二进制格式则避免了这些问题，它们以计算机更容易处理的方式存储数据，从而提高了效率。

其次，它们都支持多种数据类型，包括基本类型（如整数、浮点数、字符串、布尔值）和复杂类型（如数组、二进制、日期等）。这使得它们可以灵活地处理各种数据结构，满足不同应用场景的需求。

此外，两者都提供了多种编程语言的实现，使得它们可以在不同的系统和平台之间进行数据交换。无论是使用 Python、Java、C#、Go，还是其他编程语言，我们都可以找到相应的库来使用它们。最后，它们都提供了高效的序列化和反序列化机制，使得开发者可以方便地进行数据的相关操作。

那么，同样都是二进制数据，它们是否都具备相当高的空间利用率以及性能呢？

不同点

然而，BSON 和 MessagePack 之间也存在一些关键的设计上的差异。这些差异导致了它们的空间利用率，以及各自所擅长的功能并不相同。

BSON 的设计目标是主要用于 MongoDB 的数据存储和传输，而不是为了提供一个 JSON 的上位替代。这种设计理念上的差异直接影响了它们在空间利用率和性能方面的表现。由于 BSON 包含一些额外的元数据（如字段长度等），因此其空间效率相对较低；而 MessagePack 使用紧凑的表示方式来编码数据，例如使用更少的字节来表示较小的整数，因此空间效率非常高。MessagePack 的设计哲学是“尽可能地小”，这使得它在对数据大小有严格要求的场景中成为理想的选择。

在性能方面，BSON 的序列化和反序列化速度相对较慢，而 MessagePack 的序列化和反序列化速度非常快。这是因为 MessagePack 的编码方式更加简单高效，减少了处理数据所需的计算量。然而，BSON 虽然效率相对较低，但它在 MongoDB 中有许多优化，例如在索引方面，BSON 的结构允许 MongoDB 高效地遍历和查询数据，这弥补了其在通用性能上的一些不足。具体来说，MongoDB 可以利用 BSON 中存储的字段长度等信息，快速定位到需要的数据，而不需要像解析 JSON 那样逐个字符地扫描。

代码对比

这里，我们在 C# 中用一个简单的例子来对比 BSON 和 MessagePack。我们使用 Newtonsoft.Json.Bson 和 MessagePack 这两个库来实现。

首先，我们设计一个包含一些属性的类，并且为它填充一些数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


public class MyModel
{
 public int Id { get; set; }
 public string Name { get; set; }
 public DateTime CreatedAt { get; set; }
 public bool IsActive { get; set; }
 public decimal Price { get; set; }
 public double Rating { get; set; }
 public Guid UniqueId { get; set; }
 public byte[] Data { get; set; }
 public List<string> Tags { get; set; }
 public Dictionary<string, int> Counts { get; set; }
 public long BigNumber { get; set; }
 public short SmallNumber { get; set; }
 public char Initial { get; set; }
 public TimeSpan Duration { get; set; }
 public Uri Website { get; set; }
 public Version Version { get; set; }
 public object DynamicValue { get; set; }
 public Status Status { get; set; }
}

public enum Status
{
 Pending,
 InProgress,
 Completed
}

var model = new MyModel
{
 Id = 123,
 Name = "My Model",
 CreatedAt = DateTime.UtcNow,
 IsActive = true,
 Price = 99.99m,
 Rating = 4.5,
 UniqueId = Guid.NewGuid(),
 Data = new byte[] { 1, 2, 3 },
 Tags = new List<string> { "tag1", "tag2" },
 Counts = new Dictionary<string, int> { { "a", 1 }, { "b", 2 } },
 BigNumber = 123456789012345,
 SmallNumber = 123,
 Initial = 'A',
 Duration = TimeSpan.FromMinutes(15),
 Website = new Uri("https://www.example.com"),
 Version = new Version(1, 0, 0),
 DynamicValue = new { Value = "dynamic" },
 Status = Status.InProgress
};

然后，我们用两种方法来序列化这个对象。首先是 BSON：

1
2
3
4
5
6
7
8
9


using Newtonsoft.Json;
using Newtonsoft.Json.Bson;

using (var fs = File.OpenWrite(@"bson.dat"))
using (var writer = new BsonWriter(fs))
{
 var serializer = new JsonSerializer();
 serializer.Serialize(writer, model);
}

然后是 MessagePack。这里为了序列化上述模型，我们还需要为模型类添加一些特性，包括：

为类添加 [MessagePackObject]
为每个属性依次添加 [Key(0)]、[Key(1)]、[Key(2)]……

否则序列化代码将会报错。这里，修改后的模型类（部分）及序列化代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


[MessagePackObject]
public class MyModel
{
 [Key(0)]
 public int Id { get; set; }
 [Key(1)]
 public string Name { get; set; }
 [Key(2)]
 public DateTime CreatedAt { get; set; }
 [Key(3)]
 public bool IsActive { get; set; }
 // ...
}

using (var fs = File.OpenWrite(@"msgpack.dat"))
{
 var data = MessagePackSerializer.Serialize(model);
 fs.Write(data);
}

然后，我们观察文件大小：

BSON：381 字节
MsgPack：166 字节

可以明显看出，BSON 在空间效率上完全没有优势。

Note

实际上，就算是对比 JSON，BSON 在空间效率上也未必会有显著的优势。BSON 的优势主要来自对日期、二进制数据、数字等的处理，而 JSON 只能全部以字符串的形式存储。对于 100,000,000 这样的大数字，JSON 需要 9 个字符，而 BSON 只需要 4 个字节；但对于 1.0 这样的小数，JSON 需要 3 个字符，而 BSON 只需要 8 个字节。不仅如此，BSON 还包含了额外的元数据，如字段名称、字段长度等，这也导致了 BSON 的空间效率并没有相较于 JSON 有多少提升。

总结

总而言之，BSON 和 MessagePack 都是优秀且现代的二进制序列化格式。BSON 的优势在于与 JSON 的兼容性和对丰富数据类型的支持，使得它在 MongoDB 等数据库应用中表现出色；MessagePack 的优势在于其高性能和高空间效率，这使得它在网络通信、大数据处理等需要快速传输和处理大量数据的场景中更有优势。在实际应用中，我们应当根据具体需求选择合适的格式。

为什么不试试 ReactiveUI 呢？

Wed, 12 Mar 2025 00:00:00 +0000

在去年，我制作了一期视频与大家探讨响应式编程（Reactive Programming）。在视频的结尾，我也“剧透”了自己或许会在将来的一天继续深入这个话题，与大家探讨使用 ReactiveUI（以下简称为“RxUI”）这个库来做符合 MVVM 模式的桌面应用。

但现在已经过去很久了，后续内容迟迟没有出现。这真的是一件尴尬的事情。事实上，这个话题可谓难度非常高，尤其是相较于其他 MVVM 框架（比如 CommunityToolkit.Mvvm、Prism 等）来说，它的入门难度极高。

最近看了一篇列在了 ReactiveUI 官方文档的“资源”中的博文：I have become a huge fan of ReactiveUI。有趣的是，当你点开这篇文章后，你会发现标题是“Don’t use ReactiveUI”。不过作者立刻在第一段就澄清了这只是一个颇具欺骗性的标题，实际上并不是想表达这个意思，作者是在说反话。

所以我的这篇文章也仿照这一点，起了一个颇具欺骗性的标题——是的，我也在说反话。现阶段我不推荐任何人使用 RxUI，尤其是现在有 CommunityToolkit.Mvvm 这样成熟且易上手的框架的情况下（我还专门写了一整个入门教程来和大家分享这个工具包的使用）。

为什么不推荐使用 RxUI？

那么为什么我不推荐使用 RxUI 呢？

如果你或你的团队选择了 RxUI 来进行开发，那么你将获得下面几个优势：

你的代码会看起来很酷；
你会获得新颖而不同寻常的开发体验；
你的代码会非常难以让新入职的同事接手，这会让你变得更加重要，也更难以被“优化”；
你会充分培养自己的自学能力——因为你几乎无法靠别人理清楚你到底在干什么。

是的，如果你选择了 RxUI，那么“you are on your own.”，甚至包括目前最聪明的几个大语言模型，比如 ChatGPT o3、Claude 3.7 Sonnet、Gemini 2.0 Pro、Grok 3、DeepSeek R1 等，也帮不了你。现在不能，将来应该也不能，因为它们的训练集里面并不充分包含这么一个技术。

可能有些开发者会说，RxUI 有你说的那么难吗？我觉得还好啊，不就是借助 RaiseAndSetIfChanged 这个方法来实现属性的通知，用 ReactiveCommand 来创建用于绑定 Command 的命令，最多再用 ObservableAsPropertyHelper（OAPH）来创建一个只读属性（或者说计算属性），就可以了啊？如果嫌麻烦，还可以借助 Fody，或者源生成器不是嘛。

如果你这样想，那么恭喜你，你可能只是刚刚入门，并且你的项目并不复杂，仅靠入门的这些知识就可以应付。如果你深入了解 RxUI，你会发现你要考虑的因素实在是太多了，并且很多时候你可能都不知道自己在做什么，该想什么，以及该如何判断某种做法的优劣。

不相信的话，不妨问自己这么几个问题：

你知道视图及视图模型的生命周期，以及什么时候该使用 WhenActivated 吗？
你知道哪些对象应当考虑资源回收的问题吗？
如果你不确定某个对象是否应该显式释放资源，你知道该如何去判断吗？
你知道 WhenAny、WhenAnyValue、WhenAnyObservable 这三个方法的区别以及触发时机吗？
你知道什么时候该使用 Bind、BindCommand 等方法而不是直接在 XAML 中绑定吗？
你知道 MessageBus、DynamicData 这些类的作用吗？
你知道如何处理可观测对象的异常吗？
你知道如何取消一个从可观测对象或异步任务创建的命令吗？
你知道如何正确搭配 IoC 容器来使用 RxUI 吗？你知道 RxUI 所依赖的 Splat 吗？
你熟悉响应式编程吗？

最后一个问题应该才是灵魂拷问。如果你没有拿下响应式编程的信心，那么我建议你还是先放弃 RxUI，并且也基本上不要指望可以一边学习 RxUI 一边入门响应式编程，因为响应式编程是一种思想，而这个思想在 RxUI 中只体现了一方面。但 RxUI 还需要学习的东西还有很多，比如如何遵循 MVVM 模式，如何正确使用依赖注入，如何管理视图的生命周期，如何在界面框架中去实现绑定等。如果你一边学习一边开发，那么很有可能随着你慢慢理解这一切，你会发现你之前写的代码是多么地糟糕。

当你度过重重困难，最终会得到什么？

好吧。假如你历经千辛万苦，终于熟练掌握了 RxUI，那么你会得到什么呢？或者说，如果你打一开始就选择了 CommunityToolkit.Mvvm，你会损失什么？

首先，你可以优雅地实现一个搜索框，这也是 RxUI 官方示例中经常展示的场景：用户输入文字，搜索结果实时更新，并能有效处理延迟、去重等复杂逻辑；此外，如果有一些属性及命令，它们之间的通知关系比较复杂，那么 RxUI 会让你的代码更加直观，好比于从大家的主动通知目标变成了目标去主动观察大家；更重要的是，你还入门了响应式编程这一个有趣的概念。

然而，这种便利并非毫无代价。你可能会为了掌握 RxUI 付出大量的时间和精力。更重要的是，你的代码库可能会变得难以维护，因为其中充斥着 RxUI 特有的 API 和概念。这些 API 本身就带有一丝“黑魔法”的色彩，可能会让团队中的其他成员，甚至未来的维护者感到困惑——掌握这门框架的人才，多吗？

遇到了困难，你去看官方文档，去问群友，去问大模型，恐怕都不会有太多的帮助。至少我并不认为，RxUI 这么复杂的框架，它的官方文档足够详尽和易懂，我也基本上找不到什么稍微深入一些的示例项目，更是几乎看不到有多少人在写关于 RxUI 的博客——那该如何指望大语言模型能够掌握这个技术呢？

但如果你选择了别的框架，那么相关的教程实在是太多了，毕竟 MVVM 教程多得是，无非就是了解一下框架的用法，它们的视图模型的基类是如何实现 INPC 接口，并提供了一些额外的辅助方法的，就差不多了。这么直白的学习路线，是 RxUI 所不拥有的，因为后者需要更多的背景知识。

哦对了，差点忘了一件事情：如果你选择了 RxUI，你还有可能获得一个“四不像”的项目。因为 RxUI 为了实现 MVVM，将整个响应式编程的概念引入到了项目中，但是这一概念一般情况下我们根本用不到。因此，很多人即便在自己的项目中使用了 RxUI，但是对于其他的业务逻辑，仍旧使用的是传统的思路，比如使用多线程加锁（好一点的用信号量，差一点的甚至还在用 bool 类型的标志位）、线程安全的队列、LINQ 甚至是 for 循环，而完全不考虑 Rx 提供的数据流这一概念。

此外，RxUI 还引入了 Splat 这个库，用于解决跨平台的问题（比如读取本地图片等），还提供了一套简单的 IoC 容器——不管你用到用不到，它都在那里。作为一个完美主义者，我非常不喜欢引入一个库，但是只用了一小部分功能这件事情。因此我更喜欢 CommunityToolkit.Mvvm，因为它只提供了 MVVM 的基础功能，我可以随意搭配其他我想用的 IoC 容器等（同理，我也并不怎么喜欢 Prism）。

因此，权衡利弊至关重要。如果你需要处理极其复杂的响应式场景，并且愿意投入大量时间和精力去学习和维护，那么 RxUI 或许是一个不错的选择；但如果你的项目复杂度适中，或者团队成员对响应式编程不熟悉，那么选择更易上手的框架可能更为明智。毕竟，技术的选择应该服务于项目的目标，而不是反过来。

我还打不打算讲 RxUI 了？

这是一个充满矛盾的问题。一方面，我写了这么多来“唱衰”RxUI，劝退新手，似乎已经给它判了“死刑”。那么，我还会继续深入讲解它吗？

我想，答案是肯定的。尽管入门门槛高，维护成本大，但 RxUI 终究是一门有趣的技术，一个有着十几年历史却依然“新颖”的框架，一个能将不畏挑战的开发者筛选出来的概念。能够攻克它，掌握它，并将经验分享给大家，这本身就是一件充满成就感的事情。

当然，这一天恐怕不会很快到来。首先，我对响应式编程本身的理解还需要进一步加深。其次，如果仅仅是重复介绍 RaiseAndSetIfChanged、ReactiveCommand、ObservableAsPropertyHelper 这些基础用法，那毫无意义。市面上并不缺乏这种级别的教程。真正有价值的，是解决前面提到的那些深层问题，帮助大家真正理解和掌握 RxUI 的精髓。否则，互联网上只会多出一篇平庸的“教程”，而不是一篇真正具有“教育意义”的文章。

所以，我真心期待有读者能在评论区“打脸”，分享你优秀的 RxUI 学习路线和实践经验。这不仅能让我受益，更能帮助所有对 RxUI 感兴趣的开发者。如果能看到更多人分享他们成功使用 RxUI 的案例，那将是对我观点最好的反驳，也是我最乐于见到的。毕竟，技术的世界，永远欢迎不同的声音和观点。

WPF 中的 ContentControl 及 ContentPresenter 有何异同？

Wed, 05 Mar 2025 00:00:00 +0000

标题中提到的 ContentControl 和 ContentPresenter 都是 WPF 中较为常见的显示内容的控件，它们有各自的用途。但有的时候，开发者可能会搞不清楚它们之间的区别，导致选错了控件（却往往又因为效果实现了而忽视这一问题）。本文将简单介绍一下这两个控件的异同。

二者的共同点

首先，我们来看一下 ContentControl 和 ContentPresenter 之间的共同点：

都包含一个 Content 属性；
都可以用作一个将要展示内容的容器或占位符；
默认情况下通常都没有什么样式，完全透明且空白，看起来十分轻量。

因此，当用于展示一个控件或内容时，它们看起来都可以胜任。比如：

1
2
3


<ContentControl>
 <Button Content="Hello, World!" />
</ContentControl>

或者我们还可以在资源词典中声明一个控件：

1
2
3
4
5


<Window.Resources>
 <Button x:Key="MyButton" Content="Hello, World!" x:Shared="False" />
</Window.Resources>

<ContentControl Content="{StaticResource MyButton}" />

Info

这里我们使用了 x:Shared="False" 来确保每次使用这个资源时都会创建一个新的实例。否则，如果我们在多个地方使用这个资源，那么这些地方的控件都会指向同一个实例，导致一些问题（比如只有一个控件正确显示）。

当然了，我们还可以在代码后台去动态设置 Content 属性，这里我们就不演示了。

二者的区别

但正是因为它们有着这样的相同点，因此经常会有开发者误用了它们两个。那么，它们之间的区别又是什么呢？

它们的基类不同

ContentControl 是 Control 的子类，而 ContentPresenter 是 FrameworkElement 的子类。

首先我们来看 FrameworkElement。它提供了一些最基本的界面元素应该有的属性，比如宽高、样式、布局等。Control 是它的子类，额外添加了控件需要的边框、前背景色、字体等，还有一个相当重要的属性 Template，用于定义控件的外观。

然后，在这些的基础上，ContentControl 继承了 Control，并添加了一个 Content 属性，用于存放要展示的内容。不仅如此，因为它拥有模板（以及模板选择器等），因此它可以根据一些因素选择合适的模板从而去展示内容，并且非常适合在运行时动态改变内容。此外，它的 Content 不仅可以是一个具体的控件，还可以是一个数据模型等（通常还可以是绑定得到的）。

另一方面，ContentPresenter 并不拥有 Control 所提供的那些属性，可以说是一个相当轻量的界面元素。它的主要使用场景就是在模板中，用于展示模板的内容。比如我们可以在一个 Button 的模板中使用 ContentPresenter 来展示按钮的内容：

1
2
3
4
5


<ContentTemplate x:Key="MyButtonTemplate" TargetType="Button">
 <Border>
 <ContentPresenter />
 </Border>
</ContentTemplate>

不仅如此，因为它太适合用在这个场景了，所以通常我们根本不需要去操作它的 Content 属性，因为它会自动绑定到模板的 Content 属性上。也就是说，我们不需要写 Content="{TemplateBinding Content}" 这样的代码。

Info

其实 ContentPresenter 的作用就是在模板中用来展示 Content，所以 ContentControl 及其子控件自然也都用到了它。如果你在一个模板中，错误地将 ContentControl 用在了应该用 ContentPresenter 的地方，并且手写了 Content 属性的绑定，那么你仍然有可能看到正确的效果。只是它底层依旧是借助了 ContentPresenter。

它们的功能不同

因为上面的原因，所以即便它们看起来（甚至简单使用起来）并没有什么区别，但是它们被设计出来的目的及作用是完全不一样的。

ContentControl 一般来说有这么几种用途：

用于展示一个控件或内容（可以理解为容器或占位符）；
用作控件的基类，可以被继承，从而实现一些自定义的控件；
用于动态改变内容，比如在运行时改变 Content 属性；
搭配 DataTemplate 使用，用于根据数据模型展示不同的内容（尤其适用于导航页面）。

对于第 4 点，这里有一个简单的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<ContentControl Content="{Binding CurrentPageViewModel}">
 <ContentControl.Resources>
 <DataTemplate DataType="{x:Type local:HomePage}">
 <local:HomePage />
 </DataTemplate>
 <DataTemplate DataType="{x:Type local:AboutPage}">
 <local:AboutPage />
 </DataTemplate>
 </ContentControl.Resources>
</ContentControl>

此时，虽然它的 Content 属性的值并不是一个控件，而是一个模型（Model），但是它会根据这个模型的类型自动选择合适的模板来展示内容。这样的话，只要我们给它提供视图模型（ViewModel），它就可以自动选择相应的视图（View）来展示，并且还会自动将 View 的 DataContext 设置为 Content 的值。

而 ContentPresenter 一般来说只有一种用途，那就是用在 ControlTemplate 中。类似的，还有一个 ItemsPresenter，用于在 ItemsControl （及其子控件，如 ListBox 等）的模板中展示子项。如果你在一个需要使用 ContentControl 的地方使用了 ContentPresenter，那么你不仅没有办法操作 Template 或提供 DataTemplate 来展示数据，而且还将没有办法操作一些最基本的 Control 的属性，比如前景色、背景色、字体等。

总结

深入了解 ContentControl 和 ContentPresenter 的区别，可能显得有些繁琐。其实大家基本上只需要记住，ContentPresenter 几乎只用于模板中，其余情况下都可以使用 ContentControl 即可。

让合适的控件做合适的事情，这样才有助于我们开发出更加清晰、稳健、易维护的代码。

WPF 中 ObjectDataProvider 的一些有趣用法

Fri, 07 Feb 2025 00:00:00 +0000

WPF 中的 ObjectDataProvider 是一个很有用的类。与常见的直接绑定到属性（包括控件的依赖属性、类的实例的属性、静态属性或字段等）不同的是，它可以通过调用构造函数的方式来创建对象，或调用对象的方法来获取数据，进而将其用作绑定的数据源。

这篇文章我们就来探讨一下它的一些实用而有趣的用法。

基本用法

创建对象

首先，我们来看一下最基本的用法：通过 ObjectDataProvider 来创建一个对象。比如我们有一个 Person 类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class Person
{
 public string Name { get; set; }
 public int Age { get; set; }

 public Person(string name, int age)
 {
 Name = name;
 Age = age;
 }
}

如果 Person 提供了无参构造函数，那么我们可以用传统的方式直接实例化一个对象：

1
2
3


<Window.Resources>
 <local:Person x:Key="PersonObject" Name="Tom" Age="25" />
</Window.Resources>

但现在我们假设 Person 类只提供了有参构造函数，那么我们就无法直接实例化一个对象了。这时，我们可以通过 ObjectDataProvider 来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<Window ...>
 <Window.Resources>
 <ObjectDataProvider x:Key="PersonObject" ObjectType="{x:Type local:Person}">
 <ObjectDataProvider.ConstructorParameters>
 <sys:String>John</sys:String>
 <sys:Int32>25</sys:Int32>
 </ObjectDataProvider.ConstructorParameters>
 </ObjectDataProvider>
 </Window.Resources>
 <Grid>
 <TextBlock Text="{Binding Name, Source={StaticResource PersonObject}}" />
 <TextBlock Text="{Binding Age, Source={StaticResource PersonObject}}" />
 </Grid>
</Window>

这里我们通过 ObjectType 属性指定了 Person 类型，通过 ConstructorParameters 属性传入了构造函数的参数。这样我们就成功地创建了一个 Person 对象，并将其绑定到了两个 TextBlock 控件上。

调用方法

除了创建对象，ObjectDataProvider 还可以调用对象的方法。比如我们有一个 Calculator 类：

1
2
3
4
5
6
7


public class Calculator
{
 public int Add(int a, int b)
 {
 return a + b;
 }
}

我们可以通过如下方式调用 Add 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Window ...>
 <Window.Resources>
 <ObjectDataProvider x:Key="CalculatorObject" ObjectType="{x:Type local:Calculator}" MethodName="Add">
 <ObjectDataProvider.MethodParameters>
 <sys:Int32>10</sys:Int32>
 <sys:Int32>20</sys:Int32>
 </ObjectDataProvider.MethodParameters>
 </ObjectDataProvider>
 </Window.Resources>
 <Grid>
 <TextBlock Text="{Binding Source={StaticResource CalculatorObject}}" />
 </Grid>
</Window>

上面的方式会自动创建一个 Calculator 对象，并调用其 Add 方法，传入了两个参数。我们还可以将 Calculator 类及其成员声明为静态的，这样就可以避免创建对象了。

Info

如果 ObjectType 指定的类型不是静态的，那么即便我们要访问的属性或方法是静态的，ObjectDataProvider 也会自动创建一个对象。这一现象可以在运行时通过观察该资源的 ObjectInstance 属性来验证。

给定实例

除了指定 ObjectType 属性外，我们还可以通过 ObjectInstance 属性来指定一个实例。比如我们上面的 Calculator 类提供了单例模式的实现：

1
2
3
4
5
6


public class Calculator
{
 public static Calculator Instance { get; } = new();

 // ...
}

那么我们可以通过如下方式调用 Add 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Window ...>
 <Window.Resources>
 <ObjectDataProvider x:Key="CalculatorObject" ObjectInstance="{x:Static local:Calculator.Instance}" MethodName="Add">
 <ObjectDataProvider.MethodParameters>
 <sys:Int32>10</sys:Int32>
 <sys:Int32>20</sys:Int32>
 </ObjectDataProvider.MethodParameters>
 </ObjectDataProvider>
 </Window.Resources>
 <Grid>
 <TextBlock Text="{Binding Source={StaticResource CalculatorObject}}" />
 </Grid>
</Window>

当我们指定了 ObjectInstance 属性后，就不需要再指定 ObjectType 属性了。

工厂模式

还有一个经典用法是，我们可以结合工厂模式来在 XAML 中创建对象。比如我们有一个 PersonFactory 类：

1
2
3
4
5
6
7


public class PersonFactory
{
 public Person CreatePerson(string name, int age)
 {
 return new Person(name, age);
 }
}

我们可以通过如下方式创建一个 Person 对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<Window ...>
 <Window.Resources>
 <ObjectDataProvider x:Key="PersonFactory" ObjectType="{x:Type local:PersonFactory}" MethodName="CreatePerson">
 <ObjectDataProvider.MethodParameters>
 <sys:String>John</sys:String>
 <sys:Int32>25</sys:Int32>
 </ObjectDataProvider.MethodParameters>
 </ObjectDataProvider>
 </Window.Resources>
</Window>

这样便为 XAML 注入了更多的活力与灵活性。

经典用法

绑定枚举类型到下拉选单

相信所有和 ComboBox 控件打过交道的开发者都知道，如果我们希望将一个枚举类型的值绑定到 ComboBox 控件上，我们可以通过 ObjectDataProvider 来实现。

比如我们有一个 Fruit 枚举类型：

1
2
3
4
5
6
7


public enum Fruit
{
 Apple,
 Banana,
 Orange,
 Pear
}

我们可以通过如下方式将其绑定到 ComboBox 控件上：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<Window ...>
 <Window.Resources>
 <ObjectDataProvider x:Key="FruitEnumValues" MethodName="GetValues" ObjectType="{x:Type sys:Enum}">
 <ObjectDataProvider.MethodParameters>
 <x:Type TypeName="local:Fruit"/>
 </ObjectDataProvider.MethodParameters>
 </ObjectDataProvider>
 </Window.Resources>
 <Grid>
 <ComboBox ItemsSource="{Binding Source={StaticResource FruitEnumValues}}" />
 </Grid>
</Window>

这里其实就体现了对于类型方法的调用。首先，我们知道在 C# 中，可以通过这样的方式来获取枚举类型的所有值：

1

var values = Enum.GetValues(typeof(Fruit));

也就是我们调用了 Enum 类型的 GetValues 静态方法，并传入了 Fruit 类型（Type），从而获取所有的枚举值。而在 XAML 中，我们就是借助 ObjectDataProvider 来实现了相同的操作。我们通过 ObjectType 属性指定了 Enum 类型，通过 MethodName 属性指定了 GetValues 方法，再通过 MethodParameters 属性传入了 Fruit 类型。

为下拉选单提供整数数据源

借鉴上面的思路，我们很容易产生更多的想法：既然它可以调用任何类型的方法，那么 LINQ 的 Enumerable 上面的一些静态方法岂不也能为我们所用了？

那么我们就赶快来试一试吧。我们假如我们想给一个 ComboBox 添加几个连续的数字作为它的选项（比如 1~5），在代码后台我们会这样调用：

1

var numbers = Enumerable.Range(1, 5);

那么在 XAML 中，我们可以这样实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Window xmlns:linq="clr-namespace:System.Linq;assembly=netstandard">
 <Window.Resources>
 <ObjectDataProvider x:Key="Numbers" MethodName="Range" ObjectType="{x:Type linq:Enumerable}">
 <ObjectDataProvider.MethodParameters>
 <sys:Int32>1</sys:Int32>
 <sys:Int32>5</sys:Int32>
 </ObjectDataProvider.MethodParameters>
 </ObjectDataProvider>
 </Window.Resources>
 <Grid>
 <ComboBox ItemsSource="{Binding Source={StaticResource Numbers}}" />
 </Grid>
</Window>

是不是很有意思呢？

总结

ObjectDataProvider 是一个非常有用的类，它可以帮助我们在 XAML 中实现更多的功能。通过调用构造函数或对象的方法，我们可以实现更多的数据绑定操作。在实际开发中，我们可以根据具体的需求，灵活地使用 ObjectDataProvider，从而提高开发效率。

不过，好用归好用，它或许并不总是最优解。如果我们可以借助 ViewModel 中的成员，或 MarkupExtension 等方式来实现，那么我们一般就可以不考虑使用 ObjectDataProvider 了。毕竟，ObjectDataProvider 声明起来还是显得有些繁琐，而且因为借助反射，我们在编译时也可能无法发现一些潜在的问题。

为什么用户密码需要加盐哈希后再存储？

Thu, 23 Jan 2025 00:00:00 +0000

我们常说，密码不能明文存储在数据库中，而是应当哈希后存储。尤其我们还要对密码进行加盐处理。这样做的目的及必要性是什么呢？在 C# 中又该如何实现呢？这篇文章我们就来探讨一下。我们将从最不安全到最安全，逐步讲解为什么要这样做。

明文存储

首先我们就来看一看最不安全的方式吧：

1
2
3
4
5
6


class User
{
 public int Id { get; set; } // 自增主键
 public string Username { get; set; }
 public string Password { get; set; } // 明文密码
}

然后我们去创建一个用户：

1
2
3
4
5


var user = new User
{
 Username = "admin",
 Password = "123456"
};

那么现在，数据库中存储的就是用户的明文密码了。这样其实是非常危险的。

假如是本地的如 SQLite 数据库，那么只要有人能够访问到数据库文件，或通过反编译等方式获取到了连接字符串，那么就可以直接看到用户的密码；
假如是远程的数据库，那么黑客依旧有多种方式可以获取到数据库的数据，比如 SQL 注入、SSH 密钥泄露、数据库备份文件泄露、其他服务器漏洞等等。

明文的密码可以说是相当不应该被泄露的。它不仅可能包含了用户的私密信息以及使用习惯，还可以被黑客直接用来撞库（即通过泄露的密码尝试登录其他网站）。所以我们应当在任何情况下避免明文存储密码。

哈希存储（MD5 / SHA1）

下面我们稍微升级一下我们的代码，改为存储使用 MD5 或 SHA1 哈希后的密码：

1
2
3
4
5
6


class User
{
 public int Id { get; set; } // 自增主键
 public string Username { get; set; }
 public string PasswordHash { get; set; } // 密码哈希
}

然后为了方便开发，我们再写一个密码辅助类，用来进行密码哈希及验证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class PasswordHelper
{
 public static string HashPassword(string password)
 {
 using var md5 = MD5.Create();
 var hash = md5.ComputeHash(Encoding.UTF8.GetBytes(password));
 return Convert.ToBase64String(hash);
 }

 public static bool VerifyPassword(string password, string passwordHash)
 {
 return HashPassword(password) == passwordHash;
 }
}

在这个方法中，我们使用 MD5 算法对密码进行哈希，并最终转换为 Base64 字符串。在验证密码时，我们只需要再次哈希输入的密码，然后与数据库中的密码哈希进行比较即可。

Info

为什么我们通常会将密码转为 Base64 字符串再进行存储，而不是直接存为比如 BLOB 呢？这是因为 Base64 字符串是可读的，方便我们在数据库中查看。不仅如此，字符串的索引的效率也比 BLOB 更高。

在后面的方法中，我们还会看到一些哈希后的密码本身就是可读字符串的方法。所以通常我们会将密码哈希转为字符串进行存储。

此时我们保存的密码可能形如：

ISMvKXpXpadDiUoOSoAfww==

现在这个密码看起来显然比明文要安全多了。但很可惜，在黑客看来，这样的密码恐怕并没有安全太多，因为有一招叫做彩虹表攻击。简单来说，黑客可以提前生成一张巨大的彩虹表，里面包含了常见密码的哈希值。然后黑客只需要将数据库中的哈希值与彩虹表中的哈希值进行比对，就可以很快地找到密码。

比如上面的密码，对应的明文是 admin。黑客只需要在彩虹表中找到对应的哈希值，就可以轻松破解密码了。可不要小看这个彩虹表，它通常包含巨量的常见密码，甚至是所有可能的密码组合。所以，除非你的密码比较复杂（比如包含大小写、数字及符号），否则可能就会被彩虹表轻易破解。

不仅如此，MD5 和 SHA1 算法本身也是不安全的。它们已经被证明是可以被碰撞的。所谓碰撞，就是两个不同的输入可以生成相同的哈希值。这样的话，黑客就可以通过碰撞来破解密码了。以上述例子来说，虽然黑客可能无法通过彩虹表得知我们的明文是 admin，但是他通过计算发现，qwerty 同样可以生成相同的哈希值，那么他就可以用 qwerty 来登录了。毕竟服务器端的校验只会比对哈希值，而不会比对明文。

使用 SHA256 加盐

那么，我们只好进一步升级我们的算法了。这次我们使用能够防止碰撞的 SHA256（它是 SHA-2 系列中的一种，其他常见的还有 SHA-384、SHA-512 等）算法，并且加入一个随机的盐值：

1
2
3
4
5
6
7


class User
{
 public int Id { get; set; } // 自增主键
 public string Username { get; set; }
 public string PasswordHash { get; set; } // 密码哈希
 public string Salt { get; set; } // 盐值
}

然后，我们修改一下 PasswordHelper 类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class PasswordHelper
{
 public static string HashPassword(string password, byte[] salt)
 {
 var passwordBytes = Encoding.UTF8.GetBytes(password);
 var combinedBytes = new byte[passwordBytes.Length + salt.Length];
 Array.Copy(passwordBytes, 0, combinedBytes, 0, passwordBytes.Length);
 Array.Copy(salt, 0, combinedBytes, passwordBytes.Length, salt.Length);
 var hash = SHA256.HashData(combinedBytes);
 return Convert.ToBase64String(hash);
 }

 public static bool VerifyPassword(string password, string passwordHash, byte[] salt)
 {
 return HashPassword(password, salt) == passwordHash;
 }
 
 public byte[] GenerateSalt()
 {
 return RandomNumberGenerator.GetBytes(16); // 一般 16 字节（256 位）的盐值即可
 }
}

Tip

在较新版本的 .NET 中，我们可以使用很多便利的静态方法，比如 SHA256.HashData，RandomNumberGenerator.GetBytes 等，而不需要我们先创建实例。

在以前，大家可能会见过使用 RNGCryptoServiceProvider 来生成随机数的方法。但是该方法现在已经过时。

在这个方法中，我们将密码和盐值合并后再进行哈希。这样，即使两个用户的密码相同，由于盐值不同，最终的哈希值也会不同。这样就避免了碰撞的问题。

此外，盐值也是需要存储在数据库中的。这样，在进行密码校验时，会根据用户的 Id 或 Username 从数据库中取出盐值及加盐哈希后的密码，然后再将用户输入的密码使用相同的盐值进行哈希，最后与数据库中的密码进行比对，从而判断密码是否正确。

这样的密码存储方式，即使黑客拿到了数据库，也无法直接破解密码。因为彩虹表攻击现在已经不再有效，毕竟每个用户都有不同的盐值。

使用 PBKDF2

SHA256 加盐的方式已经相当安全了，但是我们还可以进一步提升安全性。因为黑客虽然无法使用彩虹表，但仍然可以尝试暴力破解密码。简单来说，黑客可以尝试使用各种密码组合，然后通过哈希后的密码与数据库中的密码进行比对，从而破解密码。

所以，为了提高密码被暴力破解的难度，之后我们要考虑的方案基本上就是围绕着提高计算的速度来展开。首先，我们可以考虑使用 PBKDF2 算法。这个算法在很多编程语言的标准库中均有提供。在 C# 中，我们可以使用 Rfc2898DeriveBytes 类来实现。我们只需要稍加修改我们的 PasswordHelper 类即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class PasswordHelper
{
 public static string HashPassword(string password, byte[] salt)
 {
 using var pbkdf2 = new Rfc2898DeriveBytes(password, salt, 10000, HashAlgorithmName.SHA256); // 迭代 10000 次
 return Convert.ToBase64String(pbkdf2.GetBytes(32)); // 32 字节（256 位）的哈希值
 }

 // 其他方法不变
}

Info

Rfc2898 是 PBKDF2 的一个实现，所以这里可以说是一回事，只是名字不同。另外，Rfc2898DeriveBytes 的构造函数中，我们需要给定使用的哈希算法，否则不包含这一传参的构造函数会提示已过时。

在这个方法中，我们使用 Rfc2898DeriveBytes 类来进行密码哈希。我们可以指定迭代次数，这样就可以提高计算的速度。一般来说，迭代次数越多，计算的速度就越慢，黑客破解密码的难度就越大。但是，迭代次数也不能太多，否则会影响用户登录的速度。一般来说，10000 次迭代是一个比较合适的值。

有了这一算法的加持，现在黑客想要暴力破解，需要付出的代价就会大大增加。

使用 BCrypt 和 Argon2

但可惜的是，道高一尺，魔高一丈。PBKDF2 算法虽然提高了黑客暴力破解密码的难度，但是仍然有一些问题。比如，黑客可以使用 GPU 或 FPGA 来加速计算，从而提高暴力破解的速度。所以，我们还有更加重量级的选手：BCrypt 及 Argon2。

我们先来看 BCrypt。在 C# 中，我们可以使用 BCrypt.Net-Next 库来实现 BCrypt 算法。我们只需要稍加修改我们的 PasswordHelper 类即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class PasswordHelper
{
 public static string HashPassword(string password)
 {
 return BCrypt.Net.BCrypt.HashPassword(password, 12); // 12 为工作因子
 }

 public static bool VerifyPassword(string password, string passwordHash)
 {
 return BCrypt.Net.BCrypt.Verify(password, passwordHash);
 }
}

并且我们的 User 类也可以去掉 Salt 属性了。这是为什么呢？因为 BCrypt 算法本身就包含了盐值，相当于替我们代劳了。这样，我们就不需要再自己生成盐值，也不需要专门去存储盐值了。

我们看一个 BCrypt 哈希后的密码：

$2a$11$lraBT1/lH3RiFXjQbywREutDElnBFaolPOEsDAvo1sjK2iRjwCAUi

这段文本中， $2a$ 表示使用的是 BCrypt 算法，11 表示工作因子，而后面的内容则是由盐值和哈希后的密码组成。也就是说，这段文本中包含了全部用来验证密码的信息，我们只需要将其存储在数据库中即可。

Info

工作因子是用来控制计算的速度的，它是 $2$ 的幂运算。比如，上面的密码就对应了 $2^{11}=2048$ 次计算。工作因子越大，计算的速度就越慢，黑客破解密码的难度就越大。通常 $10$ 到 $12$ 是一个比较合适的范围。

但黑客依旧不甘心，还是打算借助其强大的硬件来尝试破解。这样，我们就要请出我们的杀手锏：Argon2 算法了。

与 BCrypt 一样，Argon2 同样没有 .NET 标准库的实现。我们可以选择一些第三方的库，比如 Konscious.Security.Cryptography。

这里，我们不演示实际在 C# 中该如何使用 Argon2 算法，因为它与 BCrypt 在开发体验及数据模型和表的设计上是类似的。但是，Argon2 算法在安全性上要比 BCrypt 更胜一筹。它引入了更多防止黑客暴力破解的机制，比如内存硬化、并行计算等。它可以轻易调整破解的时间、内存成本以及并行度。

另外，Argon2 还提供了三种变体：Argon2d、Argon2i 和 Argon2id。其中，Argon2d 适用于对抗时间攻击，Argon2i 适用于对抗侧信道攻击，而 Argon2id 则是两者的结合。具体来说：

Argon2d 更注重防止 GPU 并行计算的攻击。
Argon2i 更注重抗侧信道攻击。
Argon2id 是综合了这两种特性，适合一般用途。

相信有了这么“变态”的密码哈希算法，至少现阶段的黑客是彻底束手无策了。

总结

在这篇文章中，我们从最不安全的明文存储密码开始，逐步讲解了为什么我们需要对密码进行加盐哈希。我们看到了明文存储密码的危险性，哈希后的密码可能被彩虹表攻击的问题。以及老旧的哈希算法可能存在的被碰撞的问题。然后，我们介绍了 SHA256 加盐、PBKDF2、BCrypt 和 Argon2 等算法，以及它们的优缺点。

在实际开发中，我们应当根据自己的需求和安全性要求来选择适合的密码哈希算法。对于一般的小项目来说，SHA256 加盐已经足够安全了，而且它对于客户端及服务端开销的要求也很低。但是，如果我们对安全性要求很高，那么 BCrypt 或 Argon2 就是不二之选了。

如何在 WPF 中高效布局多行多列的控件

Thu, 26 Dec 2024 00:00:00 +0000

这次我们来探讨一个 WPF 中的简单而又不简单的布局问题：如何实现下图中的效果？

为什么说这个问题简单而又不简单呢？是因为单纯只是实现这个效果的话，我们完全可以使用 Grid 控件来实现。~~甚至如果完全不在乎优雅的话，我们还可以用 Canvas 来实现~~（当然这几乎在任何情况下都是不推荐的）。但是，实际这样干过的开发者相信都很清楚，使用 Grid 的实现方式几乎可以说是毫无灵活性的。很快就会被后续的界面微调的需求整得焦头烂额。

那么我们今天就来看一看，这样的需求通常有哪些做法吧。希望这篇文章中提到的某些方式能够帮助到你。

最传统的方式：Grid

在介绍后面的更好的方式之前，我们有必要先来看一看最传统的方式：使用 Grid 控件。这样才能更好地分析这种方式的局限性，以及思考改进的方向。

这样的方式相信所有具备基本 WPF 基础的开发者都相当熟悉：

在 XAML 中定义一个 Grid 控件
在 Grid 中定义多个 RowDefinition 和 ColumnDefinition
在 Grid 中定义多个控件，并通过 Grid.Row 和 Grid.Column 来指定控件的位置
（可选）通过 Grid.RowSpan 和 Grid.ColumnSpan 来指定控件的跨行和跨列

好，然后我们就开始写 XAML 吧：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto" />
 <RowDefinition Height="Auto" />
 <RowDefinition Height="Auto" />
 <RowDefinition Height="Auto" />
 </Grid.RowDefinitions>
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="Auto" />
 <ColumnDefinition Width="Auto" />
 </Grid.ColumnDefinitions>

 <Label Grid.Row="0" Grid.Column="0" Content="1" />
 <TextBox Grid.Row="0" Grid.Column="1" />
 <Label Grid.Row="1" Grid.Column="0" Content="2" />
 <TextBox Grid.Row="1" Grid.Column="1" />
 <!-- ... -->
</Grid>

好的，马上痛苦面具就戴上了：为每个控件写 Grid.Row 和 Grid.Column，简直就是顶级折磨。如果你搞了十几行，结果被告知需要删掉前面某一行，或者在前面添加一行，那就更是欲哭无泪了。

Tip

可能会有聪明的同学想到一些简化这一步骤的方式，比如使用 Style 来统一指定上面的 TextBox 控件的 Grid.Column，并省略 Label 的 Grid.Column="0"。但这样依旧存在相当多的局限性，毕竟它最怕的就是例外情况了。

所以，我们显然是不能满足于使用这样的方式的。那究竟有什么更好的方式呢？

外层使用 UniformGrid

说起“自动化布局”，相信很多人在使用 Grid 时都垂涎过 UniformGrid 的功能，因为它可以让所有子控件依次填充到每个单元格中。所以，我们或许可以借助它的这一效果。比如我们想要一个两列的网格，可以：

1
2
3
4
5
6


<UniformGrid Columns="2">
 <Label Content="1" />
 <TextBox />
 <Label Content="2" />
 <TextBox />
 <!-- ... -->

但这样的局限性在于，所有子控件的大小（或者它们所处的单元格）都是完全等大的。这可能会失去灵活性，并且看起来有些呆板。那么我们还可以部分借助 UniformGrid 的功能，比如下面这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<UniformGrid Columns="1">
 <UniformGrid.Resources>
 <Style TargetType="StackPanel">
 <Setter Property="Orientation" Value="Horizontal" />
 </Style>
 <Style TargetType="Label">
 <Setter Property="Width" Value="50" />
 </Style>
 </UniformGrid.Resources>
 <StackPanel>
 <Label Content="1" />
 <TextBox />
 </StackPanel>
 <StackPanel>
 <Label Content="2" />
 <TextBox />
 </StackPanel>
 <!-- ... -->
</UniformGrid>

这里我们将每一行的内容放在了一个 StackPanel 中，从而让 Label 和 TextBox 出现在同一行（或者说 UniformGrid 的同一个单元格中）。这样我们就不需要再为每个控件指定 Grid.Row 和 Grid.Column 了。

为了更加简化代码，我们还声明了两个 Style，分别用于设置 StackPanel 的 Orientation 和 Label 的 Width。这样我们就可以在 StackPanel 中直接放置 Label 和 TextBox，而不需要再为 Label 设置宽度了。

但是这样做有一个明显的局限性：行高是一致的。如果我们需要不同行的高度不一致，那么这种方式就无法满足需求了。

外层使用 StackPanel

为了突破上一个方式的局限性，我们可以考虑使用 StackPanel 来替代 UniformGrid。这样我们就可以为每一行的 StackPanel 设置不同的高度了。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<StackPanel Orientation="Vertical">
 <StackPanel.Resources>
 <!-- Styles -->
 </StackPanel.Resources>
 <StackPanel Height="40">
 <Label Content="1" />
 <TextBox />
 </StackPanel>
 <StackPanel Height="50">
 <Label Content="2" />
 <TextBox />
 </StackPanel>
 <!-- ... -->
</StackPanel>

但很快，我们又会被别的问题所折磨：如何高效地设置行间距？

而且可能还有另外一个小折磨：因为内外都使用了 StackPanel，所以写的 Style 可能会被它们共同使用。

Info

针对这一问题，可能有同学会将内部的 StackPanel 替换为 WrapPanel，但这样并不是一个好主意，因为 WrapPanel 会让每一行的控件都尽可能地靠左对齐，并且在宽度不够时会自动换行！或许现在看着还好，但调整了窗口或父控件的尺寸，甚至修改了分辨率及缩放后，都有可能让你的界面变得一团糟。

此时，我们可以请个“外援”。其实在 Win UI 3、Avalonia UI 等框架中，StackPanel 天生就比 WPF 多了一个属性：Spacing。这个属性可以让我们很方便地设置行间距。但是在 WPF 中，我们就没有这么幸运了。不过，我们可以借助自定义控件来实现这一功能。

代码也不用我们自己写，网上可以找到一些开源实现。比如这里我贴两个供大家参考：

假如我们搬运到了 local 命名空间下，那么我们就可以这样使用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<local:StackPanel Spacing="10">
 <local:StackPanel.Resources>
 <Style TargetType="StackPanel">
 <Setter Property="Orientation" Value="Horizontal" />
 </Style>
 </local:StackPanel.Resources>
 <StackPanel>
 <Label Content="1" />
 <TextBox />
 </StackPanel>
 <StackPanel>
 <Label Content="2" />
 <TextBox />
 </StackPanel>
 <!-- ... -->
</local:StackPanel>

这样看起来就方便多了。此外，我们还有一些小技巧，来进一步提高布局的效率：

为 Label 设置一个固定的宽度，这样可以让所有的 Label 对齐
为 Label 设置 VerticalAlignment 或 VerticalContentAlignment 为 Center，这样可以让 Label 和 TextBox 垂直居中对齐
为 TextBox 等控件（还比如 CheckBox、ComboBox 等）设置固定的宽度，这样可以让所有的 TextBox 对齐

使用更高级的 Grid

上面的方式其实已经相当灵活了，尤其是对于可能需要增删、调换顺序之类的情形。但是可能仍然会觉得不够爽，因为里面多出了一层 StackPanel，这写起来就还是会觉得不太爽。

所以，有没有办法让 Grid 更加智能一点，比如可以像是 WrapPanel 或者 UniformGrid 那样，自动填充控件呢？

答案当然是有的。这里给大家推荐一个 NuGet 包：WpfAutoGrid。这个 AutoGrid 就正是我们梦寐以求的控件。

Info

NuGet 上有好多个叫这个名字的包。这里我贴一个自己试过的：WpfAutoGrid.Core

它的使用也非常简单：

1
2
3
4
5
6
7


<local:AutoGrid Columns="100,150" RowCount="8" RowHeight="30">
 <Label Content="1" />
 <TextBox />
 <Label Content="2" />
 <TextBox />
 <!-- ... -->
</local:AutoGrid>

这样我们连内部的 StackPanel 都不需要了，直接将 Label 和 TextBox 放在 AutoGrid 中即可。此外，它提供了很多实用的属性，比如上面实用的 Columns、RowCount、RowHeight，还有 ColumnSpacing、RowSpacing 等。不仅如此，AutoGrid 还能正确响应子控件 ColumnSpan 等属性，可以让我们更加灵活地布局控件。

除此之外，这里我再贴一个我自己写的 GridAssist。它是一个附加属性，可以直接用于原生的 Grid 控件。使用这个附加属性，就能够自动为子控件添加 Grid.Row 和 Grid.Column 属性。

BYJRK/GridAssist

使用方式也非常简单：

1
2
3
4
5
6
7


<Grid local:GridAssist.AutoRowColumn="_,2">
 <Label Content="1" />
 <TextBox />
 <Label Content="2" />
 <TextBox />
 <!-- ... -->
</Grid>

这个附加属性的 AutoRowColumn 填写的 _,2 意思是，行数自动增加，列数固定为 2（还可以写 _,2,Auto，从而将列宽设置为 Auto）。这样我们就不需要为每个控件指定 Grid.Row 和 Grid.Column 了。然后，我们只需要将子控件按照从上到下，从左到右的顺序放置即可，不需要再引入一层 StackPanel 了。此外，它也是可以正确响应 Grid.ColumnSpan 的。

总结

在 WPF 中，布局是一个非常重要的问题。而对于多行多列的控件布局，我们可以使用 Grid、UniformGrid、StackPanel、AutoGrid 等控件或者附加属性来实现。每一种方式都有它的优势和局限性，我们可以根据实际情况来选择最适合的方式。

另外，对于上面提到的几种自定义控件或附加属性，我们完全可以直接将代码复制到自己的项目中，然后根据实际需求进行修改。这样可以更好地适应自己的项目，也可以更好地理解这些控件或属性的实现原理，还可以省去引入第三方库的麻烦。

WPF 值转换器（ValueConverter）的一些实用技巧

Wed, 18 Dec 2024 00:00:00 +0000

本篇文章对应的教学视频链接：WPF中值转换器（ValueConverter）的一些实用技巧

在 WPF 中，值转换器（ValueConverter）是一个非常重要的概念。它可以帮助我们在绑定数据时，将数据转换成我们需要的格式。在这篇文章中，我们将介绍一些值转换器的实用技巧。

使用 WPF 内置的值转换器

WPF 内置了几个常用的值转换器，我们可以直接使用。例如，我们可以使用 BooleanToVisibilityConverter 将布尔值转换成 Visibility 枚举值。

1
2
3
4
5
6
7
8


<Window.Resources>
 <BooleanToVisibilityConverter x:Key="BooleanToVisibilityConverter"/>
</Window.Resources>

<StackPanel>
 <CheckBox x:Name="checkBox" Content="Show Text" IsChecked="True"/>
 <TextBlock Text="Hello, World!" Visibility="{Binding ElementName=checkBox, Path=IsChecked, Converter={StaticResource BooleanToVisibilityConverter}}"/>
</StackPanel>

遗憾的是，WPF 内置的值转换器并不是很多，基本上我们能直接用上的就是上面提到的这个 BooleanToVisibilityConverter。其他虽然有一些照理说用得上的值转换器，但它们很多都是 internal 的，我们无法直接使用。即便如此，通过阅读它们的源代码，我们仍然可以学习一下它们的实现方式。比如：

将值转换器声明为单例

使用值转换器有些是否会让人觉得繁琐，因为通常这意味着我们需要在某个控件的 Resources 中声明一个值转换器，并在需要的地方通过 StaticResource 来引用它。但实际上，我们可以将值转换器声明为单例，这样就可以在任何地方直接使用它。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public class BooleanToVisibilityConverter : IValueConverter
{
 // 单例模式
 public static BooleanToVisibilityConverter Instance { get; } = new();

 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 // ...
 }

 public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 {
 // ...
 }
}

然后我们就可以在 XAML 中借助 x:Static 来直接使用这个单例：

1
2
3
4


<StackPanel>
 <CheckBox x:Name="checkBox" Content="Show Text" IsChecked="True"/>
 <TextBlock Text="Hello, World!" Visibility="{Binding ElementName=checkBox, Path=IsChecked, Converter={x:Static local:BooleanToVisibilityConverter.Instance}}"/>
</StackPanel>

Warning

这样确实可以一定程度上简化我们的代码，但也要注意，这样做可能会导致值转换器的状态被共享，从而引发一些问题。所以在使用这种方式时，一定要确保值转换器是无状态的。

将值转换器声明在 App.xaml 中

如果我们有一些相当通用且无状态的值转换器，就比如 BooleanToVisibilityConverter、BoolReverseConverter、NotNullConverter 等，我们可以将它们声明在 App.xaml 中，这样就可以在整个应用程序中直接使用这些值转换器，而不需要在每个用到它们的 Window、UserControl 等地方都进行声明。

1
2
3
4
5
6
7


<Application ...>
 <Application.Resources>
 <BooleanToVisibilityConverter x:Key="BooleanToVisibilityConverter"/>
 <BoolReverseConverter x:Key="BoolReverseConverter"/>
 <NotNullConverter x:Key="NotNullConverter"/>
 </Application.Resources>
</Application>

如果觉得这样的方式会“污染”App.xaml，我们也可以新建一个 ResourceDictionary，并将这些值转换器声明在这个 ResourceDictionary 中，然后在 App.xaml 中引用这个 ResourceDictionary。例如，我们可以新建一个 CommonConverters.xaml：

1
2
3
4
5


<ResourceDictionary ...>
 <BooleanToVisibilityConverter x:Key="BooleanToVisibilityConverter"/>
 <BoolReverseConverter x:Key="BoolReverseConverter"/>
 <NotNullConverter x:Key="NotNullConverter"/>
</ResourceDictionary>

然后在 App.xaml 中引用这个 ResourceDictionary：

1
2
3
4
5
6
7
8
9


<Application ...>
 <Application.Resources>
 <ResourceDictionary>
 <ResourceDictionary.MergedDictionaries>
 <ResourceDictionary Source="CommonConverters.xaml"/>
 </ResourceDictionary.MergedDictionaries>
 </ResourceDictionary>
 </Application.Resources>
</Application>

使用 `MarkupExtension` 简化值转换器的使用

Markup 语法也就是我们经常在 XAML 中看到的“花括号”语法，例如：

{Binding ...}
{StaticResource ...}
{x:Static ...}

只要我们让值转换器继承 MarkupExtension，我们就可以在 XAML 中直接使用 Markup 语法来引用这个值转换器。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


public class BooleanToVisibilityConverter : MarkupExtension, IValueConverter
{
 public bool IsReversed { get; set; }

 public bool UseHidden { get; set; }

 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is bool b)
 {
 b = IsReversed ? !b : b;
 return b ? Visibility.Visible : (UseHidden ? Visibility.Hidden : Visibility.Collapsed);
 }
 }

 public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is Visibility visibility)
 {
 return visibility == Visibility.Visible;
 }
 }

 public override object ProvideValue(IServiceProvider serviceProvider)
 {
 return this;
 }
}

上面是一个“高级版”的 BooleanToVisibilityConverter，它支持 IsReversed 和 UseHidden 两个属性，也就为这一值转换器提供了定制性。我们可以在 XAML 中这样使用它：

1
2
3
4


<StackPanel>
 <CheckBox x:Name="checkBox" Content="Show Text" IsChecked="True"/>
 <TextBlock Text="Hello, World!" Visibility="{Binding ElementName=checkBox, Path=IsChecked, Converter={local:BooleanToVisibilityConverter IsReversed=True, UseHidden=True}}"/>
</StackPanel>

这一技巧尤其适用于某个定制功能强大，且使用频率较高的值转换器。但也要注意，这样声明就会导致值转换器每次都会实例化一个新的出来。如果一个值转换器是无状态的，那么我们最好将其声明为单例，或者将其声明在 App.xaml 中，从而避免重复实例化。

如果还觉得不过瘾，我们可以为值转换器写一个抽象基类，从而进一步简化值转换器的实现。比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public abstract class BaseValueConverter : MarkupExtension, IValueConverter
{
 public override object ProvideValue(IServiceProvider serviceProvider)
 {
 return this;
 }

 public abstract object Convert(object value, Type targetType, object parameter, CultureInfo culture);

 public virtual object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 {
 return Binding.DoNothing;
 }
}

另外还有一种版本，就是希望基类还顺便提供单例模式，那么我们可以这样：

1
2
3
4
5
6
7


public abstract class BaseValueConverter<T> : MarkupExtension, IValueConverter
 where T : class, new()
{
 public static T Instance { get; } = new();

 // ...
}

然后我们就可以使用它了。比如说我们希望实现一个单向的值转换器，将字符串转换成大写，可以这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class StringToUpperConverter : BaseValueConverter<StringToUpperConverter>
{
 public override object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is string s)
 {
 return s.ToUpper();
 }

 return Binding.DoNothing;
 }
}

是不是瞬间变得简单了很多呢？

返回 DoNothing 与 UnsetValue

在 WPF 中，有两个特殊的返回类型，分别是 Binding.DoNothing 和 DependencyProperty.UnsetValue。在某些情况下，让值转换器的方法返回这两个值是非常有用的。

这两个都表示“不做任何事情”，但它们的使用场景是不同的。具体来说，Binding.DoNothing 单纯意味着“不做任何事情”，不去通知任何绑定源或目标，也不会更新界面；而 DependencyProperty.UnsetValue 则暗示绑定是失败的，或者值是无效的。此时，它会触发 Binding 的 FallbackValue，也就是俗称的“缺省值”。

比如我们有一个可以让用户输入文件路径的文本框，并且我们会让另一个 TextBlock 展示这个文件的名称。但是如果用户输入的路径是无效的，我们就不希望展示这个文件的名称，而是展示一个缺省值，这时我们就可以使用 DependencyProperty.UnsetValue：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class FilePathToFileNameConverter : IValueConverter
{
 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is string path &&n File.Exists(path))
 {
 return Path.GetFileName(path);
 }
 return DependencyProperty.UnsetValue;
 }
}

然后我们可以在 XAML 中这样使用：

1
2
3
4


<StackPanel>
 <TextBox x:Name="textBox" Text="C:\Users\Public\Documents\file.txt"/>
 <TextBlock Text="{Binding ElementName=textBox, Path=Text, Converter={local:FilePathToFileNameConverter}, FallbackValue='Invalid File Path'}"/>
</StackPanel>

这样，当用户输入的文件路径无效时，TextBlock 就会展示“Invalid File Path”。

类似地，如果我们希望用户在输入无效的文件路径时，不做任何事情（比如保留上次有效的文件名城），我们就可以返回 Binding.DoNothing。然后就可以实现相应的效果了。

这两个特殊的返回值看似不起眼，但是如果上述功能让我们在 ViewModel 中去实现，就会变得非常繁琐。所以在这种情况下，值转换器就显得非常有用了。

借助 CultureInfo 实现多语言支持

值转换器中的两个方法都有一个 CultureInfo 类型的参数，我们可以利用这个参数来实现多语言支持。比如我们有一个值转换器，将数字转换成各国语言的数字。此时我们就可以在值转换器中根据 CultureInfo 所包含的地区码来选择合适的语言。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


public class NumberToLocalizedNumberConverter : IValueConverter
{
 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is int number)
 {
 switch (culture.TwoLetterISOLanguageName)
 {
 case "zh":
 return number switch
 {
 0 => "零",
 1 => "一",
 2 => "二",
 3 => "三",
 4 => "四",
 5 => "五"
 };
 case "en":
 return number switch
 {
 0 => "Zero",
 1 => "One",
 2 => "Two",
 3 => "Three",
 4 => "Four",
 5 => "Five"
 };
 default:
 return number.ToString();
 }
 }

 return Binding.DoNothing;
 }
}

然后我们可以在 XAML 中这样使用：

1
2
3


<StackPanel>
 <TextBlock Text="{Binding Number, Converter={local:NumberToLocalizedNumberConverter}, ConverterCulture=zh-CN}"/>
</StackPanel>

或者我们也可以在程序中动态地设置 CultureInfo：

1
2
3
4


var culture = new CultureInfo("zh-CN");

Thread.CurrentThread.CurrentCulture = culture;
Thread.CurrentThread.CurrentUICulture = culture;

但是这样还不够，因为值转换器的这一入参是从控件的 Language 属性中继承而来的。所以我们还需要修改全局的 Language 属性。例如，我们想在一个 UserControl 中使用中文，可以这样：

1
2
3
4
5
6


<UserControl Language="zh-CN">
 <!-- 也可以这样写 -->
 <UserControl.Language>
 <XmlLanguage>zh-CN</XmlLanguage>
 </UserControl.Language>
</UserControl>

或者，我们还可以用 OverrideMetadata 的方式来修改全局的 Language 属性：

1
2
3
4
5
6
7


FrameworkElement.LanguageProperty
 .OverrideMetadata(
 typeof(FrameworkElement),
 new FrameworkPropertyMetadata(
 XmlLanguage.GetLanguage(CultureInfo.CurrentCulture.IetfLanguageTag)
 )
 );

这样就可以让值转换器获取到当前的 CultureInfo，从而实现多语言支持。

仿照 Avalonia UI 实现一个 FuncValueConverter

Avalonia UI 中有一个有趣的 FuncValueConverter，它允许我们直接在代码后台简单地声明一个值转换器，而不需要额外写一个类。它地源代码可以在 GitHub 上看到。我们可以仿照这个实现一个类似的值转换器。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


public sealed class FuncValueConverter<TIn, TOut> : IValueConverter
{
 private readonly Func<TIn, TOut> _convert;

 public FuncValueConverter(Func<TIn, TOut> convert)
 {
 _convert = convert;
 }

 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 {
 if (value is TIn t)
 {
 return _convert(t);
 }

 return Binding.DoNothing;
 }

 public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 {
 return Binding.DoNothing;
 }
}

对于 Convert 方法的实现，这里还有一种更好的方式。我们都知道，在 XAML 书写的很多资源，WPF 都会在底层帮我们进行合适的类型转换。比如我们将 "1" 字符串赋值给一个 int 类型的属性，WPF 会自动将其转换成 1；我们将 "Visible" 字符串赋值给一个 Visibility 枚举类型的属性，WPF 也会进行相应的转换。如果我们不提供这个功能，那么我们写的这个 FuncValueConverter 就会变得不够灵活。因此，我们可以借助 .NET 原生的 TypeDescriptor 类来实现这个功能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
{
 if (value is not TIn t)
 {
 if (value is null)
 {
 return default(TOut);
 }

 if (TypeDescriptor.GetConverter(typeof(TIn)).CanConvertFrom(value.GetType()))
 {
 t = (TIn)TypeDescriptor.GetConverter(typeof(TIn)).ConvertFrom(value);
 }
 else
 {
 return Binding.DoNothing;
 }
 }

 return _convert(t);
}

这样我们就可以声明并使用了。我们需要将它声明为静态属性：

1
2
3
4


public class MainViewModel : ViewModelBase
{
 public static FuncValueConverter<string, int> StringToIntConverter { get; } = new(s => int.Parse(s));
}

然后我们就可以在 XAML 中这样使用：

1
2
3
4


<StackPanel>
 <TextBox x:Name="textBox" Text="123"/>
 <TextBlock Text="{Binding ElementName=textBox, Path=Text, Converter={x:Static local:MainViewModel.StringToIntConverter}}"/>
</StackPanel>

这样，我们就能够轻易地在代码后台声明一个值转换器了。

其他第三方库

除了上面提到的这些方法，我们还可以使用一些第三方库来简化值转换器及绑定的使用。比如：

这些库有的提供了丰富的内置值转换器，包括组合多种值转换器的功能（例如先将字符串根据 IsNullOrEmpty 转为 bool 类型，再转为 Visibility 类型），有的提供了更加强大的绑定功能，例如可以调用函数，进行数学运算等等。大家有兴趣的话可以去了解一下。

总结

值转换器是 WPF 中非常重要的一个概念，它可以帮助我们将数据转换成我们需要的格式。在这篇文章中，我们介绍了一些值转换器的实用技巧。希望这些技巧能够帮助大家更好地使用值转换器。

只有充分发挥 WPF 中各个功能的优势，我们才能更好地提高我们的开发效率，实现更加复杂的功能。希望大家能够在实际的开发中多多尝试，多多实践。

如何在 C# 中拷贝一个文件夹

Wed, 11 Dec 2024 00:00:00 +0000

拷贝文件夹听起来是一个非常简单的任务，但是在 C# 中实现起来却并不是那么容易，因为 .NET 并没有提供内置的方法，所以通常我们只能自己来实现。

本文提供了三种拷贝文件夹的方式供大家参考。

方法一：使用递归

使用递归是一个非常直观的方法，同时也是 Microsoft Learn 给出的示例。其原版的代码有些冗余和不必要的内存开销，所以这里贴一个相对简练且高效的版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


static void CopyDirectory(string sourceFolderPath, string targetFolderPath)
{
 Directory.CreateDirectory(targetFolderPath);

 foreach (string filePath in Directory.GetFiles(sourceFolderPath))
 {
 string fileName = Path.GetFileName(filePath);
 string destinationPath = Path.Combine(targetFolderPath, fileName);
 File.Copy(filePath, destinationPath, true);
 }

 foreach (string directoryPath in Directory.GetDirectories(sourceFolderPath))
 {
 string directoryName = Path.GetFileName(directoryPath);
 string destinationPath = Path.Combine(targetFolderPath, directoryName);
 CopyDirectory(directoryPath, destinationPath);
 }
}

简单来说，这个方法会递归地拷贝源文件夹下的所有文件和子文件夹到目标文件夹中。对于子文件夹，会递归调用该方法进行拷贝。

Tip

Directory.CreateDirectory 是一个相当灵活的方法。如果目标文件夹不存在，它会自动创建；如果目标文件夹已经存在，它会忽略这个操作。同时，它还会沿途创建所有不存在的文件夹（类似 mkdir 的 -p 参数）。

方法二：不使用递归

如果不希望使用递归，那么也可以通过相对路径的方式来实现。这个方法会递归搜索源文件夹下的所有文件，通过计算它与源文件夹的相对路径来得到它的目标路径，进而生成目标路径所在的文件夹。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


static void CopyDirectory(string sourceFolderPath, string targetFolderPath)
{
 Directory.CreateDirectory(targetFolderPath);

 foreach (string filePath in Directory.GetFiles(sourceFolderPath, "*.*", SearchOption.AllDirectories))
 {
 var relativePath = Path.GetRelativePath(sourceFolderPath, filePath);
 var targetFilePath = Path.Combine(targetFolderPath, relativePath);
 var subTargetFolderPath = Path.GetDirectoryName(targetFilePath);
 if (subTargetFolderPath != null)
 Directory.CreateDirectory(subTargetFolderPath);
 File.Copy(filePath, targetFilePath);
 }
}

Tip

Path.GetDirectoryName 方法有可能返回空。这一情况通常发生在文件位于根目录的情况（例如 Windows 的 C:\，或 Unix 的 /）。

使用 VisualBasic 的内置方法

其实 .NET 也不是完全没有提供内置的方法。比如我们可以使用 VisualBasic 的 Microsoft.VisualBasic.Devices 命名空间下的 Computer 类上的 FileSystem 成员的方法来实现拷贝文件夹的功能：

1
2
3
4
5
6
7
8


using Microsoft.VisualBasic.Devices;
using Microsoft.VisualBasic.FileIO;

static void CopyDirectory(string sourceFolderPath, string targetFolderPath)
{
 fs = new Computer().FileSystem;
 fs.CopyDirectory(sourceFolderPath, targetFolderPath, UIOption.OnlyErrorDialogs);
}

可能有读者想说，作者你怎么不早点拿出这个方法呢？这方法多么地简单易用啊！

实际上，这个方法也是有显著缺点的：需要使用 WinForms 相关的库。也就是说，你的项目需要 TargetFramework 包含 -windows，并且还要 UseWindowsForms。

如果你在开发 WPF 或 WinForms 程序，那么这通常是可以接受的。但如果你是在开发控制台程序、ASP.NET 程序，又或者 Avalonia UI 等跨平台框架，那么这个方法显然就有些 unacceptable 了。

Tip

其实 VisualBasic 还提供了一些别的实用功能，比如将文件移至回收站，就可以用 FileSystem.DeleteFile 方法，并添加 RecycleOption.SendToRecycleBin 参数来实现。这个方法会将文件移至回收站，而不是直接删除。

总结

本文介绍了三种拷贝文件夹的方法，分别是使用递归、不使用递归、以及使用 VisualBasic 的内置方法。这三种方法各有优劣，读者可以根据自己的需求来选择适合的方法。

Warning

在拷贝文件夹时，一定要注意文件夹的权限问题。如果源文件夹或目标文件夹的权限不足，那么拷贝操作可能会失败。

常见图片相关的数据类型之间的转换

Tue, 19 Nov 2024 00:00:00 +0000

我们在做 .NET 开发时，经常要和各种图片的数据类型打交道。这里指的“类型”并不是图片的文件类型，比如 jpg、png、bmp 等，而是图片数据在内存中的表示方式。这些类型之间的转换，有时候会让人感到困惑。本文总结了常见的图片数据类型之间的转换方法，希望能帮助大家理清思路。

常见的图片数据类型有：

byte[] 字节数组：可能有两种情况：
- 将图片文件读取到内存后得到的字节数组，包括图片文件的文件头等
- 图片的像素数据，比如 RGB 数据
Stream：数据流，比如 MemoryStream、FileStream 等，一般和字节数组可以轻易地相互转换
Bitmap：WinForms 中的图片数据类型（基于 GDI+），命名空间是 System.Drawing
BitmapImage：WPF 中的图片数据类型，命名空间是 System.Windows.Media.Imaging，常用于 Image 控件的 Source 属性（是 ImageSource 类型）
BitmapSource：WPF 中的图片数据类型，命名空间是 System.Windows.Media，是 BitmapImage 的基类
其他一些来自第三方库的图片类型

将图片文件路径转为 BitmapImage

如果我们知道图片的链接（可以是本地链接或网址），并且想让 Image 控件显示这个图片，最简单的方式如下：

1
2


var image = new Image();
image.Source = new BitmapImage(new Uri(@"path\to\image.jpg", UriKind.RelativeOrAbsolute));

上述方式甚至都不需要指定图片的格式，因为 BitmapImage 和 BitmapDecoder 都会自动进行处理。对于大多数常见的图片格式（如 JPG、PNG、BMP、GIF、TIFF、WebP、HEIC、AVIF 等），这几种方式都能正常工作。但如果是一些不太常见的图片格式，则可能需要借助一些第三方库才行了。

另外，如果我们并没有图片的路径，只有它被读进内存后的数据类型，那么就需要下面的几种方式了。

Bitmap 转为 BitmapImage

System.Drawing.Bitmap 和 System.Windows.Media.Imaging.BitmapImage 是两个常见的图片数据类型。前者是 WinForms 中的类型（GDI+），后者是 WPF 的类型。它们之间的转换方法如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


using System.Drawing;
using System.Windows.Media.Imaging;

static BitmapImage ConvertBitmapToBitmapImage(Bitmap bitmap)
{
 using var stream = new MemoryStream();

 bitmap.Save(stream, ImageFormat.Png);
 stream.Position = 0;
 
 var bitmapImage = new BitmapImage();
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze(); // （可选）冻结图片，提高性能和线程安全性
 return bitmapImage;
}

字节数组转为 ImageSource

这里有两种情况。如果字节数组只是读进内存的图片文件数据，比如一个本地的 JPG、PNG、BMP 等格式的文件，那么非常简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


using System.IO;
using System.Windows.Media.Imaging;

static ImageSource ConvertByteArrayToImageSource(byte[] bytes)
{
 using var stream = new MemoryStream(bytes);
 var bitmapImage = new BitmapImage();
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze();
 return bitmapImage;
}

还有一种更简单的方式，直接使用 BitmapDecoder 类：

1
2
3
4
5
6
7
8
9


using System.Windows.Media.Imaging;

static ImageSource ConvertByteArrayToImageSource(byte[] bytes)
{
 using var stream = new MemoryStream(bytes);
 return BitmapDecoder
 .Create(stream, BitmapCreateOptions.PreservePixelFormat, BitmapCacheOption.OnLoad)
 .Frames[0];
}

如果字节数组是图片的像素数据，比如从左上到右下的逐行 RGB 数据，那么会麻烦一些，而且我们需要有办法知道图片的宽高等信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Windows.Media;
using System.Windows.Media.Imaging;

static ImageSource BgrByteArrayToImageSource(byte[] array, int width, int height, int channel = 3, int? stride = null)
{
 var bmp = new WriteableBitmap(width, height, 96, 96, PixelFormats.Bgr24, null);
 stride ??= ((width * channel + 3) / 4) * 4;
 bmp.WritePixels(new Int32Rect(0, 0, width, height), array, stride.Value, 0);
 bmp.Freeze();
 return bmp;
}

BitmapSource 转为 BitmapImage

这两个类其实是有继承关系的，BitmapImage 继承自 BitmapSource。但一般我们仍然需要进行一个“转换”，因为通常的使用场景是，我们从 WPF 提供的剪贴板 API 中获取到一个 BitmapSource，但我们经过简单的处理，将它转为 BitmapImage 从而添加给 Image 控件。这时候可以这样转换：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


using System.Windows.Media.Imaging;

static BitmapImage ConvertBitmapSourceToBitmapImage(BitmapSource bitmapSource)
{
 var bitmapImage = new BitmapImage();
 using var stream = new MemoryStream();
 BitmapEncoder encoder = new BmpBitmapEncoder(); // 一般情况下，剪贴板中的图片数据是 BMP 格式的，而非 PNG 格式
 encoder.Frames.Add(BitmapFrame.Create(bitmapSource));
 encoder.Save(stream);
 stream.Position = 0;
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze();
 return bitmapImage;
}

Emgu.CV.Image 转为 BitmapImage

前面我们提到，BitmapImage 支持绝大多数常见的图片格式。但如果现在我们有一个不常见的格式，比如 JP2（JPEG 2000）格式，那么 BitmapImage 就无法直接处理了。这时候我们可以使用 Emgu.CV 库，它是 OpenCV 的 .NET 封装，支持更多的图片格式。下面给出一种方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


var filename = @"path\to\image.jp2";

var mat = new Image<Bgr, Byte>(filename);
var bytes = mat.ToJpegData();
using var stream = new MemoryStream(bytes);

var bitmap = new BitmapImage();
bitmap.BeginInit();
bitmap.CacheOption = BitmapCacheOption.OnLoad;
bitmap.StreamSource = stream;
bitmap.EndInit();
bitmap.Freeze();

var control = new Image();
control.Source = bitmap;

control.Dump();

总结

看了这么多，大家相信已经看出规律了吧？是的，对于大多数情况，我们都要先将数据转为持有常见图像类型的 Stream，然后再创建 BitmapImage，最后将其赋给 Image 控件。这样的方式，可以保证我们的代码在大多数情况下都能正常工作。

WPF 中的 Name 与 x:Name 究竟是什么区别？

Thu, 10 Oct 2024 00:00:00 +0000

在 WPF 开发中，我们可以给控件添加 Name 或 x:Name 属性。这样做的目的通常是希望在代码后台能够访问这个控件，或者我们在写 Binding 表达式时，希望使用 ElementName 的方式绑定某个控件。那么这二者究竟是什么区别呢？本文就来简单探讨一下。

本质不同，但却又几乎相同

别的暂且不谈，我们只关注 XML 文档的命名空间，不难发现 Name 和 x:Name 的区别在于前者没有命名空间，而后者有一个 x 命名空间。具体来说，通常我们的一个 XAML 文件的根元素是这样的：

1
2
3
4
5
6


<Window x:Class="WpfApp1.MainWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="MainWindow" Height="450" Width="800">
 <!-- 省略其他内容 -->
</Window>

其中，xmlns 是默认的命名空间，而 xmlns:x 是 x 命名空间。所以，x:Name 和 Name 分别出自哪个命名空间，就不言而喻了。

但是，虽然它们两个出身不同，但在 WPF 中，它们的作用几乎是一样的。具体来说，Name 是 FrameworkElement 类（以及 FrameworkContentElement 类，下略）的一个依赖属性，形如（为便于阅读，代码略有删改）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


[CommonDependencyProperty]
public static readonly DependencyProperty NameProperty =
 DependencyProperty.Register(
 "Name",
 typeof(string),
 typeof(FrameworkElement),
 new FrameworkPropertyMetadata(/* ... */);

[Localizability(LocalizationCategory.NeverLocalize)]
[MergableProperty(false)]
[DesignerSerializationOptions(DesignerSerializationOptions.SerializeAsAttribute)]
public string Name
{
 get { return (string) GetValue(NameProperty); }
 set { SetValue(NameProperty, value); }
}

而进一步观察 FrameworkElement 类的声明，我们可以发现：

1
2
3
4
5
6
7
8


namespace System.Windows
{
 [RuntimeNamePropertyAttribute("Name")]
 public partial class FrameworkElement
 {
 // ...
 }
}

这里的 RuntimeNamePropertyAttribute 是一个特性，它告诉 WPF 运行时，FrameworkElement 类的 Name 属性将会被转为 x:Name 属性。所以，Name 和 x:Name 在 WPF 中几乎是一样的。

至于为什么要这样设计，我并没有找到官方的答案。唯一合理的猜测，就是想给开发者一个较为方便的方式去给控件命名。毕竟，Name 比 x:Name 看起来更简洁，更加直观（毕竟这看起来就是属于控件自己的名字一样），而且还不需要使用命名空间。

x:Name 本质上意味着什么？

那么，既然二者并没有多少区别，我们现在就来看一看 x:Name 到底意味着什么。在 XAML 中，当我们给控件添加 x:Name 属性时，实际上是在告诉 XAML 解析器，这个控件的名字是什么。并且相信大家都知道，拥有了名字的控件，它就会变成类的字段，我们可以在代码后台通过这个名字来访问它。

具体来说，以 Window 为例，我们会发现后台代码是一个分部类。在我们看不到的地方，XAML 解析器会生成一个类。这个类中就有我们最熟悉的在构造函数中调用的 InitializeComponent 方法，以及我们在 XAML 中添加了 Name 的控件所对应的字段。例如，我们在 XAML 中这样写：

1
2
3
4
5
6
7


<Window x:Class="WpfApp1.MainWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="MainWindow" Height="450" Width="800">
 <Button x:Name="button1" Content="Click Me" />
 <Button x:Name="button2" x:FieldModifier="private" Content="Click Me" />
</Window>

那么，我们就能在后台生成的代码（文件名类似 MainWindow.g.i.cs）中找到这样的内容（我们可以在后台随便一个地方访问这个字段，然后用 IDE 的跳转到定义的方式找到后台生成的代码）：

1
2
3
4
5


public partial class MainWindow : // ...
{
 internal System.Windows.Controls.Button button1;
 private System.Windows.Controls.Button button2;
}

此外，如果 XAML 中的一个控件拥有了 Name，我们还可以实现一些别的事情。包括但不限于：

在 Binding 表达式中使用 ElementName 来绑定这个控件；
在 Storyboard 中使用 TargetName 来指定这个控件；
在后台代码中使用 FindName 方法来查找这个控件。

总结

本文简单介绍了 WPF 中的 Name 和 x:Name 属性。虽然它们在本质上有一些区别，但在 WPF 中，它们的作用几乎是一样的。

围绕着 Name 这个概念，其实能聊的还有很多。比如：

NameScope 的概念；
当持有 Name 的控件在 ControlTemplate 或 DataTemplate 中时会怎样；
与之相关的其他来自 x 命名空间的属性，比如 x:FieldModifier、x:Reference 等。

这些内容，我们会在以后的文章中继续探讨。

参考

如何高效读取 XML 中所需的内容（其二）

Fri, 27 Sep 2024 00:00:00 +0000

我们继续上一次的内容，再来看一看关于 XML 内容读取有哪些意想不到的性能差别。这次我们用于演示的 XML 文本依旧是来自 W3Schools 的一个样例，大致内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<?xml version="1.0" encoding="UTF-8"?>
<breakfast_menu>
 <food>
 <name>Belgian Waffles</name>
 <price>$5.95</price>
 <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
 <calories>650</calories>
 </food>
 <!-- 省略中间的三个 food -->
 <food>
 <name>Homestyle Breakfast</name>
 <price>$6.95</price>
 <description>Two eggs, bacon or sausage, toast, and our ever-popular hash browns</description>
 <calories>950</calories>
 </food>
</breakfast_menu>

我们这次的任务是：获取最后一个 food 的 calories 的值（即 950）。这次我们的选手有：LINQ to XML、XPath 以及正则表达式。对于 XPath，我们同样在 XDocument 上进行操作（只需要引入 System.Xml.XPath 命名空间即可）。

LINQ to XML

我们先来看一看 LINQ to XML（即 System.Xml.Linq 命名空间）该如何实现吧。

1
2
3
4
5
6


public int Elements()
{
 var foods = doc.Root.Elements("food");
 var lastFood = foods.Last();
 return (int)lastFood.Element("calories");
}

其实，这里因为我们很清楚 XML 文档的结构，所以上面的内容可以简化为：

1
2


public int Elements()
 => (int)doc.Root.Elements().Last().Elements().Last();

这样是可以提高一点性能的，因为我们不需要检查每个节点的名字。

另外，我们还可以使用 Descendants 这个方法，从而减少一些 Elements 的调用。最极端的情况下，因为我们要获取的元素正好是最后一个，所以我们甚至别的什么都不用做，直接调用 Descendants 就可以了：

1
2


public int Descendants()
 => (int)doc.Root.Descendants().Last();

XPath

接下来我们看一看使用 XPath 表达式该如何实现：

1
2


public int XPath()
 => (int)doc.XPathSelectElement("//food[last()]/calories");

这里我们借助 XPath 表达式的特殊语法，直接选取了最后一个 food 节点的 calories 子节点。或者，因为我们知道总共五个 food 节点，所以我们也可以将上面的 last() 替换为 5。这样确实会换来一点点提升，但是非常不明显，而且有耍赖的嫌疑，所以我们就不这么做了。

上面的方式其实效率并不是最高的，因为 //food 会搜索整个 XML 文档，寻找所有名称为 food 的节点。如果我们能够将 XPath 表达式写得更加精确，是能够提升一些性能的：

1
2


public int XPathOptimized()
 => (int)doc.XPathSelectElement("/breakfast_menu/food[last()]/calories");

这样，我们就只需要搜索 breakfast_menu 节点下的 food 节点，而不是整个文档了。这个不经意的小改动，就能够带来显著的性能提升（约 4~5 倍！）。

正则表达式

最后，我们再来看一看正则表达式的实现。这个实现方式就非常简单粗暴了。我们只需要匹配 calories 节点，并拿到最后一个的值即可：

1
2
3
4
5
6
7


private readonly Regex regex = new Regex(@"<calories>(\d+)</calories>");

public int Regex()
{
 var matches = regex.Matches(xml);
 return int.Parse(matches[^1].Groups[1].Value);
}

但其实我们仍然有相当大的优化空间。因为我们这里需要的是最后一个 calories 节点，所以我们不需要匹配全部的 calories 节点，只需要匹配到最后一个即可。实现这一操作的方式，除了修改表达式本身以外，我们还可以借助 RegexOptions.RightToLeft 这个选项：

1
2
3
4
5
6
7


private readonly Regex regex = new Regex(@"<calories>(\d+)</calories>", RegexOptions.RightToLeft);

public int RegexOptimized()
{
 var match = regex.Match(xml);
 return int.Parse(match.Groups[1].Value);
}

通过这样的一个简单操作，我们再次可以换来约 4~5 倍的性能提升。

性能对比

现在，我们可以来看一看比赛的结果了：

Method	Mean	Error	StdDev	Gen0	Gen1	Allocated
Elements	101.3 ns	10.07 ns	0.55 ns	0.0101	0.0001	128 B
Descendants	243.4 ns	26.84 ns	1.47 ns	0.0062	0.0005	80 B
RegexMatch	605.7 ns	158.79 ns	8.70 ns	0.1278	0.0010	1608 B
RegexMatchOptimized	128.1 ns	59.86 ns	3.28 ns	0.0305	0.0002	384 B
XPathOptimized	1,297.4 ns	927.55 ns	50.84 ns	0.3681	0.0038	4624 B
XPath	5,099.2 ns	1,591.05 ns	87.21 ns	0.8087	0.0076	10208 B

不知道这样的结果有没有出乎大家的意料呢？不难发现，看似不起眼的 LINQ to SQL 方法，居然能轻易击败了优化过的正则表达式以及 XPath，尤其是 XPath 的速度居然会这么慢，进入了微秒级别。

另一方面，在上一次比赛中胜出的正则表达式，这次居然也不敌 LINQ to XML，尤其是如果不优化，那么正则表达式的性能还要再差上不少。

所以，这次的跑分再次向我们证明，对于 XML 文档的读取，LINQ to XML 是最好的选择，可以说是不仅好用，而且高效。

One More Thing

说到跑分，这种时候怎么少得了 Span 呢？

1
2
3
4
5


public int Span()
{
	var xml = Xml.AsSpan();
	return int.Parse(xml.Slice(xml.LastIndexOf("<calories>") + 10, xml.LastIndexOf("</calories>") - (xml.LastIndexOf("<calories>") + 10)));
}

至于结果嘛：

Method	Mean	Error	StdDev	Ratio	RatioSD	Allocated
Span	22.30 ns	0.435 ns	0.024 ns	0.22	0.00	-

要认识、理解、重视信息差

Mon, 23 Sep 2024 00:00:00 +0000

在我们的学习与生活中，信息差可以说是无处不在。所谓“信息差”，其实就是因为不同的人的见识、经历、机会等的不同，而产生的一种所了解的信息的不平等的现象。这一现象将会导致掌握更多信息的一方在某些情况下具有显著的优势。有一个经典的寓言故事，“拧这颗螺丝值 1 美元，而知道要拧这颗螺丝值 999 美元”。这其实就是信息差。

认识信息差

信息差是客观存在且几乎不可能消除的。韩愈在《师说》中提到，“闻道有先后，术业有专攻”。每个人去学习并了解一样事物的早晚和快慢都是不同的。有的人可能是相关经验比较丰富，或从小就对某样东西充满了兴趣和探索的欲望，又或者运气好，早早就找到了点醒自己的学习资料。也因此，他们早早地掌握了更多的信息，并且基于这些信息，又能够如同指数爆炸一样，快速接受更多的内容。这就是一种优势。

比如最近大火的游戏《黑神话·悟空》，就会出现一种分歧：一部分人觉得，这游戏并不难啊，一些比较厉害的 BOSS 网上很容易找到攻略，直接“耍赖皮”就能过关；而也有一些不擅长动作类游戏，或者说不擅长各种游戏、只是因为游戏的热度和对于剧情的兴趣慕名而来的玩家们就会叫苦不迭，因为游戏还没有提供难度选择。不是所有人都会越挫越勇，屡战屡败本身就很可能消磨人的意志，最终产生负面情感。但前者就会觉得，你们就是菜、就是懒，明明网上大把的攻略，你们都懒得找。

早些年深度学习很火的时候，国内有一些卖课的博主，他们只是把斯坦福大学的 CS231N 的课件拿过来就能放在知乎割大把的韭菜；电商平台时常会见到的“i7 级处理器”和只要九块九的 1T 容量的 U 盘，这种看似“明显”的骗局却屡屡有人中招；机圈人尽皆知的搭载骁龙 680 的电子垃圾，却有可能被人以 2000 元的价格买走……这样的例子数不胜数，但它们也终究是一直并将长期存在着。这些都是因为信息差导致的。

理解信息差

但是我们仅仅认识到信息差的存在是不够的。重要的是，我们要理解信息差。为什么这么说呢？还是上面提到的《黑神话》的例子。或许你知道某个 BOSS 有一个很偷鸡很轻松的打法，但是你比那些“菜鸟”多知道的，其实远不仅仅是“有这个打法”。很有可能是，你在发现这篇攻略之前，已经在相关的社区和论坛沉浸了数个小时。或许这时在你看来，只要在搜索引擎里面简单敲几个字，就能再找到这一篇；可这对于一个完全不了解这方面信息的人来说，所欠缺的时间，可能是巨大的。

在每个领域都是，就比如我和我的绝大多数读者们所处的 .NET 这一领域。或许有一个知识、一个概念、一个技巧对于你来说仿佛家常便饭，相应的博客文章、视频教程、官方文档你可以信手拈来；或许有一个问题，身经百战的你一看报错信息就知道是因为配错了环境，但是却可能让新手在百度上搜索了半天，最后找到了一篇机翻的 CSDN 文章才勉强解决问题；一个简单的接口、依赖注入，对于你来说早已经是轻车熟路、老生常谈，却依旧能够轻易地困惑一个非 CS 科班出身的新手数年。很多时候，人和人之间的差别并不是智商，而是信息。

虽然我明白这个道理，但我也经常会不由自主地去产生不好的情感。比如我经常会在弹幕或评论区看到有人问主题配色和字体用的是什么，或者问一些我早就有相关视频探讨过的内容。明明我已经专门出了视频、在很多处评论给出了解答，还专门写了置顶专栏来解答常见问题，可就是有人不知道。但是换位思考，当我正在看油管上的 Tim Corey、Nick Chapsas、Brian Launas 这些大佬的视频的时候，除非我把他们的所有视频都大致刷了一遍，否则我依旧要花时间去搜索、去研究、去搞懂。我仍记得，第一次看 Brian 的视频时，他项目中使用了 Prism 框架，但是我并不知道他一直都是这样做的，所以第一次看到他的 MVVM 框架“莫名其妙”地自动实现了一些功能时完全一脸懵逼。而这一点，对于他的其他观众而言，简直可以说是“常识”——是的，每个人都有自己的“常识”，而且有可能和别人的交集占比并不大。

也因此，每次我介绍 MVVM 相关的内容时，我会尽量多说两句 MVVM 社区工具包的原理，从而让之前没接触过的观众不至于搞不清楚那些看不到的属性是哪儿来的；看到问主题颜色和字体的问题时，我也时刻提醒自己，我知道我在很多地方提供了回答，也依旧是不够的——我现在已经有一百多期视频了，连我自己有时候都搞不清楚某个知识点我到底有没有讲过。甚至因为我用了包含连字符的字体，导致代码中有时候会出现诸如“≠”的符号，我现在都觉得有些不妥。这里给看我 MVVM 工具包视频并且因为这些符号感到困惑过的观众朋友们道个歉。

重视信息差

前面我们说了，对于信息差，我们要认识、要理解，但同时，我们还要重视。什么是重视呢？我们要知道，虽然我们可能比其他人碰巧多知道了一些知识，从而使我们在某些时候占据了优势，但是我们也要时常反思。“吾日三省吾身”，因为信息差客观存在，别人有欠缺的信息，我们极有可能也有，而且可能还有不少。所以，谁也别瞧不起谁。每个人都有自己的盲区，都有自己还不熟悉的领域。在这个信息爆炸的时代，我们永远都不要只活在自己的舒适区，要敢于跳出自己的成见，去了解、去学习、去接受新的事物。

人怎样才能进步呢？程序员的进步，不是靠着写相同的代码写 10000 遍，而是靠着每天都能写点之前从来没写过的代码，思考一些以前没想过或没相同的事情。每天都做自己认为对的事情，或许并没有进步；每天意识到曾经的自己犯过一些错误，这才是吐故纳新。要敢于承认自己的不足，正视自己的缺点，笑对别人的鄙夷。相信将来的自己，回过头来，会觉得一路走来，每一次“难受”都是值得的。

除此之外，我们还有另外一个层面的“重视”——我们要警惕别人利用信息差来欺骗或蒙蔽自己。有的人掌握了信息差，或许只是妄自尊大、盲目自信、充满了优越感；但更有一部分人，会特意借助信息差来收“智商税”。这样的例子在我们的生活中可以说是无处不在，不管是网店、二手交易平台、网课平台，还是各种中介、招聘平台等等。我们一定要擦亮自己的眼睛。

结语

最后，希望大家都能够理解信息差，要时刻怀着一种“自己还有很多不知道的东西”的态度，努力学习，尽力减少此类情形。另一方面，我们还要提高警惕，因为可能会有人借助信息差来欺骗我们。面对那些当下掌握了比自己少的信息的人，不要嗤之以鼻，而是友好相处，伸出援手。毕竟，把自己掌握的知识教会给别人，不正是践行了费曼学习法、证明自己确实掌握了这个知识吗？只有每个人都这样，我们才能建设一个良好的社区环境。

WPF 设计时特性的实用技巧

Sat, 07 Sep 2024 00:00:00 +0000

相信无数 WPF 开发者在开发过程中，都会遭受过很多这样或那样的痛苦，比如：

在设计 TextBlock 控件时，因为无法预览字体、字号、颜色等属性，导致需要临时给 Text 属性赋一个值，查看效果后再删除；
有一个默认折叠的 Expander 控件，但是在设计时无法看到折叠后的效果，只能在运行时查看，或者临时修改 IsExpanded 属性；
Window 的 DataContext 因为在后台代码中赋值，导致在设计时无法看到绑定的数据，也无法在书写绑定时获得智能提示。

如果你有过这样的困扰，那么这篇文章一定可以帮助到你。本文将介绍 WPF 中设计时特性的使用方法，让你在设计时就能看到更多的效果，提高开发效率。

基本概念

设计时特性（Design-Time Attributes）是 WPF 中的一种特性，用于在设计时为控件提供更多的信息，以便在设计时能够更好地预览控件的效果。这一功能其实默认一直都是开启的，只是我想可能很多开发者都没有注意过。比如我们在 WPF 中新建一个 UserControl，那么就会在 XAML 的开头看到类似这样的代码：

1
2
3
4
5
6
7
8


<UserControl x:Class="WpfApp1.MyUserControl"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
 xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
 mc:Ignorable="d" 
 d:DesignHeight="450" d:DesignWidth="800">
</UserControl>

在开头，模板自动为我们添加了很多 XML 命名空间（xmlns），但是很多开发者可能只了解 xmlns 与 xmlns:x 这两个，而往往忽略了另外的几个。但其实另外的几个（xmlns:mc、xmlns:d）就提供了设计时特性的支持。最典型的例子就比如上面的d:DesignHeight和d:DesignWidth，这两个属性就是用来在设计时指定控件的高度和宽度的。这些特性最大的特点就是，它们只在设计时起作用，不会影响运行时的效果。

了解了这些基本概念后，我们就可以开始介绍一些常用的设计时特性了。

常用设计时特性

比如 TextBlock 的 Text 在设计时并没有内容（比如是 DynamicResource 从运行时加载的语言文件中获取，或绑定了 ViewModel 中的属性，但是设计时这个属性没有值，却又想预览字体效果，这时候就可以使用 d:Text 来指定设计时的文本内容：

1

<TextBlock Text="{DynamicResource ResourceKey=HelloWorld}" d:Text="Hello, World!" />

这样在设计时就可以看到 Hello, World! 这个文本了。

如果 TextBlock 的内容是用多个 Run 组合而成，那么我们也可以用这样的方式来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<TextBlock>
 <d:TextBlock.Inlines>
 <Run Text="Hello, " />
 <Run Text="World!" FontWeight="Bold" />
 </d:TextBlock.Inlines>
</TextBlock>
<!-- 或者也可以用下面将要介绍的虚拟控件 -->
<d:TextBlock>
 <Run Text="Hello, " />
 <d:Run Text="World!" FontWeight="Bold"/>
</d:TextBlock>

其他类似的例子还比如：

有一个只在特殊情况下才会展示的进度条，希望查看它的效果：d:Visibility="Visible"
有一个平时默认折叠的面板，想查看效果：d:IsExpanded="True"
一个用户控件，想给它一个相对合理的默认大小：d:DesignHeight="600" 或 d:Height
一个下拉框，想查看选中项的预览效果：d:SelectedIndex="0"
一个导航用的 ContentControl，我们希望预览导航到某一页的效果，就可以写 d:ContentControl.Content

Info

关于上面的第 5 个例子，为什么我们直接将想要导航的内容以下面要提到的虚拟控件的方式添加到 ContentControl 之中呢？因为通常来说，我们写的导航页面是借助 UserControl 实现的，而它的命名空间通常为 xmlns:local 等。对于这样的命名空间，我们没有办法使用 d: 技巧，所以这里我们选择为 ContentControl 的 Content 属性添加 d: 特性。

虚拟控件

我们不仅可以借助设计时特性来实现控件某些属性的虚拟，还可以虚拟整个控件出来：

1

<d:Button Content="Virtual Button" Style="{StaticResource MyButtonStyle}" />

这样就可以在设计时看到一个虚拟的按钮了，而不需要在运行时才能看到效果。这一技巧可以用来预览按钮的样式。

还有一种常见情形是，我们设计的软件会让用户去手动添加一些项目，从而动态生成对应的控件。对于这样的情况，我们如果能在设计时就看到一些“生成”出来的控件，那么就能更好地开发样式了。此时，我们添加一些虚拟控件，就可以满足这个需求。

1
2
3
4
5
6
7


<ItemsControl>
 <d:ItemsControl.Items>
 <Button Content="Button 1" />
 <Button Content="Button 2" />
 <Button Content="Button 3" />
 </d:ItemsControl.Items>
</ItemsControl>

设计时数据

这段内容可以说是重中之重了。很多开发者苦恼于因为在 Window 的代码后台通过 this.DataContext = new ViewModel(); 来添加 ViewModel，导致在设计时无法看到绑定的数据，也无法获得智能提示。这时候我们可以使用 d:DataContext 来指定设计时的数据：

1
2
3


<Window ...
 d:DataContext="{d:DesignInstance Type=vm:MainViewModel}">
</Window>

DesignInstance 还有一个 IsDesignTimeCreatable 属性，用于指定是否在设计时创建实例。如果设为 True，还将能够在设计时看到一些 ViewModel 中属性的默认值。

或者我们还可以这样写，并且还可以在 XAML 中定制一些 ViewModel 的属性的初始值，便于观察效果：

1
2
3
4
5


<Window ...>
 <d:DataContext>
 <vm:MainViewModel Message="Hello!" />
 </d:DataContext>
</Window>

列表项

如果我们有一个 ListBox，并且想要查看列表项的效果，可以这样：

1
2
3
4
5
6
7
8
9


<ListBox ItemsSource="{Binding Students}">
 <d:ListBox.ItemsSource>
 <x:Array Type="model:Student">
 <model:Student Name="Alice" Age="18" />
 <model:Student Name="Bob" Age="19" />
 <model:Student Name="Charlie" Age="20" />
 </x:Array>
 </d:ListBox.ItemsSource>
</ListBox>

如果不想写 x:Array，而是希望采用传统的为 Items 添加控件的方式添加预览项，也可以这样：

1
2
3
4
5
6
7


<ListBox ItemsSource="{Binding Students}" d:ItemsSource="{x:Null}">
 <ListBox.Items>
 <ListBoxItem>Student 1</ListBoxItem>
 <ListBoxItem>Student 2</ListBoxItem>
 <ListBoxItem>Student 3</ListBoxItem>
 </ListBox.Items>
</ListBox>

这里额外写一个 d:ItemsSource="{x:Null}" 是因为 ItemsSource 和 Items 两个属性不能同时使用，所以我们需要将 ItemsSource 设置为 null，就可以避免这个报错了。

除了这些，如果我们想要预览的是比较简单的数据，或者我们并不非常关心数据的内容及格式，只是希望生成几个项目从而查看样式或模板的书写是否有问题，那么还有一个更简单的方法：

1

<ListBox ItemsSource="{Binding Students}" d:ItemsSource="{d:SampleData ItemCount=5}" />

这样就可以生成 5 个虚拟的列表项了。

参考

如何高效读取 XML 中所需的内容（其一）

Sun, 18 Aug 2024 00:00:00 +0000

这次我们用于演示的 XML 文本来自 W3Schools 的一个样例，内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<?xml version="1.0" encoding="UTF-8"?>
<breakfast_menu>
 <food>
 <name>Belgian Waffles</name>
 <price>$5.95</price>
 <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
 <calories>650</calories>
 </food>
 <!-- 省略中间的三个 food -->
 <food>
 <name>Homestyle Breakfast</name>
 <price>$6.95</price>
 <description>Two eggs, bacon or sausage, toast, and our ever-popular hash browns</description>
 <calories>950</calories>
 </food>
</breakfast_menu>

假定我们的任务是读取所有 food 节点的 name 属性的值，然后将它们存储到一个 List<string> 中。首先我们来用几种方式来实现这个需求。

使用 XmlDocument

XmlDocument 算是一种“传统”的方式。它有两种“玩法”，一种是使用诸如 GetElementsByTagName 这样的方法，一点一点地找到我们需要的节点及其属性和内容；另一种是使用 XPath 表达式，一次性找到所有符合条件的节点。我们先来看看第一种方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public List<string> XmlDocument()
{
 var doc = new XmlDocument();
 doc.LoadXml(testXml);
 return doc
 .GetElementsByTagName("food")
 .OfType<XmlNode>()
 .Select(node => node["name"]!.InnerText)
 .ToList();

 // var names = new List<string>();
 // foreach (XmlNode node in doc.GetElementsByTagName("food"))
 // {
 // names.Add(node["name"]!.InnerText);
 // }
 // return names;
}

Info

上面注释掉的代码是使用传统的 foreach 循环来实现的，这样写在旧版本的 .NET 中可能会更快一些，但是在 .NET 7 以来的新版本中，LINQ 的性能已经得到了很大的提升。对于常见的集合类型，LINQ 的性能已经和传统的 foreach 循环相差无几，甚至有时还更快，而且完全不会产生额外的 GC 压力。

然后我们还可以用 XPath 表达式来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public List<string> XmlDocumentXPath()
{
 var doc = new XmlDocument();
 doc.LoadXml(testXml);
 return doc
 .SelectNodes("//food/name")
 .OfType<XmlNode>()
 .Select(node => node.InnerText)
 .ToList();
}

使用 Xml.Linq

Xml.Linq 是一种更加现代的方式，它的 API 设计更加友好，使用起来也更加方便。我们可以这样来实现：

1
2
3
4
5
6
7
8
9


public List<string> XDocument()
{
 var doc = XDocument.Parse(testXml);
 return doc
 .Root
 .Elements("food")
 .Select(node => node.Element("name")!.Value)
 .ToList();
}

XDocument 同样可以使用 XPath 表达式来实现，但是这里我们就不演示了，因为 XDocument 的 API 设计已经足够友好，不像是 XmlDocument 那样使用 XPath 表达式会显得更加简洁。

使用 XmlReader

XmlReader 是一种基于流的方式，它的操作并不简单，但是效率极高。我们可以这样来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public List<string> XmlReader()
{
 using var stringReader = new StringReader(testXml);
 using var xmlReader = System.Xml.XmlReader.Create(stringReader);
 var res = new List<string>(8);
 while (xmlReader.Read())
 {
 if (xmlReader.IsStartElement() && xmlReader.Name == "name")
 {
 res.Add(xmlReader.ReadElementContentAsString());
 }
 }
 return res;
}

使用 Regex

因为我们的任务过于简单，要解析的 XML 文本内容也很纯粹，所以我们还可以使用正则表达式来实现：

1
2
3
4
5


public List<string> Regex()
{
 var matches = Regex.Matches(testXml, @"<name>(.*?)</name>");
 return matches.Select(match => match.Groups[1].Value).ToList();
}

使用传统的字符串方法

最后，我们还可以使用传统的字符串方法来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public List<string> StringOps()
{
 var res = new List<string>(8);
 int cur = 0;
 while (true)
 {
 // 找到下一个 <name> 节点
 	int idx = testXml.IndexOf("<name>", cur);
 // 如果找不到，说明已经找完了
 	if (idx < 0)
 		break;
 // 找到对应的 </name> 节点
 	int end = testXml.IndexOf("</name>", idx + 6);
 	res.Add(testXml.Substring(idx + 6, end - idx - 6));
 // 从下一个节点开始继续找
 	cur = end + 7;
 }
}

提前剧透一下，这个方式的效率非常低，远低于其他几种方式。因此，我们还有一个杀手锏：Span<T>。

使用 Span

Span<T> 是 C# 7.2 引入的一个新特性，它可以让我们更加高效地操作内存。我们可以这样来实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public List<string> SpanOps()
{
 var res = new List<string>(8);
 var span = testXml.AsSpan();
 while (true)
 {
 int idx = span.IndexOf("<name>");
 if (idx < 0)
 break;
 int end = span.Slice(idx + 6).IndexOf("</name>") + idx + 6;
 res.Add(span.Slice(idx + 6, end - idx - 6).ToString());
 span = span.Slice(end + 7);
 }
 return res;
}

性能测试

现在我们就可以来测试一下这几种方式的性能了。我们使用 BenchmarkDotNet 来进行测试。结果如下：

怎么样，大家领教了 Span 的威力了吗？它一骑绝尘，已经进入纳秒的境界了。所以我们可以得出结论：

如果我们要获取的内容并不复杂，我们完全可以使用正则表达式来抓取想要的内容，而不是死板地解析 XML 文档
当较为复杂时，我们还是需要借助传统的方式进行读取。它们的性能关系为：XmlReader > XDocument > XmlDocument
从实用性的角度考虑， XDocument 比 XmlReader 及 XmlDocument 都更加实用，速度比传统的 XmlDocument 快，又并不显著逊于 XmlReader，所以应该是我们在大多数情况下的最优选项
使用 Span 可以显著优化性能，尤其是我们需要频繁对字符串进行 IndexOf、SubString 等操作时

使用 AsyncBarrier 来等待并同步多个异步任务

Sun, 11 Aug 2024 00:00:00 +0000

大家在做异步编程开发的时候，不知道是否会遇到这样的一种情形：

有多个异步任务，这些任务之间没有依赖关系，但是我们需要等待所有任务都完成后再继续执行后续的操作。我们唯一知道的，就是这些任务的数量。

举个例子：我们现在有三个 IO 相关的异步任务。这些任务的先后顺序是不确定的，并且这些任务也不必同时发起，但是我们需要等待这三个任务都完成后再继续执行后续的操作。

对于最普通的等待多个异步任务，我们首先肯定会想到使用 Task.WhenAll 方法。但是 Task.WhenAll 现在并不能满足我们的需求，因为它需要能够立刻获取到所有任务的集合。并且因为我们希望在每个异步任务的中间某个环节去等待其他任务的完成，而并不是所有异步任务都会在同一时间点发起，所以这就产生了一个矛盾。

这时候大家可能会想到另外一种更加简单粗暴的方式：我们创建一个局部字段 int count，然后每个异步任务完成后，我们将 count 自增。当 count 的值等于我们预期的任务数量时，我们就可以继续执行后续的操作。这种方式虽然可以解决问题，但是实现起来比较繁琐，因为我们还需要考虑使用什么机制来控制这些异步任务在 count 达到预期值时进行后续操作。最简单的方式无疑是使用轮询，但这显然是不够好的。聪明一些的方式是使用信号量，如 SemaphoreSlim，或者其他库提供的 AsyncAutoResetEvent 等。当然，我们还可以采用更加轻量的 TCS（TaskCompletionSource）来实现。但即便思路已经有了，实际实现起来依旧非常复杂，因为我们还要考虑 count 变量的线程安全、异常处理、取消任务等。

引入 AsyncBarrier

这时候，AsyncBarrier 就派上用场了。AsyncBarrier 是一个非常轻量级的类，它可以帮助我们等待并同步多个异步任务。这个类是由 Microsoft.VisualStudio.Threading 提供的，我们可以轻易地找到它的源代码。

实际在使用时，我并不推荐大家去直接将 Microsoft.VisualStudio.Threading 这个库引入到项目中，因为这个库本身是一个非常庞大的库，而且里面还包含了一些代码分析器（Code Analyzers），会给我们的项目添加一些恼人的“波浪线”。所以，一般情况下，我更推荐大家去使用 Nito.AsyncEx 这个库。但是它又不包含 AsyncBarrier 这个类，所以我们可以直接将 AsyncBarrier 的源代码复制到我们的项目中，然后稍作修改即可。如果你不想麻烦，我也提供了一个开箱即用的版本，在 GitHub Gist 上。

我们来简单理解一下它的源代码。这里我节选了一部分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


public class AsyncBarrier
{
 private readonly int participantCount;

 private readonly Stack<Waiter> waiters;

 public AsyncBarrier(int participants)
 {
 if (participants <= 0)
 throw new ArgumentOutOfRangeException(
 nameof(participants),
 $"Argument {nameof(participants)} must be a positive number."
 );
 this.participantCount = participants;

 this.waiters = new Stack<Waiter>(participants - 1);
 }

 public ValueTask SignalAndWait(CancellationToken cancellationToken)
 {
 lock (this.waiters)
 {
 if (this.waiters.Count + 1 == this.participantCount)
 {
 while (this.waiters.Count > 0)
 {
 Waiter waiter = this.waiters.Pop();
 waiter.CompletionSource.TrySetResult(default);
 waiter.CancellationRegistration.Dispose();
 }

 return new ValueTask(
 cancellationToken.IsCancellationRequested
 ? Task.FromCanceled(cancellationToken)
 : Task.CompletedTask
 );
 }
 else
 {
 TaskCompletionSource<EmptyStruct> tcs =
 new(TaskCreationOptions.RunContinuationsAsynchronously);
 CancellationTokenRegistration ctr;
 if (cancellationToken.CanBeCanceled)
 {
 ctr = cancellationToken.Register(
 static (tcs, ct) =>
 ((TaskCompletionSource<EmptyStruct>)tcs!).TrySetCanceled(ct),
 tcs
 );
 }
 else
 {
 ctr = default;
 }

 this.waiters.Push(new Waiter(tcs, ctr));
 return new ValueTask(tcs.Task);
 }
 }
 }
}

这里还有另外两个类型 Waiter 和 EmptyStruct，这里由于篇幅的关系就不展示了。它们做的事情也非常简单，前者用于存储等待器的信息，后者则是一个空结构体，用于表示一个空的异步操作。它们并不是我们的重点，所以就不展开讨论了。

我们不难观察到这么几点：

它内部有一个 participantCount 字段，表示参与者的数量；另外还有一个 Stack，用来存储所有等待的参与者；
它只有一个公开的方法 SignalAndWait，表示调用者现在要进入等待状态。在这个方法中：
- 首先，它会判断当前等待的参与者数量是否等于预期的参与者数量。如果是，那么就将等待器逐个从 Stack 中弹出并唤醒；
- 如果不是，那么就创建一个新的 TaskCompletionSource，并将其存入 Stack 中，然后返回这个 TaskCompletionSource 的 Task 给参与者用于 await。
当所有参与者都到齐后，SignalAndWait 方法会返回一个已完成的 ValueTask，这时候所有参与者都可以继续执行后续的操作。

Info

这里其实还有一个小细节，就是 Stack 的容量是 participantCount - 1。这是因为我们并不需要将最后一个参与者也入栈。毕竟，当“倒数第一”到达终点时，我们就可以宣告比赛结束了。

使用 AsyncBarrier

现在我们就可以来用一用它了。我们这里借助 CommunityToolkit.Mvvm 这个库来写一个视图模型（ViewModel），大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


partial class MainViewModel : ObservableObject
{
 public ObservableCollection<string> Results { get; } = new();

 private AsyncBarrier _asyncBarrier = new(3);

 [RelayCommand]
 async Task FirstJobAsync(CancellationToken token)
 {
 await Task.Delay(1500, token);
 Results.Add("First job completed. Waiting for async barrier...");
 await _asyncBarrier.SignalAndWait(token);
 Results.Add("First job completed.");
 }

 [RelayCommand]
 async Task SecondJobAsync(CancellationToken token)
 {
 await Task.Delay(1500, token);
 Results.Add("Second job completed. Waiting for async barrier...");
 await _asyncBarrier.SignalAndWait(token);
 Results.Add("Second job completed.");
 }

 [RelayCommand]
 async Task ThirdJobAsync(CancellationToken token)
 {
 await Task.Delay(1500, token);
 Results.Add("Third job completed. Waiting for async barrier...");
 await _asyncBarrier.SignalAndWait(token);
 Results.Add("Third job completed.");
 }
}

这里我们定义了三个异步方法 FirstJobAsync、SecondJobAsync 和 ThirdJobAsync，它们分别模拟了三个异步任务。这三个任务之间没有依赖关系，但是我们希望在它们都完成后再继续执行后续的操作。我们在类中声明了一个 AsyncBarrier 字段，然后让这三个任务都调用它的 SignalAndWait 方法，这样就可以保证这三个任务都完成后才会继续执行后续的操作。

实际运行代码，我们可以发现确实达到了我们想要实现的效果。这三个按钮可以让用户以任意的顺序及时间间隔进行点击，并且每个任务接近完成的时候，都会进入等待状态。只有当所有任务都完成后，我们才会看到所有任务都已完成的提示。

更棒的是，AsyncBarrier 还可以重复使用。毕竟它底层只是一个 Stack。我们在等待时会入栈，等待完成后会出栈，最终使它回归初始状态。这样我们就可以在界面中反复实验这一现象。

取消任务

现在我们希望更进一步，为这些异步任务添加取消功能。那么，首先我们可以添加 InitAllJobs 与 FinishJobs 两个方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


private AsyncBarrier? _asyncBarrier;

[MemberNotNull(nameof(_asyncBarrier))] // 提示编译器，这个方法会确保 _asyncBarrier 不为空
private void InitJobs()
{
 if (_asyncBarrier == null)
 {
 _asyncBarrier = new AsyncBarrier(3);
 Results.Clear();
 }
}

private void FinishJobs(bool success = true)
{
 if (_asyncBarrier != null)
 {
 _asyncBarrier = null;
 if (success)
 Results.Add("All jobs completed successfully.");
 else
 Results.Add("Jobs were canceled.");
 }
}

这两个方法分别用于初始化任务与结束任务。在初始化任务时，我们会创建一个新的 AsyncBarrier 实例，并清空 Results 集合。在结束任务时，我们会将 AsyncBarrier 实例置空，并根据是否成功完成任务来添加提示信息。

Tip

这其实也是我比较推荐的使用 AsyncBarrier 的方式。虽然我们前面说了，它可以被重复使用。但是观察它的源代码会发现，它非常轻量，也不需要担心资源释放的问题，因为我们大可以每次使用的时候都实例化一个新的出来。毕竟这样还有一个好处，就是每次我们都可以根据实际情况去调整它的 participantCount。

接下来我们就可以在每个异步任务中添加取消逻辑。以 FirstJobAsync 为例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[RelayCommand]
async Task FirstJobAsync(CancellationToken token)
{
 InitJobs();

 try
 {
 await Task.Delay(1200, token);
 Results.Add("First job completed. Waiting for async barrier...");

 await _asyncBarrier.SignalAndWait(token);

 FinishJobs();
 }
 catch (TaskCanceledException)
 {
 Results.Add("First job was canceled.");
 FinishJobs(false);
 }
}

这里的大致思路是：

首先会调用 InitJobs 方法，初始化任务。这里每个异步方法都会尝试去初始化，但只有第一个（即 AsyncBarrier 字段为空时）是有效的；
在异步任务中使用 try-catch 块，捕获 TaskCanceledException 异常。因为如果我们想要取消任务，那么这个异步任务中的 Task.Delay 以及 AsyncBarrier.SignalAndWait 都会抛出这个异常；
当异步任务完成时，会调用 FinishJobs 方法，结束任务。并且这里类似 InitJobs，只有第一个异步任务会有效调用。

然后，我们还需要一个 RelayCommand，用来实现取消功能：

1
2
3
4
5
6
7


[RelayCommand]
private void CancelAllJobs()
{
 if (FirstJobCommand.IsRunning) FirstJobCommand.Cancel();
 if (SecondJobCommand.IsRunning) SecondJobCommand.Cancel();
 if (ThirdJobCommand.IsRunning) ThirdJobCommand.Cancel();
}

这样我们就实现了想要的效果了。此时，我们在 XAML 中的代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<Window ...>
 <Window.DataContext>
 <local:MainViewModel />
 </Window.DataContext>
 <DockPanel >
 <DockPanel DockPanel.Dock="Bottom" LastChildFill="False">
 <Button Content="Job1" Command="{Binding FirstJobCommand}" />
 <Button Content="Job2" Command="{Binding SecondJobCommand}" />
 <Button Content="Job3" Command="{Binding ThirdJobCommand}" />
 <Button Content="Cancel" Command="{Binding CancelAllJobsCommand}" DockPanel.Dock="Right" />
 </DockPanel>
 <ListBox ItemsSource="{Binding Results}" />
 </DockPanel>
</Window>

其实上面的故事还没有结束，因为实际运行后会发现，Cancel 按钮在任何时候都是可用的。这是因为我们没有正确处理它的 ICommand 的 CanExecute 方法。这里我就不展开讲了，我在视频中有详细讲解，大家可以在文章开头找到相应的视频链接。

总结

AsyncBarrier 是一个非常轻量级的类，它可以帮助我们等待并同步多个异步任务。它的实现非常简单，但是却非常实用。我们可以在异步任务中使用它，来保证多个异步任务都完成后再继续执行后续的操作。同时，我们还可以在异步任务中添加取消逻辑，来保证任务的可靠性。

大家如果有这样的需求，不妨去试一下这个类，相信一定可以帮上忙。不仅如此，我们还可以借此学习微软官方的源代码，了解一下它的实现细节。这对我们提升编程能力也是非常有帮助的。

C# 字符串操作实用技巧及新手易犯错误

Sat, 27 Jul 2024 00:00:00 +0000

C# 为字符串相关的操作提供了很多实用的类，比如：

string
StringBuilder
Encoding
Regex

它们的功能相当强大，但这也导致了我们可能并不足够了解它，导致我们可能并不熟悉某些方法的重载，或者不知道某些方法的性能问题，最终导致我们的代码效率低下（而且我们还常常察觉不到）。这篇文章我将为大家介绍一些 C# 字符串操作的实用技巧和易犯错误，希望能帮助大家更好地使用字符串。

在可以使用字符的时候不要使用字符串

在 C# 中，声明一个字符与字符串，有一个很典型的区别，就是使用单引号和双引号。除此之外，它们二者也是区别很大的。字符串变量实际上是在堆上分配了一块内存空间，这个空间用来存储字符串的内容。而字符则是值类型，它存储在栈上，所以它的性能要比字符串要好很多。所以绝对不能把字符简单理解为长度为 1 的字符串，它们是完全不同的两种类型，效率也是很不相同的。

在 C# 中使用 string 类型的某些方法时，我们就有机会使用字符而不是字符串，比如：

1
2
3
4
5
6
7


string str = "Hello, World!";

str.StartsWith('H');
str.EndsWith('!');
str.Contains('o');
str.IndexOf('o');
str.Split(',');

这些方法都有重载，可以接受字符作为参数，这样我们就可以直接使用字符而不是字符串，这样可以提高代码的性能。

为什么要这么做呢？除了上面提到的引用类型和值类型的区别以外，它们还有其他一些区别。以 Contains 为例，大家可以想象一下这个方法在底层是如何实现的。比如底层可能会是一个二层循环，第一层循环遍历字符串的每一个字符，第二层循环则在匹配到第一个字符后，再遍历后面的字符，看是否和我们要查找的子字符串相同。

为了保证算法的通用性，即便我们传入的字符串长度为 1，底层也会把它当做一个字符串来处理。这对应到 JIT 编译后的机器码，就会有一些额外的开销，比如判断循环的跳出条件，以及跳转等。而如果我们传入的是字符，那么底层就可以直接比较单个字符的值，这样就可以减少一些额外的开销。

使用方法的重载，减少不必要的调用

字符串类的很多方法都包含了大量的重载。正确使用这些重载，有利于我们减少一些额外的调用，以及所造成的资源浪费。比如下面几个例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


string str = " Hello, World,, Good, Morning ";

// 这里我们希望将上面的内容按照逗号分割，并去除空字符串
// 正确的做法是使用下面这个 Split 方法的重载
var slices = str.Split(',', StringSplitOptions.RemoveEmptyEntries);

//假如我们不知道这个重载，我们可能会写出下面这样的代码
var slices = str.Split(',').Where(s => !string.IsNullOrEmpty(s)).ToArray();

// 还比如我们希望去除每个字符串的前后空格
// 正确的做法是使用下面这个 Split 方法的重载
var slices = str.Split(',', StringSplitOptions.TrimEntries);

// 同样地，假如我们不知道这个重载，我们可能会写出下面这样的代码
var slices = str.Split(',').Select(s => s.Trim()).ToArray();

每一次对字符串类型调用它的常见方法，都会产生额外的开销。

我们再来看另外一个例子：比较两个字符串是否相同。如果我们想要忽略大小写进行比较，我们可能会写出这样的代码：

1
2
3
4


if (s1.ToLower() == s2.ToLower())
{
 // ...
}

但是实际上，我们有效率显著高于上面这种方式的方法 Equals：

1
2
3
4


if (s1.Equals(s2, StringComparison.OrdinalIgnoreCase))
{
 // ...
}

是的，这个方法也拥有一些重载。这样我们就可以避免创建两个新的字符串，以及额外的比较操作。

string 类的构造函数

相信大多数新手可能声明字符串的方式都是直接使用双引号，或者对其他字符串调用一些方法而得到，比如：

1
2
3


string str = "Hello, World!";
string str2 = str.Substring(0, 5);
string str3 = str.Replace(",", " ");

但实际上，string 类还有一些构造函数，可以帮助我们更好地创建字符串。相信用过 Python 的都知道，如果我们想在控制台输出一个长度为 20 个等号的分隔符，通常我们的做法是：

1

print('=' * 20)

其实在 C# 中，我们也可以实现类似的效果：

1
2


string sep = new string('=', 20);
Console.WriteLine(sep);

除此之外，如果我们有一个字符数组，我们也可以使用 string 类的构造函数来创建字符串。这个技巧一般用不到，可一旦我们有了一个需要转为字符串的字符数组，这个方法就会显得非常有用。一个典型的例子是，如果我们想翻转一个字符串，那么在不借助 Span 或 unsafe 的情况下，效率最高的方式为：

1
2
3


char[] chars = str.ToCharArray();
Array.Reverse(chars);
string reversed = new string(chars);

如果不知道字符串的构造函数的用法，可能就会写出下面的代码了：

1

string reversed = string.Join("", str.Reverse());

当然了，我们永远可以写出更加辣眼睛的代码，不是吗？

1
2
3
4


// string reversed = new string(str.Reverse().ToArray());
char[] chars = str.Select(c => c).ToArray();
chars = chars.Reverse().ToArray();
string reversed = string.Join("", chars);

与操作系统有关的一些方法

由于 Windows 与 Unix 系统的一些区别，导致了两个时不常会让我们感到痛苦的事情：换行符和路径分隔符。在 Windows 系统中，换行符为 \r\n（CRLF），而在 Unix 系统中，换行符为 \n（LF）。而路径分隔符在 Windows 系统中为 \，而在 Unix 系统中为 /。

在面对这些问题时，我们其实是有一些技巧的。比如处理路径时，我们可以使用 Path 类，它会根据当前操作系统的不同，返回不同的路径分隔符：

1
2
3
4
5


var folder = "MyFolder";
var subfolder = "MySubFolder/";
var filename = "MyFile.txt";

var path = Path.Combine(folder, subfolder, filename);

这个方法不仅可以帮助我们处理路径分隔符，还可以帮助我们处理路径的拼接，以及路径的规范化。比如上面的例子中，subfolder 末尾多了一个 /，但是 Path.Combine 方法会自动帮我们去除这个多余的 /。

类似地，面对换行符的问题，我们可以使用 Environment.NewLine 来获取当前操作系统的换行符。比如我们可以用下面的方式拼接一个多行字符串：

1
2
3
4
5
6
7


var lines = new string[]
{
 "Hello, World!",
 "Good, Morning!"
};

var text = string.Join(Environment.NewLine, lines);

Tip

类似 Environment.NewLine 这样的属性，我们还有 Path.DirectorySeparatorChar、Path.PathSeparator 等，它们都可以帮助我们处理一些与操作系统有关的问题。

不仅如此，.NET 6 还为我们提供了一个新方法：ReplaceLineEndings。这个方法可以帮助我们将字符串中的换行符统一为当前操作系统的换行符：

1
2
3
4
5
6
7
8


var text = "Hello, World!\r\nGood morning!\nGood night!";

// 如果不传参，则默认将换行符替换为当前操作系统的换行符
var normalized = text.ReplaceLineEndings();

// 如果传入参数，则将换行符替换为指定的换行符
var normalized = text.ReplaceLineEndings("\n");
var normalized = text.ReplaceLineEndings("\t");

其实很多时候，我们根本不需要显式地与换行符打交道。因为 .NET 的很多方法都会自动帮我们处理这些问题，比如：

1
2
3
4
5
6
7
8


var lines = File.ReadAllLines("file.txt");
File.WriteAllLines("file.txt", lines);

Console.WriteLine("..."); // 在控制台输出文本，并自动换行
Console.ReadLine(); // 读取用户输入，并自动处理换行符

var sb = new StringBuilder();
sb.AppendLine("Hello, World!");

等等。这些方法的名称中都会包含 Line 这个单词，大加可以多多留意。

StringBuilder 的一些技巧

StringBuilder 可能是一个对于大家来说，既熟悉又陌生的类。熟悉是因为我们在处理大量字符串拼接时，都会用到它，陌生是因为我们可能并不了解它的所有功能。这里我就不多赘述了，我用一小段代码来展示 StringBuilder 的一些技巧：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


var sb = new StringBuilder();

// 添加字符串
sb.Append("Hello, World!");
sb.AppendLine("Hello, World!");
sb.AppendFormat("Hello, {0}!", "World");
sb.Append('H', 5); // 添加 5 个 'H'

sb.Insert(0, "Hello, "); // 在指定位置插入字符串
sb.Replace("Hello", "Good"); // 替换字符串
sb.Remove(0, 5); // 删除指定位置的字符串
sb.Clear(); // 清空 StringBuilder

sb.ToString(); // 将 StringBuilder 转为字符串
sb.ToString(0, 5); // 将 StringBuilder 的一部分转为字符串

没想到吧，连它的 ToString 方法都包含一个类似 SubString 的重载，方便我们减少一次不必要的内存开销。

拥抱语法糖，使用字符串内插

在 C# 6 中，我们迎来了字符串内插（String interpolation）这个语法糖。这个语法糖可以帮助我们更加方便地拼接字符串，而且还可以在字符串中插入表达式。比如：

1
2
3
4
5
6
7


var name = "World";
var age = 18;

var str = $"Hello, {name}! You are {age} years old.";

// 在以前，我们可能会写出下面这样的代码
var str = string.Format("Hello, {0}! You are {1} years old.", name, age);

实际上，这个语法糖的作用远不止于此，它的性能是高于 string.Format 的。甚至因为它性能的提升，我们在使用 StringBuilder 时，都可以考虑使用字符串内插来代替 AppendFormat。不过，对于这种情形，性能最高的方式是连续使用 Append 方法，形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var id = 123;
var name = "World";
var age = 18;

var sb = new StringBuilder();

// 使用 AppendFormat
sb.AppendFormat("ID: {0}, Name: {1}, Age: {2}", id, name, age);

// 使用字符串内插
sb.Append($"ID: {id}, Name: {name}, Age: {age}");

// 使用连续的 Append 方法
sb.Append("ID: ").Append(id).Append(", Name: ").Append(name).Append(", Age: ").Append(age);

总结

除此之外，字符串还有很多技巧，比如：

原始字符串（Raw string）
StringPool 与 string.Intern
Span<char>
文本编码（Encoding）
一些与字符串有关的特性

但是因为篇幅的关系，我们这次就不展开了。希望大家能够通过这篇文章，了解到一些 C# 字符串操作的实用技巧和易犯错误。希望大家在以后的开发中，能够更加熟练地使用字符串，写出更加高效的代码。

如何读写 INI 配置文件？

Thu, 11 Jul 2024 00:00:00 +0000

INI 文件是一种相当古老的配置文件格式，但很“可惜”的是，它如今依旧被广泛使用。正因为如此，即便现在已经出现了很多更加现代化的配置文件格式（比如 JSON、YAML、TOML 等），我们仍然可能会遇到读写 INI 文件的情形。那么这次我们就来看看如何在 C# 中读写 INI 文件。

INI 文件格式概述

INI 文件是一种文本文件，它由一系列的节（Section）和键值对（Key-value pair）组成。每个键值对都位于某个节中，键和值位于等号（=）左右，而节则由方括号（[]）括起来。一个简单的 INI 文件看起来可能是这样的：

1
2
3
4
5
6
7


[Section1]
Key1=Value1
Key2=Value2

[Section2]
Key3=Value3
Key4=Value4

此外，INI 文件还支持注释，通常以分号（;）开头（有时也可以自定义为其他符号，比如 # 等），直到行尾为止：

1
2


[Section1]
Key1=Value1 ; 这是一个注释

INI 文件的格式要求基本就是这样了。其他可能还有一些诸如命名习惯，以及等号左右是否添加空格等细节，但这些通常都是没有具体约束的。

不难发现，INI 因为格式极其简单，所以它的解析也是相当容易的，我们稍加思考，通常就可以写出一个简单的解析器。但是，既然已经有现成的解析库，我们当然不必自己重复造轮子。接下来我们就来看看在 C# 中如何读写 INI 文件。

传统方法：使用 Win32 API

相信大家只要在网上搜索过这个问题，就一定会看到有人推荐使用 Win32 API 来读写 INI 文件。这种方法的优点是简单、高效，但缺点也很明显：它是不跨平台的。如果你的程序需要在 Linux 或 macOS 上运行，那么这种方法就不适用了。

INI 文件的读写操作在 Windows 平台上有专门的 API 支持，这些 API 位于 kernel32.dll 中。我们可以通过 P/Invoke 的方式调用这些 API，实现对 INI 文件的读写。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


using System;
using System.Runtime.InteropServices;

[DllImport("kernel32")]
private static extern long WritePrivateProfileString(string section, string key, string val, string filePath);

[DllImport("kernel32")]
private static extern int GetPrivateProfileString(string section, string key, string def, StringBuilder retVal, int size, string filePath);

public string IniReadValue(string Section,string Key)
{
 StringBuilder temp = new StringBuilder(256);
 int i = GetPrivateProfileString(Section,Key,"",temp, 256, this.path);
 return temp.ToString();
}

我们只需要从 kernel32.dll 中导入 WritePrivateProfileString 和 GetPrivateProfileString 两个函数，就可以实现对于 INI 文件的读写操作了。通常情况下，我们还会额外写一个 IniReadValue 方法来包装 GetPrivateProfileString 函数，以便更加方便地读取键值。

Info

除了上面的两个方法，kernel32.dll 中还有一些其他的函数，比如 GetPrivateProfileSection、GetPrivateProfileSectionNames 等，它们可以帮助我们更加方便地操作 INI 文件。有兴趣的读者可以自行查阅相关文档。

但是大家在使用这个库的时候，不知道会不会有一种仿佛“高射炮打蚊子”一样的心情？毕竟 INI 这么简单的一种格式，居然要使用到 P/Invoke 来调用 Win32 API，这未免也太麻烦了。所以，这种传统方式存在以下问题：

使用体验差：需要通过 P/Invoke 来调用 Win32 API，这对于 C# 开发者来说并不是一种友好的体验。
不跨平台：这种方法只能在 Windows 平台上使用，无法在 Linux 或 macOS 上运行。
线程不安全：由于这是一个全局函数，每次调用都会操作外部文件，所以在多线程环境下可能会出现问题。
时间复杂度高：假如我们想要读取 INI 文件中的多个键值对，那么就需要多次调用 GetPrivateProfileString 函数，而每次调用都需要从文件开头开始读取，直到找到对应的键值对。这样的时间复杂度显然是不够理想的。
文本编码：这种方法只会使用系统默认的文本编码（比如中文操作系统的 ANSI 对应 GBK 编码），无法指定其他编码，因此非 ASCII 字符可能会出现乱码。

所以下面我们再介绍几个别的库。但是大家也不要高兴太早，因为这些库虽然各有优点，但也有各自的问题。

第三方库：Ini-Parser

ini-parser 是一款非常好用的 INI 文件解析库。它可以一次性将整个 INI 文件解析为一个 IniData 对象（可以想象成一个字典），从而方便我们像操作字典那样便捷又高效地进行高频率的读写操作，并在最后统一写回文件。

Tip

大家在 NuGet 中搜索 ini-parser 时，还会发现 ini-parser-netstandard 这个库。这两个库的功能是一样的，只是前者是 .NET Framework的，而后者则是 .NET Standard 2.0 的，因此可以在 .NET Core、.NET 5+ 及跨平台环境中使用，甚至还可以用于 Unity 游戏开发。推荐大家在任何情况下都使用后者。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


using IniParser;

var parser = new FileIniDataParser();
IniData data = parser.ReadFile("config.ini");

// 读取键值对
string value1 = data["Section1"]["Key1"];
string value2 = data["Section1"]["Key2"];

// 修改键值对
data["Section1"]["Key1"] = "NewValue1";
data["Section1"]["Key2"] = "NewValue2";

// 写回文件
parser.WriteFile("config.ini", data);

除此之外，它还支持更多功能，比如合并多个 INI 文件等。大家可以查看官方文档来了解更多信息。

但是，这个库有一个非常明显的限制：虽然它一次性读取了整个 INI 文件，使得我们在需要频繁读写时更加高效。但是当文件较大时，一次性读取整个文件可能会导致占用更大的内存；不仅如此，如果我们的需求仅仅是临时读写某一项配置，那么这种一次性读取整个文件的方式显然是不够高效的。

所以这里再和大家推荐另外一个库。

第三方库：IniSharp

IniSharp 真是一个不错的名字。这个库提供了便捷的操作 INI 文件的方法，并且不依赖 Win32 API，因此可以在跨平台环境下使用。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


using IniSharp;

var ini = new IniFile("config.ini", Encoding.UTF8);

var value1 = ini.GetValue("Section1", "Key1");
var value2 = ini.GetValue("Section1", "Key2", "Default"); // 如果该键不存在，则创建并返回默认值

ini.SetValue("Section1", "Key1", "NewValue1");

ini.DeleteKey("Section1", "Key2");

ini.DeleteSection("Section2");

List<string> sections = ini.GetSections();
List<string> keys = ini.GetKeys("Section1");

这个库并不会一次性读取整个 INI 文件，而是在每次操作时进行读取或写入操作，因此不会占用过多的内存。这在我们的需求是临时读写某一项配置时显得尤为重要。

但是我仍然要泼大家一盆冷水：这个库的性能并不高，因为它底层的代码存在一些值得优化的空间。以读取单个键值的方法为例（以下代码为节选，并不完整）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


// 它在底层声明了一个“碰巧”与 Win 32 API 一样的函数名
private string GetPrivateProfileString(string section, string key, string defaultValue = null)
{
 List<string> lines = File.ReadAllLines(filePath, FileEncoding).ToList();
 (int sectionNum, int keyNum) = FindSectionAndKey(section, key, lines);
 if (sectionNum != -1 && keyNum != -1)
 {
 int startIndex = lines[keyNum].IndexOf(key);
 int equalsIndex = lines[keyNum].IndexOf('=', startIndex + key.Length);
 string strLalue = lines[keyNum].Substring(equalsIndex + 1);
 int hashIndex = strLalue.IndexOf(commentChar);
 return (hashIndex != -1) ? strLalue.Substring(0, hashIndex) : strLalue;
 }
 if (defaultValue != null)
 {
 if (sectionNum != -1)
 {
 if (keyNum == -1)
 {
 lines.Insert(sectionNum + 1, $"{key}={defaultValue}");
 lock (lockObject)
 {
 File.WriteAllLines(filePath, lines, FileEncoding);
 }
 }
 }
 else
 {
 lock (lockObject)
 {
 using (StreamWriter sw = File.AppendText(filePath))
 {
 sw.WriteLine($"[{section}]");
 sw.WriteLine($"{key}={defaultValue}");
 }
 }
 }
 }
 return defaultValue;
}

不难看出几个问题：

它使用的是 ReadAllLines() 方法，而不是采用 ReadLines() 方法返回一个延迟加载的 IEnumerable<string>，或使用 StreamReader 逐行读取。这样会导致一次性读取整个文件，占用更多内存。尤其是即便我们要找的键就在文件的开头，它也会从头读取整个文件，这显然是不够高效的。
它使用了 File.WriteAllLines() 方法，每次修改都会重写整个文件。
在插入新键值对时，它使用了 List.Insert() 方法，这会导致整个列表的元素向后移动，时间复杂度为 O(n)。

除此之外，这个库还有其他一些提升空间，比如可以使用 Span、ArrayPool 等，来减少内存分配和 GC 压力。

总结

上面提到的几种方式可以说是各有千秋，总会存在一些缺憾，因此关于 INI 这么简单的一个文件格式，我们的故事并没有结束。在后续的文章中，我还会和大家分享更多关于 INI 文件的读写方法，以及一些优化技巧。欢迎大家继续关注我的博客。

为什么我们一般不使用公共字段，而是选择自动属性？

Thu, 13 Jun 2024 00:00:00 +0000

在写 C# 代码的时候，我们经常会写诸如此类的自动属性：

1
2
3
4


public Person
{
 public int Age { get; set; }
}

这时候相信很多人都会有疑问：为什么我们要费劲写成这样的自动属性？为什么不能直接简单地把它写成一个公共字段呢？就比如这样：

1
2
3
4


public Person
{
 public int Age;
}

其实这是有一些原因的。我们这次就来探讨一下。

看待属性与字段的方式不同

首先最重要的，就是我们看待属性与字段的方式，或者对于它们所扮演的角色的理解是不一样的。

当我们看到一个属性时，通常我们都会期望它拥有一个公共的读权限，同时拥有一个可能不公开的写权限还可能在初始化上存在一些限制。通常我们写一个属性时，都是希望它存在被外界访问的价值，并且我们也充分考虑了后果（比如我们可以在 setter 中添加逻辑，或干脆不开放 setter）。

也就是说，通常情况下我们希望一个属性它是一个：

（一般情况下）可以在类外被访问到，并且具有一定的意义，是开发者故意暴露出来的成员
它的初始化可能包含一些逻辑，比如可以在什么时候被初始化，是否必须被初始化，初始化后还能否更改等
它后台未必一定对应一个字段，而是会通过一些方式来得到它的值

Info

对于第 3 条，我可以举出一些例子：

List.Count 实际与底层的 Array 的长度有关
AsyncRelayCommand.IsRunning 与底层的 Task 的状态有关
ObservableValidator.HasErrors 与底层用于存放错误信息的列表有关
CheckBox.IsChecked 与底层的依赖属性有关

但是当我们看到字段时，通常会怎么考虑呢？我们先来看一段简单的代码：

1
2
3
4
5
6
7


class Manager
{
 private readonly int _uniqueId; // 一个可能有特殊作用的唯一 ID
 private readonly IConfiguration _config; // 一个通过依赖注入的方式在构造中初始化的接口对象
 private bool _flag = false; // 一个只用于内部方法间传递状态的标志位
 private readonly object _syncRoot = new(); // 一个只用于类内部的线程锁
}

大家对于字段的印象是否一般都是这样的呢？如果是的话，那么相信在看到下面的代码时，一定会有点恍惚和不知所措吧：

1
2
3
4
5
6


class Manager
{
 protected readonly int UniqueId;
 public bool Flag = false;
 public string ErrorMessage = "Oops!";
}

所以这里面的道理相信大家应该已经有一定感觉了。是的，我们通常对于字段所扮演角色的理解是：

它通常只用于类内，作为其他属性或方法的辅助角色（比如线程锁、标志位、依赖注入的对象等）
它通常不包含太多的逻辑，只是一个简单的值，而且也不如属性那样具有多种初始化的方式
它通常不太“安全”，或者说开发者在不了解的情况下不太敢轻易去操作它

基于这样不同的看待方式，相信大家应该都能理解为什么我们一般不直接使用公共字段了。

当然了，例外情况肯定也是有的。比如说我们在开发一个简单的 Unity 游戏，那么通常我们会写出这样的代码：

1
2
3
4
5
6
7


public class Player : MonoBehaviour
{
 [SerializeField]
 private int health; // Unity 官方推荐的命名习惯是首字母小写
 public int attack;
 public int defense;
}

或者当我们想要与 C/C++ 写的 DLL 交互时，我们可能会写出这样的代码：

1
2
3
4
5
6
7


[StructLayout(LayoutKind.Sequential)]
public struct MyData
{
 public ushort Index;
 public uint Value;
 public byte[] Data;
}

这些情况下，我们可能会直接使用公共字段，而不是属性。

长期的约定俗成

既然我们有这样不同的看待方式，所以就出现了相当多类似的开发习惯，甚至连标准库及第三方库也在有意无意贯彻着这样的习惯。

Info

当然了，这里面其实还有一个“先有鸡还是先有蛋”的问题。也就是说，我们是因为有了这样的习惯，所以才会有这样的标准库设计，还是因为标准库设计的如此，所以我们才会有这样的习惯呢？不过这个问题就不在我们的讨论范围内了。

这里我可以举很多例子：

在 WPF 开发中，如果你想在 XAML 中绑定一个类（通常为 Model 或 ViewModel）的变量，那么这个变量必须是一个属性，而不能是一个字段。此外，WPF 中另一个相当重要的功能——依赖属性——也会充分和属性打交道。
在进行类的序列化与反序列化时，Json.NET、System.Text.Json 等库默认只会序列化属性，而不会序列化字段。
DataGrid、PropertyGrid 等会根据数据类型来自动生成界面的控件都是关注属性而非字段。
在 EntityFramework Core 中，如果你想要使用代码优先（Code-First）的方式，那么你的实体类中的属性必须是属性，而不能是字段；而使用数据库优先（Database-First）的方式时，工具自动生成的也是属性。
C# 的接口可以包含属性，但不能包含字段。
C# 的记录类（record）底层也是使用属性来实现的。

其他还有一些别的例子，比如我们在使用数据映射的工具（如 Mapster、AutoMapper 等）时，可能也会发现属性和字段的一些不同之处。

所以，既然这样的习惯广泛存在，我们为什么要选择做一个另类的开发者呢？

灵活性与封装性

属性具有无与伦比的灵活性。我们可以在属性的 getter 和 setter 中添加任意的逻辑，比如数据校验：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public class Person
{
 private int _age;

 public int Age
 {
 get => _age;
 set
 {
 if (value < 0)
 {
 throw new ArgumentOutOfRangeException(nameof(value), "Age must be greater than 0.");
 }

 _age = value;
 }
 }
}

再比如通知功能：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class ViewModel : INotifyPropertyChanged
{
 private string _name;

 public string Name
 {
 get => _name;
 set
 {
 if (_name != value)
 {
 _name = value;
 OnPropertyChanged(nameof(Name)); // 事件与方法的实现略
 }
 }
 }
}

但更重要的是它的封装性。比如常见的 setter 就有这么几种：

public：公共的 setter，任何人都可以修改这个属性
protected：受保护的 setter，只有继承这个类的子类才能修改这个属性
private：私有的 setter，只有这个类内部的方法才能修改这个属性
internal：内部的 setter，只有同一个程序集内的方法才能修改这个属性
init：初始化 setter，只能在构造函数中初始化这个属性
空：只读属性，只能在构造函数中初始化这个属性

不仅如此，还可以配合诸如 required、virtual 等关键字，使得属性的灵活性和封装性更上一层楼。这些都是字段完全无法比拟的（我知道上面的一些关键字也可以用于字段，但效果都很有限，比如会同时限制读写的权限等）。

性能方面的考虑

这时候可能有同学又要说了：我知道自动属性其实是个语法糖，最终还是会被编译器转换成字段和方法，形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


class Person
{
 [CompilerGenerated]
 private int <Age>k__BackingField;

 public int Age
 {
 [CompilerGenerated]
 get
 {
 return <Age>k__BackingField;
 }
 [CompilerGenerated]
 set
 {
 <Age>k__BackingField = value;
 }
 }
}

那么调用方法去读写字段的值，效率上理应比直接读写字段要低对吧？如果是这样的话，把 { get; set; } 这样的自动属性直接写成公共字段，不是更好吗？

这是个好问题，我们来看这样一个例子。下面的 Person 类中，我们定义了两个属性，一个是自动属性，一个是字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var p = new Person();

p.Age1 = 10;
p.Age2 = 20;

public class Person
{
 public int Age1 { get; set; }
 public int Age2; 
}

如果我们观察 IL 代码，会发现：

1
2
3
4
5
6
7


IL_0000: newobj instance void Person::.ctor()
IL_0005: dup
IL_0006: ldc.i4.s 10
IL_0008: callvirt instance void Person::set_Age1(int32)
IL_000d: ldc.i4.s 20
IL_000f: stfld int32 Person::Age2
IL_0014: ret

好像确实不大对劲啊。Age1 就是使用了 Person::set_Age1 方法，而 Age2 却直接使用了 stfld 指令。那是不是说明修改属性的速度就是会略微慢于直接修改字段呢？先别急，我们再来看一看 JIT 编译后的代码：

1
2
3
4
5
6


Program.<Main>$(System.String[])
 L0000: mov ecx, 0x33a4ca1c
 L0005: call 0x066f300c
 L000a: mov dword ptr [eax+4], 0xa
 L0011: mov dword ptr [eax+8], 0x14
 L0018: ret

这里我们可以看到，自动属性的 setter 其实会被 JIT 编译器优化成直接的内存写入操作。这就意味着，实际上在运行时，修改属性和直接修改字段的速度是一样的。所以，自动属性的性能和公共字段是完全一样的。大家大可以打消这个顾虑了。

.NET 9 即将到来的新语法特性

如果你还在犹豫的话，我还可以再告诉你一个好消息：.NET 9（C# 13）即将引入一个新语法特性：field 关键字（这个关键字曾经在 C# 11 的时候就释放过信号，但因为一些原因姗姗来迟）。这个新特性可以让你更加方便地声明一个属性。

我们都知道，以前我们写完整属性（propfull）时，需要写成这样：

1
2
3
4
5
6
7


private int _age;

public int Age
{
 get => _age / 2;
 set => _age = value * 2;
}

但是现在，有了 field 关键字，我们可以这样写：

1
2
3
4
5


public int Age
{
 get => field / 2;
 set => field = value * 2;
}

这里的 field 就相当于那个 _age 字段。这样一来，我们就可以更加方便地声明一个属性了。

总结

通过上面的讨论，相信大家对于为什么我们一般不使用公共字段，而是选择自动属性有了更深的理解。当然了，这并不是说我们就不能使用公共字段了。在一些特殊的场景下，我们还是可以使用公共字段的。但是在大多数情况下，我们还是应该选择自动属性。

C# 后面不断新增的语法特性，一直在优化我们使用属性的体验。在比较旧的 C# 版本中，我们甚至不能给自动属性直接赋值，而是需要通过构造函数来初始化。但是随着 C# 版本的不断更新，我们可以看到，自动属性的使用变得越来越方便了。除了上面提到的即将到来地 field 关键字，我们在 C# 9 还迎来了记录类型，在 C# 12 又迎来了主构造函数。这些都是为了让我们更加方便地使用属性。

相信大家今后可以更加无忧无虑地使用属性。

如何在 C# 中模拟 Go 的 defer 关键字并用于客户端开发

Tue, 28 May 2024 00:00:00 +0000

Go 中的 defer 大概是怎么一回事

Go 语言中有一个非常好用的 defer 关键字。defer 会在函数返回之前执行，可以用来释放资源，关闭文件等。比如我们想打开并读取一个外部文件的内容，我们可以这样写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


func ReadFile() {
 file, err := os.Open("file.txt")

 // 如果打开文件失败，直接返回
 if err != nil {
 log.Fatal(err)
 }

 // 在函数返回之前关闭文件
 defer file.Close()

 // 读取文件内容
 content := make([]byte, 1024)
 file.Read(content)
 fmt.Println(string(content))
}

在这个例子中，我们使用 defer 关键字来确保在函数返回之前关闭文件。这样我们就不用担心忘记关闭文件，导致资源泄漏。

其实在 C# 和 Python 中，我们也可以借助一些特殊的语法来实现类似的效果。比如在 C# 中，我们可以使用 using 关键字来确保资源在使用完之后被释放；在 Python 中，我们可以使用 with 关键字来确保资源在使用完之后被释放。

但有些时候，我们想要实现的功能只是希望在离开作用域之前执行一些代码，而不是释放资源。这种情况下，我们仍然可以借助 using 关键字来实现，可以为我们带来意想不到的便利。

在 C# 中模拟 Go 的 defer

前面已经提到，我们需要在 C# 中使用 using 关键字来模拟 Go 的 defer。但是 using 关键字只能用于“释放资源”，或者说需要对一个实现了 IDisposable 接口的对象进行操作。那么我们就必须实现 Dispose 相关的逻辑了。话虽如此，并没有人规定我们必须在 Dispose 方法中执行释放资源的逻辑。比如我们前面提到的，希望在离开作用域之前执行一些代码，就可以放在 Dispose 方法中去执行。

基于这个思路，我们可以写出这样的代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class MyDisposable : IDisposable
{
 private readonly Action _callback;

 public MyDisposable(Action callback)
 {
 _this._callback = callback;
 }

 public void Dispose() => _callback();
}

这样我们就可以在 Dispose 方法中执行我们想要执行的代码了。比如我们可以这样使用：

1
2
3
4
5
6


void Foo()
{
 using var md = new MyDisposable(() => Console.WriteLine("Job is done."));

 // Do something
}

我们在上面的例子中还用到了 C# 8.0 的新特性：using 语法的改进。在 C# 8.0 中，我们可以省略 using 语句中的大括号，直接在 using 语句后面写一个表达式。这样我们就可以更加简洁地使用 using 语法了。

它实际对应的底层 C# 代码是这样的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


void Foo()
{
 MyDisposable md = new MyDisposable(() => Console.WriteLine("Job is done."));
 try
 {
 // Do something
 }
 finally
 {
 if (md != null)
 {
 md.Dispose();
 }
 }
}

所以可以保证 finally 语句中的代码一定会被执行，即使在 try 语句中抛出了异常。

这一技巧在 WPF 开发中的妙用

其实这个小妙招并不是我的原创，而是油管上的 Jason Williams 在他的一期视频中提到的。在他的视频中，他为我们提供了一个绝妙的点子。

我们在做 WPF（以及其他诸如 Win UI、Avalonia 等）的客户端开发时，经常会遇到一个问题，就是需要去管理一个进度条的可见状态。比如我们现在有一个异步任务，我们希望任务在执行期间能够显示一个进度条，任务执行完毕（不管成功与否）后进度条消失。通常我们的做法是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// 模拟搜索电影的异步任务
public bool IsBusy { get; set; } = false; // 控制进度条是否可见，且该属性具备通知功能

async Task SearchMovieAsync(string movieName)
{
 IsBusy = true;

 if (!CanSearch())
 {
 IsBusy = false;
 return;
 }

 var resList = await SearchMoviesFromInternetAsync(movieName);
 if (resList == null || resList.Count == 0)
 {
 IsBusy = false;
 return;
 }

 foreach (var res in resList)
 {
 // Do something
 }

 IsBusy = false;
}

可以看到，我们在方法中需要多次根据情况设置 IsBusy 属性。这样的代码看起来不太优雅。为了解决这个问题，我们就可以用上前面实现的类了。不过我们需要稍微修改一下，使它的回调函数可以接受一个参数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class BusyDisposable : IDisposable
{
 private readonly Action<bool> _busySetter;

 public BusyDisposable(Action<bool> busySetter)
 {
 _busySetter = busySetter;
 _busySetter(true);
 }

 public void Dispose() => _busySetter(false);
}

然后我们就可以这样使用了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


async Task SearchMovieAsync(string movieName)
{
 using var _ = new BusyDisposable(value => IsBusy = value);

 if (!CanSearch())
 {
 return;
 }

 var resList = await SearchMoviesFromInternetAsync(movieName);
 if (resList == null || resList.Count == 0)
 {
 return;
 }

 foreach (var res in resList)
 {
 // Do something
 }
}

Info

这里有一个需要注意的点：我们是在 ViewModel 中对 IsBusy 进行的操作，并借助绑定来控制前台进度条的显示。这无形中帮助我们解决了一个重要的隐患：线程安全。即便我们在非 UI 线程中修改了 IsBusy 属性，由于 WPF 的数据绑定机制，我们也不用担心线程安全问题。

但如果是在 View 中去直接操作进度条的 Visibility 属性，那么就可能需要我们自己去处理线程安全问题了。常见的方式比如使用 Dispatcher，或参考我的这篇关于使用 IProgress 的文章。

相信大家立刻就能够明白这个方式有多么简洁和优雅了。我们通过使用 using 关键字，保证了当前作用域中的代码不管是正常执行还是异常退出，都会在离开作用域之前执行 IsBusy = false 这一行代码。这样我们就不用在方法中多次设置 IsBusy 属性了。

甚至我们还能再稍微优化一下，比如使用一个自动属性来简化 BusyDisposable 的实例化：

1
2
3
4
5
6
7
8
9


private BusyDisposable NewBusyDisposable 
 => new BusyDisposable(value => IsBusy = value);

async Task SearchMovieAsync(string movieName)
{
 using var _ = NewBusyDisposable;

 // ...
}

这样我们就可以进一步简化这一语法，从而使其更接近 Go 语言中的 defer 关键字的使用方式。

总结

本期内容主要介绍了 Go 语言中的 defer 关键字，以及如何在 C# 中模拟 defer 的实现。虽然我们似乎一定程度上“滥用”了 using 关键字以及 IDisposable 接口，但这种方式确实可以带来一些意想不到的便利。

油管上的这位 Jason Williams 也绝对是一位大神。虽然他视频非常少，粉丝也只有几百，但是每期内容都堪称精品。大家有机会的话也可以去关注一下他，相信一定会有所收获。

如何在异步任务中汇报进度

Thu, 09 May 2024 00:00:00 +0000

在执行异步任务时，有时候我们会希望有办法汇报进度。比如在一个 WPF 程序中，我们在界面上放了一个进度条，从而展示当前任务的进度。那么该如何汇报异步任务的进度呢？

其实 .NET 标准库就为我们提供了实现这一功能的接口和类：IProgress<T> 与 Progress<T>，其中 T 是一个泛型类型，表示要汇报的内容。如果我们希望汇报一个百分比进度，那么使用 double 类型即可；类似地，如果我们希望汇报一些更加复杂的内容，还可以使用 string 甚至一些自定义类与结构体。

下面我们就来看看该如何使用吧。

搭建项目

首先我们创建一个简易的 WPF 项目。因为这次的任务比较简单，所以我们就不遵循 MVVM 模式了，而是使用最传统的 WPF 事件注册的方式。

它的 MainWindow 形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<Window ...>
 <StackPanel VerticalAlignment="Center">
 <Button Width="100"
 Margin="0,0,0,10"
 Content="Run"
 Click="Button_Click" />
 <ProgressBar Height="20"
 d:Value="10"
 Name="progressBar" />
 </StackPanel>
</Window>

然后在 MainWindow.xaml.cs 中实现一些简单的逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


public partial class MainWindow : Window
{
 public MainWindow()
 {
 InitializeComponent();
 }

 private async void Button_Click(object sender, RoutedEventArgs e)
 {
 await DoJobAsync(CancellationToken.None);
 }

 async Task DoJobAsync(CancellationToken token)
 {
 if (token.IsCancellationRequested)
 return;
 for (int i = 0; i < 100; i++)
 {
 await Task.Delay(50, token);
 progressBar.Value = i + 1;
 if (token.IsCancellationRequested)
 {
 break;
 }
 }
 }
}

我们将按钮注册的 Button_Click 方法修改为 async void，这样我们就可以在里面等待一个异步任务了。

Info

虽然 async void 是一种非常危险的方式，但因为 Button 控件的 Click 事件对应委托对于函数传参及返回值的限制，这里我们不得不这样做。

然后，我们在 DoJobAsync 中实现后台的异步任务。这里我们简单地使用一个 for 循环，并在其中使用 Task.Delay，从而实现一个拥有进度的异步任务。然后，我们在每次循环中直接修改 progressBar 控件的值。运行程序，就可以直接看到效果了：

这个问题难道就这么轻松地就解决了吗？其实不是的，因为在异步任务中，很可能会出现在别的线程中操作 UI 线程的资源（也就是控件及其属性），这种情况下程序会报错。所以如果使用这样的方式，通常我们还需要使用老套的 Dispatcher.Invoke 的方式来规避这个问题。但这样就显得不够优雅了。

那么同样的功能，我们该如何使用 Progress 类来实现呢？

使用 Progress 类

首先我们需要稍稍修改一下 DoJobAsync 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


async Task DoJobAsync(IProgress<double> reporter, CancellationToken token)
{
 for (int i = 0; i < 100; i++)
 {
 if (token.IsCancellationRequested)
 return;
 await Task.Delay(50, token).ConfigureAwait(false);
 reporter.Report(i + 1);
 if (token.IsCancellationRequested)
 {
 break;
 }
 }
}

然后，这个 Progress 类的实例来自哪儿呢？我们再修改一下 Button_Click 方法：

1
2
3
4
5


private async void Button_Click(object sender, RoutedEventArgs e)
{
 var reporter = new Progress<double>(value => progressBar.Value = value);
 await DoJobAsync(reporter, CancellationToken.None);
}

就这样，我们只需要在使用的时候实例化一个新的即可。它除了我们前面提到的泛型，还传入了一个回调函数，表示每次 Report 时需要执行的逻辑。这里的逻辑非常简单，只需要将传入的 double 类型的数字赋值给进度条的 Value 属性即可。

那么问题来了：它是如何规避了前面提到的线程问题的呢？我们观察 Progress 类的源代码，可以发现：

1
2
3
4
5
6
7
8


public Progress()
{
 // Capture the current synchronization context.
 // If there is no current context, we use a default instance targeting the ThreadPool.
 _synchronizationContext = SynchronizationContext.Current ?? ProgressStatics.DefaultContext;
 Debug.Assert(_synchronizationContext != null);
 _invokeHandlers = new SendOrPostCallback(InvokeHandlers);
}

在它的构造函数中，拥有一个 SynchronizationContext 对象，它持有了当前的同步上下文。当我们在 Button_Click 方法中声明它时，因为还在 UI 线程，所以它就保存了这个上下文。然后在它的 Report 方法被调用时，就会在正确的同步上下文（也就是 UI 线程）中执行相关逻辑了。

Info

除了给构造函数传回调，Progress 类还为我们提供了一个 ProgressChanged 事件。注册这个事件可以实现相同的效果，并且也是在相同的同步上下文执行的。

实现自定义 Progress 类

如果我们还有其他额外的需求，那么我们还可以自己实现接口，或者继承 Progress 类。官方特意没有将这个类设为 sealed，并且将 OnReport 方法设为 virtual，就是为了满足我们的这些需求。

Note

但是如果我们去继承这个 Progress 类，会发现其实我们能自由发挥的空间并不大，因为它其中的很多字段（尤其是同步上下文）都是 private 的，所以我们能做的事情基本上也只有重写 OnReport 方法了。

比如这里我写了一个子类，从而可以在进度完成后执行一个回调方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


class MyProgress<T> : Progress<T> where T : notnull
{
 private readonly Action? _complete;
 private readonly T _maximum;
 private bool _isCompleted;

 public MyProgress(Action<T> handler, Action? complete, T maximum)
 : base(handler)
 {
 _complete = complete;
 _maximum = maximum;

 ProgressChanged += CheckCompletion;
 }

 protected override void OnReport(T value)
 {
 if (_isCompleted)
 return;
 base.OnReport(value);
 }

 private void CheckCompletion(object? sender, T e)
 {
 if (e.Equals(_maximum) && !_isCompleted)
 {
 _isCompleted = true;
 _complete?.Invoke();
 }
 }
}

然后我们就可以这样使用了：

1
2
3
4
5
6
7
8
9


private async void Button_Click(object sender, RoutedEventArgs e)
{
 var reporter = new MyProgress<double>(
 value => progressBar.Value = value,
 () => progressBar.Visibility = Visibility.Hidden,
 100
 );
 await DoJobAsync(reporter, CancellationToken.None);
}

这里实现的效果是，当异步任务完成后，将会隐藏进度条。

总结

不知道大家看完这篇文章的感受如何。其实我在最开始了解文中提到的 IProgress 接口以及 Progress 类时，最大的感受是：微软究竟为我们提前准备好了多少接口和类啊🤣！

.NET 类中有太多这样的标准库了，但我们也没有什么办法去系统地挖掘与总结。所以只能仰仗大家今后持续不断的交流与学习了。

参考

How to Report Progress with Async/Await in .NET Core 3 - YouTube

C# Advanced Async - Getting progress reports, cancelling tasks, and more - YouTube

如何在 WPF 中实现符合 MVVM 模式的文件拖入功能

Wed, 08 May 2024 00:00:00 +0000

本篇文章对应的教学视频链接：WPF中如何实现符合MVVM模式的文件拖入功能

原始方式

在 WPF 中，实现文件拖入功能并不难。稍微在网上搜索一下，就能够得到答案。比如现在有一个窗口，我们只需要设置它的 AllowDrop 属性为 True，然后在 Drop 事件中处理即可。形如：

1
2
3


<Window ...
 AllowDrop="True"
 Drop="Window_Drop">

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public partial class MainWindow : Window
{
 public MainWindow()
 {
 InitializeComponent();
 }

 private void Window_Drop(object sender, DragEventArgs e)
 {
 if (e.Data.GetDataPresent(DataFormats.FileDrop))
 {
 var files = (string[])e.Data.GetData(DataFormats.FileDrop);
 // 处理拖入的文件
 }
 }
}

添加视图模型

但问题是，如果现在 Window 拥有一个视图模型（ViewModel），形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public class MainViewModel : ViewModelBase
{
 private string? _fileName;
 public string? FileName
 {
 get => _fileName;
 set
 {
 _fileName = value;
 OnPropertyChanged(this, nameof(FileName));
 }
 }
}

Info

这里我们假定已经实现了 ViewModelBase 类，它实现了 INotifyPropertyChanged 接口，并提供了 OnPropertyChanged 方法以便于通知属性发生了变化。

然后 Window 上面有一个 TextBox 绑定了这个属性，这又该怎么办呢？

这里有两种比较简单粗暴的方式：

为 TextBox 添加一个 Name，然后在 Window 的 Drop 事件中直接修改 TextBox 的 Text 属性，进而使用依赖属性的一些方法来通知绑定的 ViewModel 属性发生了变化
在 Window 的 Drop 事件中直接修改 ViewModel 的属性（获取 Window.DataContext，并将其转为 MainViewModel 类型），然后在 ViewModel 中实现 INotifyPropertyChanged 接口，进而通知 TextBox 的 Text 属性发生了变化

这两种方式都很直接，而且其实都不违背 MVVM 模式。但是这两种方式并不优雅，所以这里我们借助行为（Behaviors）来实现一个更加优雅且通用的方式。

使用行为

首先，我们需要安装 Microsoft.Xaml.Behaviors.Wpf 包。然后我们可以创建一个 DropFileBehavior 类，形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


public class DropFileBehavior : Behavior<FrameworkElement>
{
 public string[]? Data
 {
 get => (string[]?)GetValue(FilesProperty);
 set => SetValue(FilesProperty, value);
 }

 public static readonly DependencyProperty FilesProperty = DependencyProperty.Register(
 nameof(Data),
 typeof(string[]),
 typeof(DropFileBehavior),
 new UIPropertyMetadata(null)
 );

 protected override void OnAttached()
 {
 AssociatedObject.AllowDrop = true;
 AssociatedObject.Drop += DropHandler;
 }

 protected override void OnDetaching()
 {
 AssociatedObject.Drop -= DropHandler;
 }

 private void DropHandler(object sender, DragEventArgs e)
 {
 if (e.Data.GetDataPresent(DataFormats.FileDrop))
 {
 Data = (string[])e.Data.GetData(DataFormats.FileDrop);
 }
 }
}

这个行为大致实现的功能是：

当附加到一个 FrameworkElement 上时，将其 AllowDrop 属性设置为 True，并注册 Drop 事件
当拖入文件时，将文件路径保存到 Data 依赖属性中

然后我们就可以在 XAML 中使用这个行为了（因为这里我们声明的 Data 属性是一个数组，所以我们稍微修改 MainViewModel 中相关属性的名称及类型，从而实现绑定功能）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<Window ...
 xmlns:i="http://schemas.microsoft.com/xaml/behaviors"
 xmlns:local="clr-namespace:YourNamespace">

 <i:Interaction.Behaviors>
 <local:DropFileBehavior Data="{Binding FileNames, Mode=OneWayToSource}" />
 </i:Interaction.Behaviors>

 <TextBox Text="{Binding FileNames[0]}" />
</Window>

注意这里，我们在书写行为的 Data 属性的绑定时，使用了 Mode=OneWayToSource，这是因为我们只需要将数据从视图传递到视图模型，而不需要反向传递。并且如果不写 Mode，它默认将会是 OneWay，导致可能无法正确通知到 ViewModel。

制作界面

最后，我们还可以搞一个“酷炫”的界面，形如：

首先，我们可以在窗口中添加这样一个置于上方的控件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Grid Name="dropFilePanel" Visibility="Hidden">
 <Border Background="White" Opacity="0.8" />
 <TextBlock HorizontalAlignment="Center"
 VerticalAlignment="Center"
 Text="将文件拖放到此处" />
 <Rectangle Width="200"
 Height="100"
 Stroke="Gray"
 RadiusX="10"
 RadiusY="10"
 StrokeDashArray="3,4"
 StrokeThickness="2" />
</Grid>

同时，因为我们现在有了这个专门的用于放置文件的面板，所以我们可以将之前添加给窗口的行为转移到它身上，形如：

1
2
3
4
5


<Grid Name="dropFilePanel" Visibility="Hidden">
 <i:Interaction.Behaviors>
 <local:DropFileBehavior Data="{Binding FileNames, Mode=OneWayToSource}" />
 </i:Interaction.Behaviors>
 ...

但是我们要控制它在合适的时机出现与消失。这里我们可以使用触发器与行为来快速地实现这一效果。具体来说，我们可以给窗口添加这样的触发器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<Window ...
 xmlns:b="http://schemas.microsoft.com/xaml/behaviors">
 <b:Interaction.Triggers>
 <b:EventTrigger EventName="DragEnter">
 <b:ChangePropertyAction TargetObject="{Binding ElementName=dropFilePanel}" PropertyName="Visibility" Value="Visible" />
 </b:EventTrigger>
 <b:EventTrigger EventName="DragLeave">
 <b:ChangePropertyAction TargetObject="{Binding ElementName=dropFilePanel}" PropertyName="Visibility" Value="Hidden" />
 </b:EventTrigger>
 </b:Interaction.Triggers>
 ...

这样，当鼠标拖入窗口时，dropFilePanel 就会显示出来；当鼠标拖出窗口时，dropFilePanel 就会被隐藏。

实际测试后会发现，当我们将文件拖到上方并松开左键后，虽然行为得到了正确的响应，但面板并没有消失。这是因为我们上面写的触发器只会在鼠标拖动状态离开窗口后才会隐藏面板。所以这里，我们可以再为面板添加一个触发器，并在它触发了 Drop 事件后将自身隐藏：

1
2
3
4
5
6


<Grid Name="dropFilePanel" Visibility="Hidden">
 <b:Interaction.Triggers>
 <b:EventTrigger EventName="Drop">
 <b:ChangePropertyAction PropertyName="Visibility" Value="Hidden" />
 </b:EventTrigger>
 </b:Interaction.Triggers>

这样，上面动图中的效果就实现了。

总结

WPF 开发必然会经常和控件的事件打交道。但很多时候，如果我们希望遵循 MVVM 模式，可能就会不知所措。相信大家通过这篇文章的代码，都能够充分领略到使用触发器与行为的强大之处。当然，这里只是一个简单的例子，实际开发中，我们还可以为上面的例子添加更多丰富的功能及特效。这些就有待大家的探索了。

大家如果有什么自己的好方法，也欢迎在文章评论区留言，分享给大家。

如何使用 appsettings.json 配置文件？

Mon, 22 Apr 2024 00:00:00 +0000

在 .NET Core 项目中，我们可以使用 appsettings.json 配置文件来存储应用程序的配置信息。在这篇文章中，我们将学习如何使用 appsettings.json 配置文件。

appsettings.json 是一个相较于 App.config 更加灵活的配置文件，是 .NET Core 以来新增的一种配置方式，提供了更多的灵活性。

快速入门

我们可以在项目中创建一个 appsettings.json 文件，然并将其生成操作设置为「较新时复制」或「总是复制」，这样在项目构建时，appsettings.json 文件会被复制到输出目录中。

然后我们可以在其中添加如下内容：

1
2
3
4
5
6
7
8


{
 "AppSettings": {		
 "LogLevel":"Warning",
 "ConnectionStrings": {
 "Default": "this is the connection string"
 }	
 }
}

这样我们就可以尝试读取了。我们使用 NuGet 包管理器安装 Microsoft.Extensions.Configuration.Json 包。它会隐式安装 Microsoft.Extensions.Configuration 等依赖项，这些我们不需要显式安装。

然后我们可以在代码中读取配置文件：

1
2
3
4
5


using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
 .Build();

这样我们就可以获取上面的配置信息了：

1
2


var logLevel = configuration["AppSettings:LogLevel"];
var connectionString = configuration["AppSettings:ConnectionStrings:Default"];

这里的形如 AppSettings.LogLevel 是一种特殊的写法，简单来说就是借助 : 来表示 JSON 中的层级关系。

如果要获取的配置项是一个数字，我们除了可以先通过上述方式获取到字符串，进而使用 int.Parse 或 Convert.ToInt32 等方法进行转换，还可以使用 GetValue 方法：

1
2
3
4


// 传统方法
var logLevel = int.Parse(configuration["AppSettings:LogLevel"]);
// 使用 GetValue 方法
var logLevel = configuration.GetValue<int>("AppSettings:LogLevel");

对于连接字符串，我们还可以使用 GetConnectionString 方法：

1

var connectionString = configuration.GetConnectionString("Default");

可选与自动重载

在上面的代码中，我们可以看到 AddJsonFile 方法有两个参数，optional 和 reloadOnChange：

optional 参数表示是否允许配置文件不存在，如果设置为 false，则会抛出异常，否则会忽略。
reloadOnChange 参数表示是否在配置文件发生变化时重新加载配置文件。如果设置为 true，则会在配置文件发生变化时重新加载配置文件。

比如我们可以用下面的例子测试自动重载的效果：

1
2
3
4
5
6
7
8
9


var configuration = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
 .Build();

while (true)
{
 Console.WriteLine(configuration["AppSettings:LogLevel"]);
 Thread.Sleep(1000);
}

在运行程序后，我们可以修改 appsettings.json 文件中的 LogLevel 配置，然后我们会发现程序会自动重新加载配置文件。注意这里我们修改的是输出目录（也就是 .exe 文件所在位置）下的 appsettings.json 文件，而不是项目中的 appsettings.json 文件。

添加多个 JSON 文件

如果只能添加一个 JSON 文件，那么配置文件的灵活性就大大降低了。事实上，我们可以通过多次调用 AddJsonFile 方法来添加多个 JSON 文件。一个典型的情形是添加一个 appsettings.Development.json 文件，用于存储开发环境的配置信息。

1
2
3
4


var configuration = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
 .AddJsonFile("appsettings.Development.json", optional: true, reloadOnChange: true)
 .Build();

这样我们就可以在 appsettings.Development.json 文件中存储开发环境的配置信息，而在 appsettings.json 文件中存储通用的配置信息。

不仅如此，这二者之间存在优先级，或者说覆盖关系。具体来说：

如果 appsettings.json 和 appsettings.Development.json 中都有相同的配置项，那么 appsettings.Development.json 中的配置项会覆盖 appsettings.json 中的配置项
如果 appsettings.Development.json 中没有某个配置项，而 appsettings.json 中有，那么会使用 appsettings.json 中的配置项
如果 appsettings.Development.json 中有某个配置项，而 appsettings.json 中没有，那么会使用 appsettings.Development.json 中的配置项

使用强类型配置

在上面的例子中，我们使用 configuration["AppSettings:LogLevel"] 来获取配置信息，这种方式是一种弱类型的方式。我们也可以使用强类型的方式来获取配置信息。

我们修改一下 appsettings.json 文件中的配置项：

1
2
3
4
5
6
7


{
 "UserSettings": {
 "Name": "Alice",
 "Age": 18,
 "IsActive": true
 }
}

然后我们定义一个强类型的配置类：

1
2
3
4
5
6


public class UserSettings
{
 public string Name { get; set; }
 public int Age { get; set; }
 public bool IsActive { get; set; }
}

在获取配置前，我们还需要安装一个 NuGet 包：Microsoft.Extensions.Options.ConfigurationExtensions。然后我们就可以这样获取配置信息：

1

var userSettings = configuration.GetSection("UserSettings").Get<UserSettings>();

这样我们就可以获取到 UserSettings 对象了，然后就可以使用 userSettings.Name、userSettings.Age、userSettings.IsActive 来获取配置信息了。

但是需要注意，因为这里的 userSettings 实例已经初始化，所以前面提到的自动重载功能不再生效。如果需要自动重载，我们需要重新获取 userSettings 对象。

添加环境变量和命令行参数

在 .NET Core 中，我们还可以通过环境变量和命令行参数来覆盖配置文件中的配置信息。我们需要再安装两个 NuGet 包：

Microsoft.Extensions.Configuration.EnvironmentVariables
Microsoft.Extensions.Configuration.CommandLine

然后我们可以这样添加环境变量和命令行参数：

1
2
3
4
5


var configuration = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
 .AddEnvironmentVariables()
 .AddCommandLine(args)
 .Build();

这样我们就可以通过环境变量和命令行参数来覆盖配置文件中的配置信息了。

比如我们可以创建一个 .bat 批处理文件：

1
2
3
4
5


@echo off
set UserSettings__Name=Bob
set UserSettings__Age=20

.\Demo.exe

或者还可以使用 PowerShell：

1
2
3
4


$env:UserSettings__Name = "Bob"
$env:UserSettings__Age = 20

.\Demo.exe

总结

相信通过这篇文章，大家已经认识到了 appsettings.json 配置文件的强大之处。它不仅提供了一种灵活的配置方式，还提供了多种配置方式的组合，使得我们可以更加灵活地配置应用程序。

但是它也有一些局限性。最重要的一条就是它的配置项是“只读”的，也就是不能像 App.config 那样在运行时方便地修改配置项。毕竟，一个项目中可能存在多个配置项，而不是只有一个 appsettings.json 文件。此时如果修改了，该保存到哪个文件呢？

当然，如果只有一个配置文件，那么 appsettings.json 是一个不错的选择。比如我们可以使用 Newtonsoft.Json 来轻松地写入 JSON 文件，这样就可以实现配置项的修改了。

最后，其实通常情况下，我们并不会使用上面的方式读取配置项，而是会更进一步，使用 Host 作为整个程序的入口，并读取配置、注入服务等。在之后的文章中，我们会学习如何使用 Host 来构建一个 .NET 应用程序。

如何用 Rx.NET 来模拟情景短剧《恐惧症研讨会》

Sat, 20 Apr 2024 00:00:00 +0000

不知道大家有没有看过这样一个视频：

（或者也可以看油管上的原版视频）

我们这次就来玩一玩，如何使用 Rx.NET 来模拟这个情景短剧。

简单分析每个人的特点

通过观看视频，我们发现一共有五个人，且这五个人各有特点，或者说各自会在特定情况下触发自己的恐惧症，进而发出尖叫。具体来说：

Lee：对于“AAGH!”（也就是“啊！”）这个词很恐惧
- 且这个词必须是别人发出的
Jim：对于道歉（或者说“Sorry”这个词）很恐惧
- 自己说的这个词也是可以触发自己的恐惧的
Karen：对于重复的话很恐惧
- 两句重复的话必须都是别人说的
- （从视频中来看，两句重复的话甚至可以间隔很久，但这种情况难以概括，且视频中其他时候也有重复的话，但并未触发，所以存在 BUG，暂不考虑）
Ronnie：对于“尴尬的沉默”很恐惧
- 也就是说，如果有人说了一句话，然后没有人回应，那么就会触发
- 前提是必须有人先说了什么，而不是打一开始就没有任何人说话
Tim：对于别人因恐惧而发出尖叫这件事情感到恐惧，并且会吓出狗叫
- 当其他有人发出了恐惧的尖叫，且之后不再会有人尖叫时，他会发出狗叫

大家可以多看几遍视频，尤其是靠近后面的地方，他们连续相继发出尖叫声的片段，看看我上面总结的是否正确。

那么现在，我们就来模拟这个情景短剧吧。

实现消息总线

在模拟每个人之前，我们首先需要有一个消息总线（Message Bus）。有了这个总线，我们才可以既让所有人都能够收听（或者说订阅）这个总线，又可以向总线中发送消息。

在 Rx.NET 中，Subject 这个类型就是典型的能够实现这一效果的类。我们可以使用它来实现一个消息总线。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class MessageBus : IDisposable
{
 // 内部使用一个 Subject 对象
 private readonly Subject<Message> _subject = new();

 // 当用于订阅时，返回一个 IObservable<Message> 对象，从而封装类中其他功能
 public IObservable<Message> Messages => _subject.AsObservable();

 // 当向总线中发送消息时，底层会调用 Subject 的 OnNext 方法
 public void SendMessage(Message message)
 {
 if (message.Content == "exit")
 _subject.OnCompleted();
 else
 _subject.OnNext(message);
 }

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

同时，我们也需要一个 Message 类型，从而更好地让接下来的每一个人都能够判断自己是否应该发出尖叫。

1

record Message(string Sender, string Content);

是的，一个简单的记录类就可以满足我们的需求了。上面的每一个人，它们都只需要知道是谁说的，以及说了什么，就足够处理各自的逻辑了。

Info

在 ReactiveUI 中也有一个消息总线类型，名叫 MessageBus。它底层其实就是借助了一个 Subject 来实现的。当然实际上更复杂一些，因为还有与 Scheduler 相关的一些额外的功能，所以它额外实现了一个名为 ScheduledSubject 的类。

模拟每一个人的行为

下面我们就根据出场顺序，来逐个模拟每个人的逻辑吧。这里为了简单起见，我们统一使用小写，并且为所有人设定了一个固定的延迟。此外，还需要给两个人额外的时间：

给 Ronnie 一个时间阈值，表示多久之后才会被她判定为长时间的“尴尬的沉默”
给 Tim 一个相对更长一点的延迟，从而让他能够在确保其他人都不再尖叫之后，才发出自己的狗叫

1
2
3


var reactionDelay = TimeSpan.FromSeconds(0.25);
var ronnieSilenceThreshold = TimeSpan.FromSeconds(3);
var timReactionDelay = TimeSpan.FromSeconds(0.3);

同时，我们还要声明前面定义好的消息总线：

1

var bus = new MessageBus();

这样，每个人都能够收听这个总线，并且自己发出的尖叫也要传递给这个总线。

Lee

Lee 的逻辑很简单，只要听到了别人说的 “AAGH!”这个词，就会发出尖叫。

1
2
3
4


using var agent1 = bus.Messages
 .Where(m => m.Content == "aagh" && m.Sender != "agent1") // 别人说的 aagh
 .Delay(reactionDelay)
 .Subscribe(_ => bus.SendMessage(new("agent1", "aagh")));

Jim

Jim 的逻辑也很简单，只要听到了 “Sorry” 这个词（不用管是谁发出的），就会发出尖叫。

1
2
3
4


using var agent2 = bus.Messages
 .Where(m => m.Content == "sorry") // 无论是谁说的 sorry
 .Delay(reactionDelay)
 .Subscribe(_ => bus.SendMessage(new("agent2", "aagh")));

Karen

Karen 的逻辑稍微复杂一点，因为她需要判断两句话是否重复，且都是别人说的。

1
2
3
4
5
6
7
8


using var agent3 = bus.Messages
 .Buffer(2, 1)
 .Where(ms => ms.Count == 2
 && ms[0].Content == ms[1].Content
 && ms[0].Sender != "agent3"
 && ms[1].Sender != "agent3")
 .Delay(reactionDelay)
 .Subscribe(_ => bus.SendMessage(new("agent3", "aagh")));

Ronnie

Ronnie 的逻辑也比较简单，只要有人说了话，然后没有人回应，就会发出尖叫。那么 Rx 中的 Throttle 方法简直就是为她量身打造的。

1
2
3
4


var agent4 = bus.Messages
 .Throttle(ronnieSilenceThreshold)
 // .Delay(reactionDelay) // 这句也可以不写
 .Subscribe(_ => bus.SendMessage(new("agent4", "aagh")));

Tim

Tim 其实与 Ronnie 类似，只要有人发出了尖叫，然后之后没有人再发出尖叫，他就会发出狗叫。所以我们同样可以使用 Throttle 方法来实现。

1
2
3
4


var agent5 = bus.Messages
 .Where(m => m.Content == "aagh")
 .Throttle(timReactionDelay)
 .Subscribe(_ => bus.SendMessage(new("agent5", "woof")));

放在一起

最后，我们将上面的代码放在一起。为了能够便于观察效果，我们使用 LINQPad 来简单地搭建这段代码，并且额外添加一个 agent，代表用户的输入。这样，我们就可以通过输入来模拟每个人的发言了。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


bool isCompleted = false;

bus.Messages
 .Subscribe(
 m => Console.WriteLine($"[{DateTime.Now: mm:ss.fff}] {m.Sender}: {m.Content}"),
 () => isCompleted = true
 );

while (!isCompleted)
{
 var input = Util.ReadLine();
 bus.SendMessage(new("user", input));
}

完整版代码可以查看这个 Gist。

运行看一下效果。输入“aagh”会看到：

1
2
3
4
5


[55:26.812] user: aagh
[55:27.112] agent1: aagh
[55:27.362] agent3: aagh
[55:27.625] agent1: aagh
[55:27.941] agent5: woof

输入“sorry”会看到：

1
2
3
4
5
6


[55:34.985] user: sorry
[55:35.236] agent2: aagh
[55:35.499] agent1: aagh
[55:35.763] agent3: aagh
[55:36.027] agent1: aagh
[55:36.339] agent5: woof

总结

通过这个简单的例子，我们可以看到，Rx.NET 的强大之处。我们可以通过简单的类似 LINQ 一样的查询，就能够实现复杂的逻辑。这种方式不仅简洁，而且易于理解，同时也能够很好地处理异步的情况。试想一下，如果我们使用传统的多线程或异步编程来实现相同的效果，那么代码会变得多么复杂。

之后我们还会继续探讨 Rx.NET 的更多用法，用更多实际且生动的例子，来帮助大家更好地理解这个库。

为什么 IEnumerable 对象没有 ForEach 方法？

Wed, 17 Apr 2024 00:00:00 +0000

便捷的 ForEach 方法

C# 中，List 类型（其他还包括 ImmutableList 等）拥有一个名为 ForEach 的方法。它的作用可以理解为传统 foreach 语句的另一种函数式的写法。比如：

1
2
3
4
5
6
7
8


var list = new List<int> { 1, 2, 3, 4, 5 };
// 传统的 foreach 语句
foreach (var n in list)
{
 Console.WriteLine(n);
}
// 便捷的 ForEach 方法可以实现相同的效果
list.ForEach(n => Console.WriteLine(n));

（One-liner 狂喜）

此外，Array 类还拥有一个 ForEach 静态方法，同样可以实现类似的功能。但很快我们就会发现，为什么这么好用的方法，我们却不能用在一个 IEnumerable （这里指的是泛型接口 IEnumerable<T>，下面不再赘述）接口类型上呢？

Note

在某些读者可能会发问之前，我把“丑话说在前面”：将一个 IEnumerable 类型使用 ToList() 方法转为 List，只为使用 ForEach() 绝对不是一个好主意，因为这很可能会涉及到消耗 LINQ 语句，创建新对象，以及逐个填充元素等。

其实这样设计是有原因的。我大概总结了这么几条，大家听一听是不是这么个道理。

添加 ForEach 方法的后果

破坏接口的纯粹性

这句话如果说得再“专业”一点，就是违背了 SOLID 原则中的“单一职责原则”（Single responsibility principle）以及“接口隔离原则”（Interface segregation principle）。

怎么讲？我们可以看一下 IEnumerable 接口的定义：

1
2
3
4
5
6
7


namespace System.Collections.Generic
{
 public interface IEnumerable<out T> : IEnumerable
 {
 new IEnumerator<T> GetEnumerator();
 }
}

非常地干净。就连它的名字也表明了，它只是表明一个对象拥有“被枚举”的能力。但是 ForEach 方法通常会伴随着一些执行逻辑，这可能就与接口的初衷不符了。

不同于 LINQ 中的 Select、Where、OrderBy 等，它们都是对于数据的映射、筛选、排序等，通常不会包含什么逻辑操作。试想，如果 LINQ 中包含了逻辑操作，尤其还是耗时的操作（比如占用 CPU 的复杂计算、IO 操作等）时，LINQ 的使用将会变得不那么可靠。

所以，假如 ForEach 方法中也存在这样的耗时操作，我们更应该考虑的做法是使用异步编程（比如创建多个异步任务，然后使用 Task.WhenAll 方法进行等待），使用 Parallel 类或者 PLINQ 等，从而使得我们的 IEnumerable 对象只包含数据序列，不包含不可控的操作逻辑。

这里给出一个简单的使用异步的例子：

1
2
3
4


IEnumerable<int> items = ...;
var tasks = items.Select(x => CalculateValueAsync(x));
await Task.WhenAll(tasks);
var results = tasks.Select(t => t.Result).ToList();

方法带来的副作用

诚然，我们可以自己写一个扩展方法，从而让 IEnumerable 对象能够像 List 那样使用 ForEach 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


static class EnumerableExtensions
{
 public static void ForEach<T>(this IEnumerable<T> items, Action<T> action)
 {
 foreach (var item in items)
 {
 action.Invoke(item);
 }
 }
}

但这可能会造成对 LINQ 现有功能的污染。为什么这么说呢？

我们来想一想，LINQ 提供的功能主要是做什么的？其实主要是对于数据的映射、筛选、排序等。这些方法通常都被认为不会对原始数据造成影响，或者修改。虽然这些方法也会接收一个回调，但是这个回调一定是个 Func，从而返回映射后的对象、筛选及排序的依据等。

但是 ForEach 方法则不同，它接收的是一个 Action，那就是说这个回调并不需要返回什么。此时我们的操作通常就有可能会对原始数据产生影响了。比如：

1
2
3
4
5
6


List<Employee> employees = ...;

employees.ForEach(e => {
 if (e.IsPromoted) // 如果员工晋升，则涨薪
 e.Salary += 1000;
})

所以，使用 ForEach 时我们是倾向于对于原本的数据进行一定的操作的。

当然这里仅仅表示一种推测，实际的用法并不绝对。即便我们使用 LINQ 中的 Select 等方法，也同样是可以做到对于数据的修改的，这一点 LINQ 并没有办法阻止我们。所以这里主要还是一个“轻重”关系。相较于 LINQ 的方法，ForEach 是更倾向于会对数据进行操作的。

性能和资源等方面的考虑

还有一个点，就是拥有 ForEach 方法的 List（类似的还有 Array.ForEach 静态方法），它们被操作的对象都有一个显著特点：元素数量是已知（或者说有限）的。这一点非常重要，因为一个 IEnumerable 对象完全有可能是无限的！

1
2
3
4
5
6
7


IEnumerable<int> GenerateNumbers()
{
 while (true)
 {
 yield return 0;
 }
}

从这个角度考虑，对一个容量未知的集合轻易开展 ForEach 这样的操作，其实是充满风险的。不仅如此，ForEach 方法不像是 foreach 语句那样，可以在其中书写 continue、break 或 return 等语句，这就意味着它一旦开始，就只能将整个集合中的全部元素逐个来一遍才行了。

所以从这个角度考虑，不给 IEnumerable 对象提供这样的扩展方法，似乎是非常有道理的。当然，你依旧可以说，LINQ 的方法遇到这样的极端情况，同样束手无策呀？的确，但 LINQ 针对的就是 IEnumerable 类型，这是无法避免的，只能希望开发者清楚自己面对的集合是有限的还是无限的。

＜2024 年 5 月 7 日更新＞

最近 Nick Chapsas 在他的一期视频中讨论了 ForEach 方法的性能。通过 Benchmark（在视频的约 5:45 处）可以看出，它的性能是显著低于传统的 for 以及 foreach 的：

1
2
3
4
5


| Method | Mean | Allocation |
| ------- | ---------- | ---------- |
| for | 424.9 us | - |
| foreach | 426.4 us | - |
| ForEach | 1,785.0 us | 88 B |

Info

关于上面的表格，有一些需要额外补充的内容：

上面的表格省去了一些列，只保留了主要部分
测试环境是最新的 .NET 9（预览版），所以 foreach 与 for 拥有近乎一样的性能，且没有内存开销
ForEach 速度慢了约 4 倍，且拥有内存开销（因为存在委托和相应的闭包）

所以这更加证明了，ForEach 方法并不是一个高性能的方法，如果我们需要对一个集合进行遍历，还是应该使用传统的 for 或 foreach。

总结

总的来说，虽然为 IEnumerable<T> 添加一个 ForEach 方法在技术上是可行的，但由于设计哲学、清晰的代码维护、性能考虑和潜在的副作用，.NET 框架设计者选择不在 IEnumerable<T> 中直接提供这样的方法。不过，大家如果需要，可以自定义扩展方法来实现这一功能。但前提是要清楚这样做可能会带来的后果。

为什么我们需要 ValueTask？

Fri, 12 Apr 2024 00:00:00 +0000

自从 C# 5.0 引入了 async 和 await 语法以后，异步编程变得非常简单，而 Task 类型也在开发中扮演着相当重要的角色，存在感极高。但是在 .NET Core 2.0 这个版本，微软引入了一个新的类型 ValueTask，那么这个类型是什么？为什么我们需要它？什么情况下应该使用它？我们今天就来探讨一下。

简单回顾 `Task` 类型

在异步编程中，我们经常会使用 Task 类型来表示一个异步操作或者说异步任务。相较于其他一些主流编程语言，C# 中的异步任务其实开销很小。比如知乎上的大佬 hez2010 在他的这个回答中提到，C# 的 Task 类型通常只占用 64~136 B 的内存，而 Go 语言的一个 goroutine 至少占用 2 KB 的内存。

不仅如此，Task 还有许多优化技巧，比如：

如果想直接返回一个结果，可以使用 Task.FromResult 方法
如果想直接返回一个已经完成的任务，可以使用 Task.CompletedTask
如果想直接返回一个已经取消的任务，可以使用 Task.FromCanceled
如果想直接返回一个已经失败的任务，可以使用 Task.FromException

等等。所以从 C# 5.0（大概是 .NET Framework 4 时代）开始，直到 .NET Core 2.0 之前，一直相安无事。

传统 `Task` 类型的问题

但是，随着 .NET 开始跨平台，能使用 C# 的场景越来越多，微软的“野心”也越来越大，开始从各种角度优化 C# 的性能，从而使 .NET 能够胜任各种任务场景。除了引入 Span、Memory、ref struct 等新特性外，还引入了 ValueTask。那么，传统的 Task 类型有什么问题呢？

首先我们要知道，Task 包含泛型版本和非泛型版本，分别对应有无返回值的异步任务。而 ValueTask 在诞生之初，只有一个泛型版本。换句话说，设计者认为，ValueTask 应当只适用于有返回值的异步任务。所以这里我们来看一个典型的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


private readonly ConcurrentDictionary<int, string> _cache = new ();

public async Task<string> GetMessageAsync(int id)
{
 if (_cache.TryGetValue(id, out var message))
 {
 return message;
 }

 message = await GetMessageFromDatabaseAsync(id);
 _cache.TryAdd(id, message);

 return message;
}

在上面的 GetMessageAsync 方法中，我们首先尝试从缓存中获取消息，如果没有找到，就再尝试从数据库中获取。但这里有一个问题，如果缓存中有数据，那么虽然我们好像会直接返回一个值。但是，由于 GetMessageAsync 方法是一个异步方法，所以实际上会返回一个 Task<string> 类型的对象。这就意味着，即便我们本可以只返回一个值，我们依旧会多创建一个 Task 对象，这就导致了无端的内存开销。

Info

这种在异步任务中直接返回一个值的情况，我们称之为“同步完成”，或者“返回同步结果”。线程进入这个异步任务后，并没有碰到 await 关键字，而是直接返回。也就是说，这个异步任务自始至终都是在同一个线程上执行的。

`ValueTask` 简介

所以，ValueTask 的主要作用就是解决这个问题。它在 .NET Core 2.0 被正式引入，并在 .NET Core 2.1 得到了增强（新增了 IValueTaskSource<T> 接口，从而使它可以拥有诸如 IsCompleted 等属性），并且还添加了非泛型的 ValueTask 类型（这个我们稍后再说）。

ValueTask 我们先不要去思考它是否为值类型，而是可以这么理解：它适用于可能返回一个 Value，也可能返回一个 Task 的情形。也就是说，它非常适合上面的“缓存命中”的典型场景。我们可以把上面的代码修改为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public async ValueTask<string> GetMessageAsync(int id)
{
 if (_cache.TryGetValue(id, out var message))
 {
 return message;
 }

 message = await GetMessageFromDatabaseAsync(id);
 _cache.TryAdd(id, message);

 return message;
}

此时，如果缓存中有数据，那么我们可以直接返回一个 ValueTask<T> 对象，而不需要再创建一个 Task<T> 对象。这样就避免了无端的堆内存开销；否则，我们才会创建 Task<T> 对象。或者说，在这种情况下，ValueTask 的性能会退化为 Task（甚至可能还稍微低一丁点，因为涉及到更多的字段，以及值拷贝等）。

Info

至于非泛型版本的 ValueTask，它的使用情形就更少了。它只有在即使异步完成也可以无需分配内存的情况下才会派上用场。ValueTask 的“发明者”Stephen Toub 在他的文章中提到，除非你借助 profiling 工具确认 Task 的这一丁点开销会成为瓶颈，否则不需要考虑使用 ValueTask。

这时候我们再来思考它的性能究竟如何：

顾名思义，ValueTask 是一个值类型，可以在栈上分配，而不需要在堆上分配。不仅如此，它因为实现了一些接口，从而使它可以像 Task 一样被用于异步编程。所以，照理说，ValueTask 的性能要比 Task 更好很多（就如同 ValueTuple 之于 Tuple、Span 之于 Array 一样）。

但是，ValueTask 真的这么美好吗？它是不是可以完全替代 Task 呢？事情恐怕并没有这么简单。

`ValueTask` 的注意事项

现在，我们该谈一谈 ValueTask 在使用时需要注意的地方了。

`ValueTask` 不能被多次等待（`await`）

ValueTask 底层会使用一个对象存储异步操作的状态，而它在被 await 后（可以认为此时异步操作已经结束），这个对象可能已经被回收，甚至有可能已经被用在别处（或者说，ValueTask 可能会从已完成状态变成未完成状态）。而 Task 是绝对不可能发生这种情况的，所以可以被多次等待。

不要阻塞 `ValueTask`

ValueTask 所对应的 IValueTaskSource 并不需要支持在任务未完成时阻塞的功能，并且通常也不会这样做。这意味着，你无法像使用 Task 那样在 ValueTask 上调用 Wait、Result、GetAwaiter().GetResult() 等方法。

但换句话说，如果你可以确定一个 ValueTask 已经完成（通过判断 IsCompleted 等属性的值），那么你可以通过 Result 属性来安全地获取 ValueTask 的结果。

Info

微软专门添加了一个与这个有关的警告：CA2012

不要在多个线程上同时等待一个 `ValueTask`

ValueTask 在设计之初就只是用来解决 Task 在个别情况下的开销问题，而不是打算全面取代 Task。因此，Task 的很多优秀且便捷的特性它都不用有。其中一个就是线程安全的等待。

也就是说，ValueTask 底层的对象被设计为只希望被一个消费者（或线程）等待，因此并没有引入线程安全等机制。尝试同时等待它可能很容易引入竞态条件和微妙的程序错误。而 Task 支持任意数量的并发等待。

如何克服 `ValueTask` 的局限性

在实际使用过程中，难免遇到需要突破它的上述限制的情况。那么我们该怎么办呢？这里给出几种常见情况的对应方式：

如果希望用阻塞的方式（Result 与 .GetAwaiter().GetResult()）获取 ValueTask<T> 的结果，可以先判断 IsCompleted 或 IsCompletedSuccessfully 等属性的值，确认它已经完成，然后再获取结果
如果希望等待多次，或在多个线程中等待等，那么可以使用 AsTask() 方法将其转为一个普通的 Task，进而再进行各种 Task 的常用操作

基于 ValueTask 的原理及限制，一个普遍认同的推荐用法是：

Tip

绝大多数情况下，都推荐直接使用 await 关键字来等待一个返回值为 ValueTask<T> 的异步任务并获取结果，而不是试图将其返回值赋值给一个变量（最多是搭配 ConfigureAwait() 进行使用）；否则，建议使用 AsTask() 方法将其转为传统的 Task，再进行常规操作。

总结

总的来说，ValueTask 确实有很多闪光点，比如在栈上分配来避免堆分配的性能开销，但它也有一些让人头疼的限制，比如不能被多次等待。使用它就像是在走钢丝，一不小心就可能掉进性能优化的陷阱里。但别担心，大多数情况下，我们还是可以安全地使用 await 来等待 ValueTask<T> 的，只要我们不试图把它当作 Task 的替代品来用就好。

希望看了这篇文章之后，大家能够正确使用 ValueTask。

参考链接

Using 语句的陷阱

Thu, 11 Apr 2024 00:00:00 +0000

using 语句在 C# 中有很多种用法，比如引入命名空间，为类型起别名，或者释放资源等。这篇文章我们主要讨论 using 语句在释放资源时的陷阱。

using 以前的使用方式

在很久很久以前，我们如果想要读取一个外部文本文件的内容，可能会这样写（不考虑更简洁易用的 File.ReadAllText() 等方法）：

1
2
3
4
5
6
7
8


using (var stream = new FileStream(filename, FileMode.Open))
{
 using (var reader = new StreamReader(stream))
 {
 var content = reader.ReadToEnd();
 Console.WriteLine(content);
 }
}

其实上面的代码，是可以减少一层缩进的，并且这也是各种 IDE 推荐的写法，形如：

1
2
3
4
5
6


using var stream = new FileStream(filename, FileMode.Open)
using var reader = new StreamReader(stream)
{
 var content = reader.ReadToEnd();
 Console.WriteLine(content);
}

这个其实很有意思，因为一般我们都认为，即便外层的语句省略了花括号，内层的语句依旧会保持缩进，就比如多层 if 语句：

1
2
3
4
5


if (condition1)
 if (condition2)
 {
 // do something
 }

但是上面展示的 using 的省略外层花括号的新语法，内层的语句并不会额外添加缩进，而是会与外层保持同一层级。不信的话，可以使用任意一个格式化工具，比如 Visual Studio 的 Ctrl+K, Ctrl+D，格式化一下上面的代码，看看会是什么样子。

using 的新语法

C# 8.0 为我们带来了一个新的 using 语句的用法，可以减少一层缩进，让代码看起来更简洁。同样是上面的代码，现在可以写成：

1
2
3
4
5
6


string filename = "test.txt";
using var stream = new FileStream(filename, FileMode.Open);
using var reader = new StreamReader(stream);

var content = reader.ReadToEnd();
Console.WriteLine(content);

上面的代码实际上会被编译为这样的 low-level C# 代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


string path = "test.txt";
FileStream fileStream = new FileStream(path, FileMode.Open);
try
{
 StreamReader streamReader = new StreamReader(fileStream);
 try
 {
 string value = streamReader.ReadToEnd();
 Console.WriteLine(value);
 }
 finally
 {
 if (streamReader != null)
 {
 ((IDisposable)streamReader).Dispose();
 }
 }
}
finally
{
 if (fileStream != null)
 {
 ((IDisposable)fileStream).Dispose();
 }
}

不难看出，using 语句用于资源释放时，其实是通过 try-finally 语句来实现的。当存在多层的 using 语句时，每一层都会对应一个 try-finally 语句，也就变成了上面的样子。

新的语法会将 using 语句下面的内容（准确地说，是当前作用域中剩下的代码）包装在 try-finally 语句中，从而保证代码在离开作用域前，会释放资源。

Info

仔细观察还可以发现，Dispose 的顺序是从内到外的，或者说先被 using 的对象会后被释放。

新语法的陷阱

学了这个新语法之后，相信很多人都打算全面替代掉旧方法，毕竟少写了花括号，而且减少了缩进，效果还一模一样。但实际上，这种新语法并不是适用于所有情况的。也就是说，效果未必一模一样。比如之前我就踩了一个坑。

当时的情况是，我在使用 System.IO.Compression 命名空间下的 GZipStream 来压缩一个文本，并输出压缩后的内容。我使用的代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


using System.IO.Compression;
using System.Text;

string input = "text to be compressed.";

using var outputStream = new MemoryStream();
using var inputStream = new MemoryStream(Encoding.UTF8.GetBytes(input));
using var compressor = new GZipStream(outputStream, CompressionLevel.Optimal);

inputStream.CopyTo(compressor);
var compressed = outputStream.ToArray();
Console.WriteLine(compressed.Length);

运行后，输出了压缩后的内容长度为 10。

但是当我修改了 input 的字符串内容后，发现输出的长度依旧是 10，这显然是不可能的。我检查了一下代码，发现问题出在了 using 语句上。只要把上面的代码修改成这样，就能得到正确的结果：

1
2
3
4
5
6
7
8


using var outputStream = new MemoryStream();
using (var inputStream = new MemoryStream(Encoding.UTF8.GetBytes(input)))
using (var compressor = new GZipStream(outputStream, CompressionLevel.Optimal))
{
 inputStream.CopyTo(compressor);
}
var compressed = outputStream.ToArray();
Console.WriteLine(compressed.Length);

造成这一现象的原因是，如果想要得到正确的压缩后的内容，需要保证 GZipStream 已经被释放。但是如果我们不加声明 GZipStream 这一行的花括号，会导致它直到离开作用域时才被释放，而不是在 inputStream.CopyTo(compressor) 之后立即释放。

所以，大家在使用新的 using 语句时，一定要根据实际情况来判断是否适用，不要无脑替换掉以前的旧写法。

C# 鸭子类型汇总

Thu, 04 Apr 2024 00:00:00 +0000

什么是“鸭子类型”？

鸭子类型的名字来源于一句俚语：

这句话的意思是，如果一个对象具有某个方法或属性，那么它就可以被当作拥有这个方法或属性的类型来使用，而不需要严格地遵循一些规定与要求。

在 C# 中，通常我们会认为，如果想要使用一些语法，需要实现一些接口。比如你很可能会觉得：

如果想要使用 foreach 语句，需要实现 IEnumerable 接口
如果想要使用 await 语句，需要与 Task 类或一些底层接口扯上关系
如果想要使用 using 语句释放资源，需要实现 IDisposable 接口

实际上真的如此吗？这篇文章我们就来总结一下 C# 中的那些不为人知的鸭子类型。

C# 中的鸭子类型

`foreach` 语句

C# 标准库为我们提供了大量的集合类型，比如 List、Stack、Queue、ObservableCollection 等等。这些集合类型都实现了 IEnumerable 接口，所以我们可以使用 foreach 语法来遍历它们。

但实际上，foreach 语法并不要求类必须实现 IEnumerable 接口。只要类中有一个名为 GetEnumerator 的方法，返回一个 IEnumerator 类型的对象，就可以使用 foreach 语法。比如下面这个例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


var c = new MyEnumerableClass();
foreach (var item in c)
{
 Console.WriteLine(item);
}

class MyEnumerableClass
{
 private int[] items = new[] { 1, 2, 3 };

 public IEnumerator GetEnumerator()
 {
 return items.GetEnumerator();
 }
}

我们还可以玩一些“花活”。事实上，这个 GetEnumerator 方法其实都不需要直接出自这个类型，甚至可以是一个扩展方法。所以，我们可以对一些我们无法修改的类添加扩展方法，从而使它们变得可以被 foreach 语法遍历。比如 C# 8.0 引入了 Range 与 Index 两个类型，表示数组的范围与索引。

Info

通常我们不会直接声明一个 Range 对象，而是会使用形如 array[1..5] 这样的语法来表示一个范围。在底层，这个 1..5 会被转换为一个 Range 对象。

你甚至可以不在数组的索引器中使用这个语法，而是直接声明一个变量并这样进行赋值：

1
2


var range = 1..5;
Console.WriteLine(range.GetType().Name); // Range

我们可以为 Range 类型添加一个扩展方法，使得它们可以被 foreach 语法遍历：

1
2
3
4
5
6
7
8


static class MyExtensions
{
 public static IEnumerator<int> GetEnumerator(this Range range)
 {
 for (int i = range.Start.Value; i <= range.End.Value; i++)
 yield return i;
 }
}

然后就可以这样玩了：

1
2
3
4
5
6
7
8
9


foreach (var i in 1..3) // 1..3 是一个 Range 类型
{
 Console.WriteLine(i);
}

// 输出：
// 1
// 2
// 3

`await` 语句

类似地，await 语法也不要求类必须继承 Task 类或实现一些底层接口。只要类中有一个名为 GetAwaiter 的方法，返回一个 IAwaiter 类型的对象，就可以使用 await 语法。并且与上面 foreach 的例子相同，我们也可以把 GetAwaiter 方法定义为一个扩展方法，从而“扩展”一些我们无法修改的类。

1
2
3
4
5


static class Extensions
{
 public static TaskAwaiter GetAwaiter(this TimeSpan ts) => Task.Delay(ts).GetAwaiter();
 public static TaskAwaiter GetAwaiter(this double sec) => Task.Delay(TimeSpan.FromSeconds(sec)).GetAwaiter();
}

上面的静态类中声明了两个扩展方法，分别为 TimeSpan 与 double 类型添加了 GetAwaiter 方法。然后我们就可以这样使用 await 语法了：

1
2


await TimeSpan.FromSeconds(1);
await 1.0;

是不是感觉越来越离谱了？不过实际开发中，轻易还是不要使用这样的技巧，因为这会严重污染常用的类型，可以说是有百害而无一利。

`using` 语句

如果你认为 using 语句只能用于实现了 IDisposable 接口的类，那你终于基本上对了一次😂。的确，对于一个 class 类型的对象，如果它没有实现 IDisposable 接口，那么即便它拥有 public void Dispose() 方法，它仍然是无法使用 using 语句的（编译器会提示，这个对象必须可以隐式转换为 IDisposable 对象）。

但是！

C# 中还有一个不太常用的 ref struct 类型。这种类型的对象在离开作用域时会自动被销毁，所以它们不需要实现 IDisposable 接口。即便如此，我们可以为这种类型的对象添加一个 Dispose 方法，这样我们就可以使用 using 语句来释放资源了。

1
2
3
4
5
6
7
8
9


ref struct MyDisposableStructType
{
 public void Dispose()
 {
 Console.WriteLine("MyDisposableStructType Disposed.");
 }
}

using var s = new MyDisposableStructType();

这样的话，我们就可以对一个没有实现 IDisposable 接口的对象使用 using 语句了。

集合初始化器

C# 中的很多集合类型都支持集合初始化器语法 { } 来初始化集合对象。比如 List 类型可以这样初始化：

1

var list = new List<int> { 1, 2, 3 };

实际上，只要类实现了 IEnumerable 接口，并且包含一个名为 Add 的方法，那么这个类就可以使用集合初始化器语法。比如下面这个例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class PlanetCollection<T> : IEnumerable
{
 public T[] Planets { get; init; }

 private int _index = 0;

 public PlanetCollection(int count)
 {
 Planets = new T[count];
 }

 public void Add(T item)
 {
 if (_index >= Planets.Length)
 throw new IndexOutOfRangeException();
 Planets[_index++] = item;
 }

 public IEnumerator GetEnumerator() => Planets.GetEnumerator();
}

然后我们就可以这样初始化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


var collection = new PlanetCollection<string>(8)
{
 "mercury", "venus", "earth", "mars", "jupiter", "saturn", "uranus", "neptune"
};

// 会被编译为：
PlanetCollection<string> source = new PlanetCollection<string>(8);
source.Add("mercury");
source.Add("venus");
source.Add("earth");
source.Add("mars");
source.Add("jupiter");
source.Add("saturn");
source.Add("uranus");
source.Add("neptune");

元组拆分

C# 在引入了元组后，也引入了元组拆分语法。比如我们可以这样写：

1
2


var (a, b) = (1, 2);
(int c, int d) = (3, 4);

很多原生的类型也支持元组拆分。比如：

1
2
3
4
5


var pair = new KeyValuePair<string, int>("key", 42);
var (key, value) = pair;

var dt = DateTime.Now;
var (year, month, day) = dt;

此外，如果我们声明一个 record 类型，那么底层也会为我们提供元组拆分的功能。

实际上，元组拆分的语法是通过 Deconstruct 方法实现的。只要类中有一个名为 Deconstruct 的方法，并且用 out 的方式进行传参，那么这个类就可以使用元组拆分语法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class Point2d
{
 public int X { get; set; }
 public int Y { get; set; }
 public void Deconstruct(out int x, out int y)
 {
 x = X;
 y = Y;
 }
}

var point = new Point2d { X = 1, Y = 2 };
var (x, y) = point;

LINQ 的 `SelectMany` 方法

最后再说一个比较冷门且不常用的，就是 LINQ 中的 SelectMany 方法，以及多层 from 语句。比如我们现在有一个“数组的数组”一样的结构，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class Person
{
 public string Name { get; set; }
 public List<Pet> Pets { get; set; }
}

class Pet
{
 public string Name { get; set; }
}

我们可以使用 SelectMany 方法来展开这个结构：

1
2
3
4
5
6
7


var people = GetPeople();
// 使用查询表达式
var pets = (from person in people
 from pet in person.Pets
 select pet).ToList();
// 或者链式表达式
var pets = people.SelectMany(p => p.Pets).ToList();

实际上，只要我们为类提供正确的 SelectMany 方法，那么我们就可以使用多层 from 语句来展开这个结构。比如我们可以为上面集合初始化器中的 PlanetCollection 类型提供一个 SelectMany 方法，从而展开这个结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


static class Extensions
{
 public static IEnumerable<TResult> SelectMany<TSource, TCollection, TResult>(
 this PlanetCollection<TSource> source,
 Func<TSource, IEnumerable<TCollection>> collectionSelector,
 Func<TSource, TCollection, TResult> resultSelector
 )
 {
 foreach (var item in source.Planets)
 {
 foreach (var subItem in collectionSelector(item))
 {
 yield return resultSelector(item, subItem);
 }
 }
 }
}

var query = 
 from planet in collection 
 from letter in planet 
 select letter;

Console.WriteLine(new string(query.ToArray()).ToUpper());

这个 SelectMany 方法的要求相对比较复杂，这里我们就不展开讨论了。

总结

看了这篇文章之后，相信大家会对 C# 这门编程语言有一个更新的认识了吧？

事实上，上面提到的大多数鸭子类型，都是与底层 C# 代码密不可分的。这里我给大家提供一个探索的方向，比如可以借助 SharpLab 这样的工具，查看诸如 foreach 语句、await 语句、以及集合初始化器等语法对应的底层 C# 代码。相信大家一定会有所收获。

EntityFrameworkCore 最小入门指南

Wed, 13 Mar 2024 00:00:00 +0000

安装 EntityFrameworkCore

以 Sql Server 为例，可以在 NuGet 包管理器中搜索并安装以下包：

Microsoft.EntityFrameworkCore
Microsoft.EntityFrameworkCore.SqlServer

实现 Model

假定现在有这样一张表：

1
2
3
4
5
6


CREATE TABLE [dbo].[Blog] (
 [BlogId] INT IDENTITY (1, 1) NOT NULL,
 [Title] NVARCHAR (100) NULL,
 [Author] NVARCHAR (50) NULL,
 [Content] NVARCHAR (MAX) NULL,
);

可以创建一个对应的 Model：

1
2
3
4
5
6
7


public class Blog
{
 public int BlogId { get; set; }
 public string Title { get; set; }
 public string Author { get; set; }
 public string Content { get; set; }
}

创建 DbContext

创建一个继承自 DbContext 的类：

1
2
3
4


public class BloggingContext : DbContext
{
 public DbSet<Blog> Blogs { get; set; }
}

这里其实幕后发生了一些基于 EF 命名习惯的自动配置，比如：

Blog 类对应的表名为其复数形式 Blogs
BlogId 字段会被自动识别为主键

配置连接字符串

最简单的方法是直接重写 OnConfiguring 方法：

1
2
3
4
5
6
7


class BloggingContext : DbContext
{
 protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
 {
 optionsBuilder.UseSqlServer(@"Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging;");
 }
}

使用 DbContext

获取 Blog 数据：

1
2
3
4


using (var db = new BloggingContext())
{
 var blogs = db.Blogs.ToList();
}

添加新的 Blog：

1
2
3
4
5


using (var db = new BloggingContext())
{
 db.Blogs.Add(new Blog { Title = "Hello World", Author = "Alice", Content = "Hello World!" });
 db.SaveChanges();
}

总结

在本文中，我们通过一个最小化的示例介绍了如何使用 Entity Framework Core 进行数据访问。我们创建了一个 BloggingContext 类来表示数据库上下文，并定义了一个 DbSet<Blog> 来操作 Blog 实体。我们还展示了如何配置连接字符串，以及如何使用 DbContext 来添加和获取数据。

这个简单的例子虽然只涉及到了基本的操作，但它为理解 EF Core 的工作原理和进一步探索其功能提供了基础。

感谢阅读，欢迎在评论区分享你的想法和问题。

Benchmark.NET 简易指南

Tue, 05 Mar 2024 10:52:37 +0800

Benchmark.NET 是一个用于 .NET 应用程序的强大的基准测试库。它可以帮助开发人员评估他们的代码的性能，找出潜在的性能问题，并且比较不同的实现方式。Benchmark.NET 提供了丰富的特性，包括内存诊断、全局初始化、迭代初始化等，可以满足各种性能测试的需求。

这篇文章将介绍 Benchmark.NET 的基础知识和一些常用的特性。你也可以观看我的 B 站教学视频进行学习。

常用特性

一些常用的特性：

Class
- MemoryDiagnoser：查看内存分配情况（有一个 bool 参数，表示是否显示 GC 的情况）
- SimpleJob：可以设置 .NET 版本，如 RuntimeMoniker.Net60
- Orderer(SummaryOrderPolicy.SlowestToFastest)：输出结果的排序
- RankColumn：为结果表格添加一列 Rank，表示当前行的方法的排名
Method
- Benchmark：表示这个方法需要被测试（另有一个 Baseline 参数，同时会给结果添加一列 Ratio，表示和 Baseline 的比率）
- Arguments：类似于 Params，表示该方法的传参，可以有多个，并且会和 Params 联动，充分考虑各种组合
- GlobalSetup：全局初始化，常用于初始化一个要用来测试的变量、集合等。可以和 Params 联动，比如数组的容量由某个字段决定
- IterationSetup：用于在每次迭代前的初始化，每次迭代都会调用一次
Field
- Params：某个字段可能有不同的值（如果多个字段被标记该特性，则会充分考虑所有参数的组合）

实际例子

测试排序的效率

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


[MemoryDiagnoser]
public class SortTester
{
 private List<int> testList;

 [GlobalSetup]
 public void Setup()
 {
 testList = Enumerable.Range(1, 100).Shuffle(new Random(1334)).ToList();
 }

 [Benchmark]
 public List<int> ListSort()
 {
 var lst = new List<int>(testList);
 lst.Sort();
 return lst;
 }

 [Benchmark]
 public List<int> LinqOrder()
 {
 return testList.Order().ToList();
 }
}

测试初始化数组的效率

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


public class ListInit
{
 [Params(16, 128, 1060)]
 public int count;

 [Benchmark(Baseline = true)]
 public List<int> WithoutInit()
 {
 var res = new List<int>();
 for (int i = 0; i < count; i++)
 res.Add(i);
 return res;
 }

 [Benchmark]
 public List<int> WithInit()
 {
 var res = new List<int>(count);
 for (int i = 0; i < count; i++)
 res.Add(i);
 return res;
 }

 [Benchmark]
 public List<int> WithLinq()
 {
 return Enumerable.Range(0, count).ToList();
 }
}

.NET 6 vs. .NET 7

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


[MemoryDiagnoser(false)]
[SimpleJob(RuntimeMoniker.Net60)]
[SimpleJob(RuntimeMoniker.Net70)]
public class SortTester
{
 private IEnumerable<int> testList;

 [GlobalSetup]
 public void Setup()
 {
 testList = Enumerable.Range(1, 10).ToArray();
 }

 [Benchmark]
 public int CalcMin()
 {
 return testList.Min();
 }
}

注意事项

要使用有编译器优化的 Release 模式
被测试的类、使用了特性的方法与字段均需要为 public
在要测试的方法中尽量避免会被 JIT 优化掉的情况，比如有一个不会被使用的变量等
除非还想要测试内存读取的速度等，否则一般没有必要创建过大的数组

参考链接

Rules of benchmarking - BenchmarkDotNet Documentation

C# 代码格式化工具 CSharpier 上手指南

Mon, 16 Oct 2023 00:00:00 +0000

简介

CSharpier 是一个针对 C# 代码的格式化工具，它可以帮助开发者自动化地调整代码的格式，使其更加一致和易于阅读。CSharpier 提供了丰富的配置选项，可以根据项目的需求定制代码格式化的规则。

它的官方介绍是「CSharpier is an opinionated code formatter for C#」，其中的“opinionated”是一个英文词，意思是“有主见的”或“有偏见的”。它想表达的是，该工具对代码格式化有自己的偏好和主见，即它会按照自己的规则来格式化代码，而不是完全按照用户的意愿。在下面的内容中，大家不难看出，CSharpier 几乎没有提供多少可以配置的选项。

安装

在 VS 的扩展中安装了 CSharpier 后，重启 VS 后会在上方提示安装工具，但是也可以自行安装，方式如下：

1

dotnet tool install -g csharpier

如果希望更新，那么可以：

1

dotnet tool update -g csharpier

除了 VS，VS Code、Rider 中也都有同名的扩展。

配置

可以在项目的根目录（通常与 .sln 文件位置相同）创建一个配置文件，可以是下面三个的任意一种：

.csharpierrc
.csharpierrc.json
.csharpierrc.yaml

支持的配置项非常少，常用的一些如下：

1
2
3
4
5
6


{
 "printWidth": 100,
 "useTabs": false,
 "tabWidth": 4,
 "preprocessorSymbolSets": ["", "DEBUG", "DEBUG,CODE_STYLE"]
}

或者

1
2
3
4
5
6
7


printWidth: 100
useTabs: false
tabWidth: 4
preprocessorSymbolSets:
 - ""
 - "DEBUG"
 - "DEBUG,CODE_STYLE"

其中最后一个配置项与代码中预编译器指令（如 #if DEBUG）有关，详见官方的配置文档。

实用场景

这里我随便写了一大段 C# 代码，大家可以拷贝到自己常用的 C# 开发工具中，然后使用 CSharpier 格式化，从而查看效果。

CSharpier 还提供了一个Playground，方便大家在线体验它的效果。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


class CSharpierDemo
{
 private readonly List<string> allowedExtensions = new List<string> { ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".tiff", ".tif", ".webp", ".heic" };

 private int[,] map = new [,] { { 1, 2, 3 }, { 4, 5, 6 }, { 7, 8, 9 } };

 public static readonly DependencyProperty MyPropertyProperty = DependencyProperty.Register("MyProperty", typeof(string), typeof(MyControl), new PropertyMetadata(""));

 [JsonIgnore] public string MyProperty1 { get; set; }
 [JsonIgnore] public string MyProperty2 { get; set; }
 [JsonIgnore] public string MyProperty3 { get; set; }

 private void Foo()
 {
 allowedExtensions.Select(x => x.Trim().ToLower()).Select(x => x.TrimLeft('.')).Where(x => x.Length == 3).ToList().ForEach(x => Console.WriteLine(x));

 var exts = from x in allowedExtensions select x.Trim().ToLower() into x select x.TrimLeft('.') into x where x.Length == 3 select x;
 }

 private void FooWithManyParameters([FromHeader(Name = "Id")] long id, [FromQuery(Name = "first_name")] string firstName, [FromQuery(Name = "last_name")] string lastName, string? middleName = null, Action? callback = null, Action? errorCallback = null)
 {
 // ...
 }
}

可以用盗版，但是要怀着愧疚的心

Sun, 25 Dec 2022 00:00:00 +0000

.NET 开发这一领域有一款特别有名的小工具名叫 LINQPad，是一位国外技术大牛开发的软件，能够显著提高 .NET 工程师的效率，但是价格也一点不便宜。除了（基本上是个半残的）免费版，还有专业版、开发者版以及尊享版，而我买的就是最贵的版本，$115，按照当时的汇率，足足 800+ RMB。但是我认为买得很值。我一直在用，它帮上了大忙，那么我觉得它是完全值得我花这笔钱的。

不仅如此，我还觉得这款软件在国外非常火爆，在国内却鲜有人知道，所以我专门制作了一期视频分享给了大家。

不久之后，我就看到了评论区这么一条内容：

这条评论我觉得真是又好气又好笑。这句话实在是不合逻辑，槽点太多，也让我看到了一些人对于所谓的付费软件以及程序员群体有着怎样的误解。

只适合专业程序员？

首先第一条，什么叫“可惜太贵，只适合专业程序员”？意思是说，不专业的程序员，或者学生党之类的就不适合？这款软件虽然最高一档的价值 800+，但是免费版也凑活着能用啊？或者你咬咬牙，花个不到 400 元就可以买一个专业版了。讲道理，400 块算多吗？放在氪金手游里面，怕不是只能抽出来一些卡池里面的乐色吧？我现在上班，每天光是坐地铁就要 10 元，一个月就是 200 多；每天三餐要花三四十，一个月就要 1000 块；这年头手机的话费，一年怎么着不得 400+？为什么这些都像是习以为常的东西，眼前的一款买断制的软件你却下不了手了？

更重要的是，买了这款软件，它可以帮助你不说一辈子了，最起码在接下来几年的学习工作生涯的黄金期里助你一臂之力，大幅提高工作学习的效率，明显发挥出软件自身的价值，难道不比你买一个氪个什么 328、648 要有意义得多？

程序员不在乎这点钱？

第二条，什么叫“程序员不在乎这点钱”？意思是说程序员都是高薪行业的人才，一个个月入好几万，根本不会在乎这么一丁点钱？不好意思，你又错了。首先，程序员就不是你想象中的这么高薪。或许能月入个一万多，但是大都是在北上广深这些地方，每月光是房租就要花个好几千，最后算下来也不剩多少了。就这还是拿身体换来的，一个个年纪轻轻地就眼睛也不好了，颈椎腰椎也不好了，手腕也不好了，头发也不剩多少了。所以程序员也不见得就不在乎这点钱的。

这种说的还是单身的没有梦想成为咸鱼的程序员。如果想结婚生子，想买房买车，想提升自己，给自己买个网课、健身房会员卡什么的，那更是开支大了去了。你月入 40K 又如何？说不定月供就两三万。所以专业程序员就不差钱了？真是想太多了。

不差钱的程序员就会愿意掏钱？

再然后，“他们不差这点钱”，所以他们就“适合买这款软件了”？不好意思，我身边“在乎这点钱”的程序员多了去了。我认识一位程序员，每周工作日至少喝三四杯国内某知名连锁店铺的奶茶，每杯按 18 块算，一个月最少也要 200 多块了。但是咧，人家连 Office 用的都是盗版的 2010，整天标题栏都是大红色的，连个京东淘宝上搞活动 200 多块的正版 Office 365（后来改名叫 Microsoft 365 了）都舍不得买，即便人家每天到手的工资都够买原价的 365 了。这种人有可能会愿意花好几百买一款没有任何开发功能，只是方便自己工作学习的小软件？

我身边这样的程序员真的是不少。我推荐他们用 XMind，明明这玩意有免费的试用版，但是他们就是喜欢一上去就在百度搜索破解版，最后下了个盗版的 XMind 8；开发软件用的 IDE，直接去搜个破解版 JetBrains 系列的，都不知道有免费的 Visual Studio 社区版以及 Visual Studio Code 可以用的；iPad 上看 PDF 记个笔记或者画个画，连个 Notability 或者 Procreate 都舍不得买，非得去找个多人共用的苹果账号用“分享版”的，不知道哪天 APP 就不能更新了。那我要是推荐他们去用 LINQPad，不用说，肯定去找盗版了，明明还有一个免费的平替 RoslynPad。

所以我想说的是，并不是所有程序员都不觉得这笔钱不是钱，也并不是所有程序员在买得起这款软件的情况下就会愿意掏钱。退一步说，就算是舍不得买正版，也不代表你就要去用盗版啊？我买不起正版 PS，但我买得起 Affinity Photo；我买不起 PR，但我可以用免费的 DaVinci；买不起 Office，但还可以用 WPS（如果你能接受广告什么的）或者 LibreOffice；买不起 LINQPad，那还可以用平替的 RoslynPad，或者不然就在 VS 里面新建一个 Console App 呗。

到底什么样的人适合这款软件？

那到底什么样的人才适合这款软件呢？我开头就已经说了，这款软件可以帮到这个行业的所有人群，不论你的技术是强还是弱，你的钱包是鼓还是瘪。只要你有着一颗想要提升自己的心，以及对正版优质软件的认可，那么我都认为你可以去买这款软件。

而这样的人恐怕并不是很多。有的图像工作者，已经依靠修图挣了很多钱，却不愿买正版的 PS；有的音乐工作者，依靠编曲已经足够养家糊口，但依旧不愿意买个正版 FL；有的程序员，已经依靠写代码挣了这么多钱，却依旧不愿意为他们使用的软件付个费，凡事总是想着去搜索破解版，甚至不以为耻，反而觉得占到了多大的便宜。当然还有些蠢货觉得这都是外国软件，跟境外势力有什么好客气的，或者“慈禧太后当年都把钱给掏过了”之类，那我真是无 f*ck 说。

曾经有一个同事得知我用的是每年花费好几百的正版 Office 订阅，觉得不以为然，说自己用的是破解版，不照样可以用吗，还省下了不少钱。我没有回答他，但是我有一句差点到嘴边了的话被我给咽了回去：请问你每年比我省下了好几百，那么你比我多得到了什么呢？

到底能不能用盗版软件？

最后，我想聊的是，盗版软件到底能不能用？我认为可以用，但是要时刻知道这样做是不对的。Minecraft《我的世界》（以下简称 MC）是一款全球知名的沙盒类游戏，但是正版是要钱的。有一位学生写信给 MC 的创始人 Notch 说，自己想玩 MC，但是没有足够的钱，问能不能玩盗版的？Notch 笑着回答说，可以玩，但是要怀着愧疚的心。

你如果对这款软件实际的效果不够放心，那你大可以去找一个破解版，然后用上一段时间（虽然它本身也提供了 30 天无条件退款）。如果你觉得这个软件不行，那你可以不去用它；如果你觉得这款软件不错，那你可以选择付费；但是你不能就这么一直用着盗版。用一段时间的盗版之后，如果觉得软件确实很好，那么我相信，善良正直的你，会选择为这款优秀的软件补票的。

这也正是我对那些使用破解版软件的人的建议。

寒流の编程笔记

你好，世界！

如何减少 PNG 文件大小

尝试使用不复杂的图片

尝试压缩 PNG 图片

量化 PNG 图片到 256 色

用 pngquant + oxipng

总结

在 WPF 等桌面应用中应该单纯使用 DI 还是引入 Generic Host？

单纯使用 DI（ServiceCollection）

在 WPF 中集成单纯 DI

方案特点

引入 Generic Host

多源配置系统

结构化日志与第三方日志集成

后台托管服务（Hosted Services）

权衡与取舍

依赖包体积与依赖树深度

生命周期模型的差异

按需组装的折中方案

总结

System.Text.Json 相较于老牌 Newtonsoft.Json 目前仍缺失的功能及补救方法

JSONPath

使用 JsonPath.NET

PopulateObject 填充既有对象

DataTable 与 DataSet

TypeNameHandling 与多态序列化

为什么要设计成这样？

BSON

总结

如何在 .NET 中获取程序的根目录？

BaseDirectory

Environment.CurrentDirectory

Assembly

Assembly.Location

Assembly.GetXXXAssembly()

总结

Figgle：在控制台中打印 ASCII 艺术字

Figgle 的几个 NuGet 包

Figgle

Figgle.Fonts

Figgle.Generator

使用 Figgle 和 Figgle.Fonts

使用 Figgle.Generator

在编译期生成固定文本

嵌入字体并在运行时渲染

常用字体推荐

Big

Slant

Ogre

Larry3d

预览全部字体

System.Text.Json：.NET 内置的 JSON 库

历史

早期的官方库

Newtonsoft.Json 的崛起

现代化的挑战

System.Text.Json 的诞生

基本用法

序列化与反序列化

配置（JsonSerializerOptions）

命名策略

Web 预设（.NET 5+）

特性标注

[JsonPropertyName]

[JsonIgnore]

[JsonInclude]（.NET 5+）

[JsonPropertyOrder]（.NET 6+）

Record 类型

位置 Record

选择构造函数：[JsonConstructor]

参数名匹配

JsonNode

解析与读取

构建 JSON

修改 DOM

与强类型对象互转

遍历

只读场景：JsonDocument

自定义转换器：JsonConverter

`Figgle`

`Figgle.Fonts`

`Figgle.Generator`

`[JsonPropertyName]`

`[JsonIgnore]`

`[JsonInclude]`（.NET 5+）

`[JsonPropertyOrder]`（.NET 6+）

选择构造函数：`[JsonConstructor]`

第一个窗口不是 `MainWindow` 该怎么办？

方法三：使用 `IDbContextFactory`