用途:本技能为在 .NET 中创建和消费 Roslyn 源生成器提供指导。创建侧覆盖 IIncrementalGenerator、语法提供器、语义分析、生成模式、诊断报告,以及用 CSharpGeneratorDriver 测试;消费侧覆盖 [GeneratedRegex]、[LoggerMessage]、System.Text.Json 源生成与 [JsonSerializable]。
创建要点:生成器以面向 netstandard2.0 的分析器形式发布,项目需设置 EnforceExtendedAnalyzerRules、IsRoslynComponent 与 LangVersion>latest,并引用 Microsoft.CodeAnalysis.Analyzers 与 Microsoft.CodeAnalysis.CSharp(PrivateAssets=all)。优先使用 IIncrementalGenerator 而非旧版 ISourceGenerator,因其具备缓存感知、仅在输入变化时重跑。管道设计规则:尽早过滤(ForAttributeWithMetadataName 或带严格谓词的 CreateSyntaxProvider);在 transform 步骤只提取简单数据,不要把 ISymbol 或 SyntaxNode 传入管道;使用值相等类型(record struct 或 IEquatable<T>);输出需确定性,带 // <auto-generated/> 与 #nullable enable 头。诊断通过 SourceProductionContext.ReportDiagnostic 报告而非抛异常;Location 不具值相等性,需注意缓存影响。可用 RegisterPostInitializationOutput 生成标记特性等静态源。测试可用 CSharpGeneratorDriver 在内存中运行,或用 Verify.SourceGenerators 做快照测试。
消费要点:[GeneratedRegex](net7.0+)要求方法为 static partial 且返回 Regex,置于 partial 类或结构体,支持除 RegexOptions.Compiled 外的选项。[LoggerMessage](net6.0+)要求方法为 partial 类中的 static partial,消息中 {占位符} 参数作为结构化数据记录,异常参数自动记录,建议显式指定 Event ID。System.Text.Json 源生成(net6.0+)需在 [JsonSerializable] 中注册所有待序列化类型,可用 TypeInfoResolverChain 组合多个上下文,是 Native AOT 所必需。
打包与引用:消费项目通过 ProjectReference 并设置 OutputItemType="Analyzer"、ReferenceOutputAssembly="false" 引用生成器;NuGet 包需将程序集放在 analyzers/dotnet/cs/ 下,并设置 IncludeBuildOutput=false、DevelopmentDependency=true。
限制:资料未提供具体收费、价格、平台或效果信息;示例仅针对顶层非泛型类,生产级生成器还需处理泛型类型参数与嵌套类型,并对不支持形态报告诊断。