如何在 XML 注释中使用 #if答案

【问题标题】：How to use #if in an XML comment如何在 XML 注释中使用 #if
【发布时间】：2021-11-17 15:21:10
【问题描述】：

我正在编写一个库，其中包含服务器和客户端共有的源代码。

我遇到的问题是在 XML cmets 内部，有时客户端和服务器文档会有所不同，例如：

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

当我在没有定义 Client 符号的情况下进行编译时，我会收到以下警告：

Warning CS1570: XML comment has badly formed XML -- 'Expected an end tag for element 'remarks'.'
CS1570: XML comment has badly formed XML -- 'End tag was not expected at this location.'
Warning CS1587: XML comment is not placed on a valid language element

有没有办法解决这个问题，还是没有希望？

【问题讨论】：

基于一些github 问题“没有希望”的可能性更大。
这对我来说听起来像是一个 XY 问题。如果您必须这样做，则表明您的设计不正确
@Liam：为什么在客户端和服务器之间拥有不同的文档是一种设计流程？一个处理 SQL 表，另一个处理向服务器发送请求。
那你为什么没有两节课呢？或者使用抽象类或其他设计模式的实现。您为两个功能公开相同的合同，这看起来很奇怪且令人困惑
@Liam 首先，源代码被编译成两个不同的程序集，一个用于服务器应用程序，一个用于客户端。对于这两种实现，属性、文档（几乎）和一些算法都是相同的，拥有两个不同的类意味着代码将被重复。

标签： c# xml-comments

【解决方案1】：

目前不支持此功能。对不起。

在官方的C# github仓库中，已经有关于这个特性的提案：

Proposal: Conditional Compilation in XML Comments #295

但是，此提案来自 2017 年，并且仍被标记为“未答复”，因此请不要屏住呼吸。

作为旁注，提案中的评论线程还 contains an explanation 表示 为什么 这不起作用：那些 #if 语句 看起来 像经典，C -style 预处理器指令，但它们不是。例如，你可以写：

Console.WriteLine(@"

#if false
This is all inside the string and will get printed to the console
#endif

");

#... 行将在字符串中结束。

【讨论】：

这不是完全一样的东西，因为XML注释在每一行结束，所以原帖中的代码没有问题。在整行中启用#if 就足够了。

【解决方案2】：

因为这在 C# 中似乎是不可能的，所以我创建了一个小工具来对 XML cmets 文件进行后处理。这是目前满足我需求的第一个版本，但还有很大的改进空间。

条件 XML cmets

XML cmets 应该是（与 OP 相同）：

  /// <summary>
  ///   Does something.
  /// </summary>
  /// <remarks>
  ///   Common info.
  ///   <if symbol="client">
  ///   Additional info for client only.
  ///   </if>
  /// </remarks>

运行工具

您可以运行该工具：

在构建后事件中，因此每次运行解决方案时都会自动运行。
在命令行中（如果有多个批处理文件），因此您可以仅在需要生成文档时运行它。

程序的第一个参数是要处理的 XML 注释文件的名称。

以下参数是定义符号的名称。

该工具将 XML 文件替换为已处理的文件。

源代码

可以在GitHub repository找到源码和资料

【讨论】：