C#代码分析器：如何仅对接口成员强制要求XML文档注释？

方法一：StyleCop Analyzers 精准配置 #

StyleCop Analyzers的SA1600规则默认检查所有成员，但可以通过.editorconfig或规则集文件，将规则的作用范围限制在接口的成员上：

• 先在项目中安装StyleCop.Analyzers NuGet包。
• 在项目根目录创建/编辑.editorconfig文件，添加以下配置：

  # 全局禁用SA1600
  dotnet_diagnostic.SA1600.severity = none
  
  # 仅对接口的成员启用SA1600
  [*.cs]
  dotnet_diagnostic.SA1600.severity = warning
  dotnet_diagnostic.SA1600.enabled = true
  dotnet_code_quality.SA1600.target_kinds = interface, interface_member
  

  这里通过target_kinds指定规则仅作用于接口和接口成员，其他类型的成员不会触发该规则。
• 如果使用规则集文件（.ruleset），可以打开规则集编辑器，找到SA1600规则，在"适用范围"里选择"接口"和"接口成员"，其他类型取消勾选。

方法二：自定义Roslyn分析器 #

如果需要更灵活的控制，可以自己写一个轻量的Roslyn分析器：

• 创建一个"Roslyn分析器"项目（Visual Studio直接选对应模板）。
• 编写核心分析逻辑，示例代码：

  [DiagnosticAnalyzer(LanguageNames.CSharp)]
  public class InterfaceMemberXmlCommentAnalyzer : DiagnosticAnalyzer
  {
      public const string DiagnosticId = "InterfaceCommentRequired";
      private static readonly LocalizableString Title = "接口成员必须包含XML文档注释";
      private static readonly LocalizableString MessageFormat = "接口成员 '{0}' 缺少XML文档注释";
      private static readonly LocalizableString Description = "强制接口的所有成员添加XML文档注释";
      private const string Category = "Documentation";
  
      private static readonly DiagnosticDescriptor Rule = new DiagnosticDescriptor(
          DiagnosticId, Title, MessageFormat, Category, 
          DiagnosticSeverity.Warning, isEnabledByDefault: true, description: Description);
  
      public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(Rule);
  
      public override void Initialize(AnalysisContext context)
      {
          context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
          context.EnableConcurrentExecution();
  
          // 监听接口成员的语法节点
          context.RegisterSymbolAction(AnalyzeSymbol, SymbolKind.Method, SymbolKind.Property, SymbolKind.Event, SymbolKind.Field);
      }
  
      private static void AnalyzeSymbol(SymbolAnalysisContext context)
      {
          var memberSymbol = context.Symbol;
          // 判断成员是否属于接口
          if (memberSymbol.ContainingType.TypeKind != TypeKind.Interface)
              return;
  
          // 检查是否有XML文档注释
          if (memberSymbol.GetDocumentationCommentXml() == string.Empty)
          {
              var diagnostic = Diagnostic.Create(Rule, memberSymbol.Locations[0], memberSymbol.Name);
              context.ReportDiagnostic(diagnostic);
          }
      }
  }
  

• 将分析器项目打包成NuGet包，或者直接引用到目标项目中，即可自动检查接口成员的XML注释缺失问题。

方法三：编译器警告CS1591的范围限定 #

CS1591是编译器自带的"缺少公开类型或成员的XML注释"警告，可通过排除其他类型间接实现仅检查接口：

• 在项目文件（.csproj）中添加以下配置：

  <PropertyGroup>
      <!-- 启用XML文档文件生成 -->
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <!-- 先全局禁用CS1591 -->
      <NoWarn>$(NoWarn);CS1591</NoWarn>
  </PropertyGroup>
  
  <!-- 引用规则集文件限定CS1591作用范围 -->
  <ItemGroup>
      <AdditionalFiles Include="interface-only.ruleset" />
  </ItemGroup>
  

• 创建interface-only.ruleset文件，内容如下：

  <RuleSet Name="Interface Only XML Comments" Description="仅检查接口成员的XML注释" ToolsVersion="17.0">
      <Rules AnalyzerId="Microsoft.CodeAnalysis.CSharp" RuleNamespace="Microsoft.CodeAnalysis.CSharp">
          <Rule Id="CS1591" Action="Warning" />
      </Rules>
      <DiagnosticFilters>
          <DiagnosticFilter Category="Documentation" Action="None">
              <And>
                  <Not>
                      <Kind Kind="Interface" />
                  </Not>
                  <Not>
                      <Kind Kind="InterfaceMember" />
                  </Not>
              </And>
          </DiagnosticFilter>
      </DiagnosticFilters>
  </RuleSet>
  

  该规则集会过滤掉非接口类型的CS1591警告，仅对接口成员生效。

内容的提问来源于stack exchange，提问作者Batesias