.NET on 寒流の编程笔记

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 声明方式，那么就需要提供带参构造函数来实现反序列化了。当类型有多个构造函数时，必须用 [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 first = root["scores"]![0]!.GetValue<int>(); // 95

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]!; // JToken 支持隐式转换

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。

源生成器

无论是强类型的 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 支持和特性标注等内容应该能覆盖大多数日常场景。而对于追求极致性能或需要 NativeAOT 发布的项目，源生成器则是必选项。随着 .NET 的持续演进，System.Text.Json 的功能覆盖已经相当完善，完全可以在大多数项目中替代 Newtonsoft.Json。

在 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# 在未来能继续引入更多强大的类型特性，让我们的代码更安全、更简洁、更易维护。

在 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，以便享受到这些改进和优化带来的好处。

.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 中的计时器，并在实际开发中选择合适的计时器来满足你的需求。如果你有任何问题或建议，欢迎在评论区留言讨论！

逆向思考 .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 方法的思路。

在实际的开发中，与其说我们需要分辨出哪些对象是可以不用释放的，不如说我们应当明白如何对这一操作的必要性进行正确的判断，并养成统一且规范的开发习惯。这样不管是对团队的其他开发者，还是未来的自己，都是有好处的。

常见图片相关的数据类型之间的转换

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 控件。这样的方式，可以保证我们的代码在大多数情况下都能正常工作。

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# 字符串操作的实用技巧和易犯错误。希望大家在以后的开发中，能够更加熟练地使用字符串，写出更加高效的代码。

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# 代码。相信大家一定会有所收获。

.NET on 寒流の编程笔记

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

源生成器

基本配置

使用方式

配置选项

两种生成模式

NativeAOT 与裁剪

与 ASP.NET Core 集成

总结

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

Union 类型的核心目标

枚举类型 enum

包含多个属性的类

object 类型

空的抽象基类或接口

OneOf 第三方库

缺乏语言级别的语法糖

代码繁杂

缺乏领域签名

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

Union 类型的到来

底层原理

总结

在 C# 中使用 IComparer 实现自定义排序

IComparer 接口的定义

一个简单的例子

一个更通用的例子

其他方式

总结

盘点 LINQ 在最近几个 .NET 版本中新增的功能和特性

.NET 6

1. Chunk 方法

2. MinBy & MaxBy

3. DistinctBy 等

4. FirstOrDefault 等方法的重载

5. Take

6. Zip

.NET 7

Order & OrderDescending

.NET 8

.NET 9

Index

CountBy

AggregateBy

关于 By 的思考

总结

.NET 原生有哪些 Timer 以及它们分别是怎么用的？

一共有多少种 Timer？

System.Threading.Timer

System.Timers.Timer

System.Threading.PeriodicTimer

System.Windows.Threading.DispatcherTimer

总结

`[JsonPropertyName]`

`[JsonIgnore]`

`[JsonInclude]`（.NET 5+）

`[JsonPropertyOrder]`（.NET 6+）

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

`init` 访问器与记录类

`foreach` 语句

`await` 语句

`using` 语句

LINQ 的 `SelectMany` 方法