C# 摘要注释中的 XML 字符串答案

【问题标题】：Xml string in a C# summary commentC# 摘要注释中的 XML 字符串
【发布时间】：2010-10-11 01:29:47
【问题描述】：

我正在记录一些我在 C# 中编写的用于解析标记的方法。由于系统其他领域的一些技术限制，这些令牌需要采用 XML 元素的形式（即<tokenName />）。我想将这些标记的格式放在摘要语句本身中。

但是，这会引发错误：格式错误的 XML -- A name was started with an invalid character"。是否有任何类型的转义字符序列可用于在我的 C# 摘要 cmets 中嵌入 XML？

【问题讨论】：

另见Can use "{}" inside cref。在If you place it in a cref element, you can instead use { and } 中有更多详细信息。
How do I escape characters in c# comments?的可能重复

【解决方案1】：

使用标准的 XML 转义。例如：

<summary>This takes a &lt;token1&gt; and turns it into a &lt;token2&gt;</summary>

作为代码输入或阅读并不容易，但 IntelliSense 可以正确地取消转义，您会在工具提示中看到正确、可读的内容。

【讨论】：

【解决方案2】：

使用 CDATA 部分。例如：

<![CDATA[ <name>Bob</name> ]]>

当您拥有较大的 XML 片段时，这在源代码中比在实体引用中编码特殊字符更优雅和可读。

如果要嵌入的 XML 本身包含 CDATA 部分，则需要使用多个 CDATA 部分，如another answer on Stack Overflow 或Wikipedia 中所述。或者，您始终可以使用此处其他答案中所述的普通实体引用。

【讨论】：

但见VisualStudio's tooltip doesn't display anything inside a CDATA-section。

【解决方案3】：

我使用转义序列，因为 VisualStudios 工具提示不显示 CDATA 部分内的任何内容。

【讨论】：

【解决方案4】：

我遇到了同样的问题。使用 <![CDATA[]]> 将隐藏 IntelliSense 中的评论。

同时替换&lt; 和> 对我来说工作量太大（懒惰:)）。我发现只需将 &lt; 替换为 &lt; 就足以用于 IntelliSense，因为它会使 xml 无效并适合 IntelliSense 解析为摘要块中的文本。

这是一个例子：

/// <summary>
/// Parse the queue process response
/// <para>&lt;?xml version="1.0" encoding="utf-16"?>&lt;result success="True">&lt;entity type="resource" operation="update" />&lt;/result></para>
/// <![CDATA[
/// <?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>
/// ]]></summary>
/// <param name="response"></param>
/// <returns></returns>

IntelliSense 会显示：

Parse the queue process response
<?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>

【讨论】：