如何在XML注释中使用#if指令避免CS1570、CS1587编译警告

错误原因 #

这个报错的核心原因是：C# 编译器将连续的以///开头的行识别为同一个XML注释块，只要中间插入了非///开头的行（包括#if、#endif预处理器指令行），就会被判定为当前XML注释块结束。
当未定义Client符号时：

1. 第一块XML注释到/// Common info.行就中断了，内部只有<remarks>开始标签，没有结束标签，触发CS1570格式错误
2. 后续单独的/// </remarks>行没有对应绑定的代码元素，触发CS1587错误

可行解决方案 #

方案1：条件编译包裹完整XML注释块（最推荐） #

直接将不同分支的完整XML注释放在独立的条件编译块内，保证每个分支内的XML注释都是连续、结构完整的，不会被非///行打断。

/// <summary>
///   Does something.
/// </summary>
#if Client
/// <remarks>
///   Common info.
///   Additional info for client only.
/// </remarks>
#else
/// <remarks>
///   Common info.
/// </remarks>
#endif

该方案为C#原生语法，无需额外配置，编译器可完整校验注释格式，适合注释差异较小的场景。

方案2：<include>标签抽离公共注释（适合公共内容多的场景） #

如果公共注释内容较多，不想在多分支重复编写，可以用XML注释原生的<include>标签，把公共内容抽离到外部XML文件，仅差异化内容分分支维护。

1. 项目中新建公共注释XML文件，例如CommonComments.xml：

<Comments>
  <TargetMember>
    <summary>Does something.</summary>
    <commonRemark>Common info.</commonRemark>
  </TargetMember>
</Comments>

2. 代码中引用公共内容：

/// <include file="CommonComments.xml" path="Comments/TargetMember/summary/*" />
#if Client
/// <remarks>
///   <include file="CommonComments.xml" path="Comments/TargetMember/commonRemark/*" />
///   Additional info for client only.
/// </remarks>
#else
/// <remarks>
///   <include file="CommonComments.xml" path="Comments/TargetMember/commonRemark/*" />
/// </remarks>
#endif

方案3：临时禁用指定警告（不推荐） #

仅用于临时调试场景，可在代码文件顶部添加预处理器指令屏蔽对应警告：

#pragma warning disable 1570, 1587

该方案会屏蔽所有同类警告，包括真正的XML注释格式错误，不建议长期使用。

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