C#摘要注释中的Xml字符串

Question

我记录了一些我在C#中编写的处理令牌的方法。由于系统的其他领域存在一些技术限制，这些令牌需要采用XML元素形式（即<tokenName />）。我想把这些令牌的格式放在概述语句中。

然而，这会引发错误：“Badly formed XML -- A name was started with an invalid character”。我是否可以使用任何转义字符序列将XML嵌入到我的C#摘要注释中？

- loomisjennifer

---

参见可以在cref中使用“{}”。更详细的信息请参见如果将其放置在cref元素中，则可以使用{和}。 - ToolmakerSteve

可能是如何在C#注释中转义字符？的重复问题。 - Michael Freidgeim

Answer 1

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

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

虽然不太容易作为代码进行输入或阅读，但 IntelliSense 正确解码并在工具提示中显示正确的可读内容。

- Andrew Arnott

Answer 2

使用CDATA段落。例如：

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

当你需要嵌入更大的XML片段时，通过在源代码中编码特殊字符而不是使用实体引用来完成更为优雅和易读。

如果你要嵌入的XML本身包含CDATA节, 你需要像在 Stack Overflow 上的另一个答案或 Wikipedia中所描述的那样使用多个CDATA部分。或者你可以像其他答案中所述一样始终使用普通实体引用。

- Sean

---

请参见 VisualStudio 的工具提示无法在 CDATA 区段内显示任何内容。 - ToolmakerSteve

Answer 3

我遇到了同样的问题。使用 <![CDATA[]]> 会隐藏 IntelliSense 中的注释。

我觉得把 < 和 > 都替换掉有点麻烦（有点懒）。我发现只需将 < 替换为 < 就足够让 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>

智能感知将会显示如下内容：

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

- Mario

Answer 4

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

- FloWi