Cadena XML en un comentario de resumen de C #

Question

Estoy documentando algunos métodos que escribí en C # que tratan con los tokens de análisis. Debido a algunas restricciones técnicas en otras áreas del sistema, estos tokens deben tomar la forma de elementos XML (es decir, <tokenName />). Me gustaría poner el formato de esos tokens en la declaración de resumen en sí.

Sin embargo, esto arroja un error: XML mal formado: un nombre se inició con un carácter no válido " ;. ¿Hay algún tipo de secuencia de caracteres de escape que pueda usar para incrustar XML en mis comentarios de resumen de C #?

Answer 1

Utilice el escape XML estándar. Por ejemplo:

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

No es súper fácil escribir o leer como código, pero IntelliSense lo desactiva correctamente y ve lo correcto y legible en la información sobre herramientas.

Answer 2

Use una sección CDATA. Por ejemplo:

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

Esto es más elegante y legible en origen que codificar caracteres especiales en referencias de entidad cuando tiene una pieza XML más grande.

Si el XML que desea incrustar contiene secciones CDATA, debe usar varias secciones CDATA como se describe en otra respuesta en Stack Overflow o en Wikipedia . O siempre puede usar referencias de entidad simples como se describe en otras respuestas aquí.

Answer 3

Uso secuencias de escape, porque la información sobre herramientas de VisualStudios no muestra nada que esté dentro de una sección CDATA.

Answer 4

Es muy tarde, pero se encontró con el mismo problema, usar <![CDATA[]]> ocultará el comentario en Intellisense.

Reemplazar tanto < como > fue mucho trabajo para mí (perezoso :)). Descubrí que el simple reemplazo de < con <=> era suficiente para Intellisense porque invalida el xml y es adecuado para que Intellisense analice como texto en su bloque de resumen.

Aquí hay un ejemplo:

/// <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>

El Intellisense mostrará esto:

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