.NET代码XML文档注释中如何在代码示例内原样显示HTML标记

问题本质 #

.NET XML文档注释的渲染链路（包括Visual Studio的悬停提示、官方文档生成工具）默认会解析<c>、<code>标签内部的类HTML标记，哪怕写入时做了基础XML转义，部分渲染环节会先将转义实体还原为标签再做富文本渲染，最终导致HTML标记被当做格式规则处理，不会作为纯文本展示。

可行方案 #

• 双重XML转义（兼容性最优，推荐）
  基础XML转义仅将<转写为<、"转写为"，无法避免二次解析问题。双重转义需要在基础转义的前提下，将所有转义后开头的&再转写为&，让渲染器第一次解析后得到的是转义后的文本，不会识别为可渲染的HTML标签。
  对应VB注释的正确写法：

  ''' <summary>
  ''' <code>
  ''' &amp;lt;div class=&amp;quot;foo&amp;quot;&amp;gt;Hello world&amp;lt;/div&amp;gt;
  ''' </code>
  ''' </summary>
  

  该写法在所有版本Visual Studio的悬停提示、各类XML文档生成工具中都能正常工作，会完整输出<div class="foo">Hello world</div>原始文本，不会做标签渲染。

• CDATA段包裹（写法更简便）
  如果不想手动做双重转义，可以将需要展示的HTML代码放在XML CDATA段内部，XML解析器会默认将CDATA段中的所有内容识别为纯文本，不会解析任何标签。示例写法：

  ''' <summary>
  ''' <code>
  ''' <![CDATA[<div class="foo">Hello world</div>]]>
  ''' </code>
  ''' </summary>
  

  该方案的缺点是部分旧版本Visual Studio会把CDATA的包裹标记也显示在提示文本中，对兼容性要求高的场景不推荐使用。

注意：不存在可以直接写入HTML就自动原样展示的特殊注释标签，所有需要作为纯文本展示的标记类内容，都需要做转义处理，不要尝试用其他注释标签替代<c>/<code>，其他标签同样会解析内部HTML标记。

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