正则表达式在C#项目中的应用非常普遍，从日志解析到输入验证都离不开Regex类。传统Regex在首次执行时需要进行解析和编译，如果使用RegexOptions.Compiled还会产生额外的动态生成IL代码开销。GeneratedRegex源生成器是.NET提供的一种新方案，它在编译阶段就将正则表达式转成强类型的C#代码，避免运行时的反射和动态编译。本文会介绍如何声明生成方法、如何传递超时和选项，以及生成后的代码如何提升匹配速度。还会通过基准测试说明与传统Regex的差异，并讨论哪些场景最适合使用源生成器。
GeneratedRegex的工作方式与优势
在理解GeneratedRegex之前，先回顾一下传统Regex的运作机制。当你执行new Regex(pattern)或者Regex.Match(input, pattern)时，Regex对象需要解析正则表达式语法，构建内部的状态机或表达式树。如果显式指定了RegexOptions.Compiled，运行时还会通过反射发出动态生成IL代码，这个过程发生在应用程序启动之后，不仅耗时，而且产出的代码无法被AOT编译器提前处理。
GeneratedRegex源生成器则完全不同。它属于.NET源生成器家族，工作在编译阶段，由编译器直接扫描带有[GeneratedRegex]特性的部分方法声明，然后将正则表达式文本翻译为等价的C#代码，并注入到程序集中。这样生成出来的代码就是普通的静态方法，没有运行时的解析开销，也没有动态IL生成。对于使用NativeAOT或希望减小启动时间的应用来说，这一点尤其重要，因为AOT环境通常禁止运行时发出代码。
除了性能优势，GeneratedRegex还带来了更好的可维护性。正则表达式模式被固定在特性参数中，对应的生成方法名可以清晰表达意图，比如EmailRegex()或PhoneRegex()。这比散落在代码各处的字符串字面量更容易管理。同时，生成器会校验正则表达式的语法，编译失败时直接产生编译错误，避免把错误留到运行时才暴露。
声明GeneratedRegex方法的基本步骤
要使用GeneratedRegex，首先需要在一个partial类中声明一个partial方法。这个方法不能有方法体，返回类型必须是Regex。源生成器会根据特性参数自动实现方法体。下面是一个最简单的声明示例，用于匹配常见的手机号码格式。
using System.Text.RegularExpressions;
public partial class MyRegexes
{
[GeneratedRegex(@"^1[3-9]\d{9}$")]
public static partial Regex PhoneRegex();
}
这段代码声明了一个静态部分方法PhoneRegex，返回Regex实例。源生成器会在编译时生成类似下面这样的实现代码，不过具体细节远比这个复杂，因为它会展开正则的解析逻辑，生成专用的匹配状态机。
// 源生成器生成的代码示意，实际不可见
public static partial Regex PhoneRegex()
{
return new Regex(@"^1[3-9]\d{9}$", RegexOptions.None, TimeSpan.FromMilliseconds(-1));
}
方法声明后，调用方式与使用普通Regex对象没有任何区别。例如，你可以这样判断一个字符串是否是合法的手机号。
var input = "13812345678"; bool isValid = MyRegexes.PhoneRegex().IsMatch(input); Console.WriteLine(isValid); // 输出 True
需要注意的是，GeneratedRegex默认使用RegexOptions.None，并且没有超时限制。如果你需要忽略大小写、多行模式等选项，可以在特性参数中传递RegexOptions。超时时间以毫秒为单位，作为第三个参数传入。下面的示例展示了如何声明一个忽略大小写并且限制匹配超时时间为500毫秒的邮箱正则。
public partial class MyRegexes
{
[GeneratedRegex(@"^[^@\s]+@[^@\s]+\.[^@\s]+$", RegexOptions.IgnoreCase, 500)]
public static partial Regex EmailRegex();
}
使用带超时的正则时，如果匹配操作超过指定时间，会抛出RegexMatchTimeoutException异常。这种防护对于用户输入场景非常必要，可以防止恶意构造的字符串造成ReDoS攻击。在之前的传统写法中，超时通常需要每次调用时手动传递TimeSpan，而GeneratedRegex把超时写死在特性里，调用方可以更省心。
性能对比与使用建议
GeneratedRegex的性能优势主要体现在两个方面：首次执行速度和稳定吞吐量。传统Regex在第一次匹配时需要解析和编译，冷启动延迟可能达到几十毫秒甚至更高，尤其是复杂表达式加上RegexOptions.Compiled时。GeneratedRegex把这份工作提前到编译阶段，首次调用和后续调用几乎没有差异，启动时间大幅缩短。
在内存分配方面，GeneratedRegex生成的状态机代码直接操作输入字符串的字符，避免了传统Regex内部部分临时对象的创建。对于高频匹配场景，比如在循环中扫描几十万条日志，这些微小的分配累积起来会显著影响GC压力。下面用一个简单的基准对比来展示差异，虽然不同机器和表达式会有波动，但趋势是明确的。
// 传统方式
var regex = new Regex(@"\d{4}-\d{2}-\d{2}", RegexOptions.Compiled);
for (int i = 0; i < 1_000_000; i++)
{
regex.IsMatch("2025-03-15");
}
// GeneratedRegex方式
for (int i = 0; i < 1_000_000; i++)
{
MyRegexes.DateRegex().IsMatch("2025-03-15");
}
在这个示例中，DateRegex需要在类中声明为[GeneratedRegex(@"\d{4}-\d{2}-\d{2}")]。从执行时间看，GeneratedRegex通常比RegexOptions.Compiled的冷启动快一个数量级，而且在持续调用中也不会劣化。但如果正则表达式只在程序生命周期内使用一两次，生成器的收益就不那么明显了，反而会增加编译产物体积。
另一个值得注意的差异是调试体验。传统Regex支持运行时动态传入模式字符串，而GeneratedRegex的模式必须在编译期确定。这意味着它不适用于需要根据用户输入动态构建正则的场景。比如一个通用搜索工具允许用户输入任意正则表达式，这种情况下就无法使用源生成器。对于固定的、复用频率高的正则，比如协议解析、数据清洗，GeneratedRegex是最合适的。
注意事项与常见错误
使用GeneratedRegex时，有几个约束必须遵守。方法必须是partial，类也必须是partial，并且方法声明不能有方法体。返回类型必须是System.Text.RegularExpressions.Regex。如果违反这些规则，编译器会报错，提示源生成器无法处理该声明。此外，声明的方法不能是async，不能有out或ref参数。
正则表达式字符串中的反斜杠需要特别注意。如果你使用普通字符串字面量，比如"\d+"，C#会尝试将\d解释为转义序列，导致编译错误或错误模式。正确做法是使用逐字字符串字面量@"\d+"，这样反斜杠会原样保留并交给正则引擎处理。在Windows文件路径匹配时更要小心，例如匹配路径C:\ASR\，正则应该写成@"C:\\ASR\\"，确保每个反斜杠都正确表达。
还有一个容易混淆的地方：GeneratedRegex特性来自命名空间System.Text.RegularExpressions，但源生成器本身在编译器中工作，不需要额外引用包。只要目标框架是.NET 7或更高版本，就可以直接使用。如果你在较旧的框架上尝试添加该特性，编译会失败。对于需要保持跨版本兼容的项目，建议通过条件编译或抽象层来隔离GeneratedRegex的使用，避免影响旧环境构建。
最后，虽然GeneratedRegex生成的代码性能很好，但不要忽视正则表达式本身的设计质量。一个糟糕的模式，比如灾难性回溯的表达式，即使通过源生成器加速，依然可能耗尽CPU时间。因此，在启用生成器之前，先用工具分析正则的复杂度，并通过设置合理超时来兜底，才是稳妥的工程实践。
C#正则表达式GeneratedRegex源生成器修改时间：2026-09-29 09:41:16