Stringa XML in un commento di riepilogo C #

Question

Sto documentando alcuni metodi che ho scritto in C # che riguardano l'analisi dei token. A causa di alcuni vincoli tecnici in altre aree del sistema, questi token devono assumere la forma di elementi XML (ovvero <tokenName />). Vorrei inserire il formato di tali token nell'istruzione di riepilogo stessa.

Tuttavia, questo genera un errore: XML mal formato - È stato avviato un nome con un carattere non valido " ;. Esiste una sorta di sequenza di caratteri di escape che posso usare per incorporare XML nei commenti di riepilogo di C #?

Answer 1

Utilizza l'escaping XML standard. Ad esempio:

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

Non è semplicissimo digitare o leggere come codice, ma IntelliSense lo svuota correttamente e nella descrizione del comando viene visualizzata la cosa giusta e leggibile.

Answer 2

Utilizza una sezione CDATA. Ad esempio:

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

Questo è più elegante e leggibile nella fonte rispetto alla codifica di caratteri speciali nei riferimenti alle entità quando hai un pezzo XML più grande.

Se l'XML che si desidera incorporare contiene sezioni CDATA, è necessario utilizzare più sezioni CDATA come descritto in un'altra risposta su Stack Overflow o su Wikipedia . Oppure puoi sempre usare riferimenti di entità semplici come descritto nelle altre risposte qui.

Answer 3

Uso sequenze di escape, perché la descrizione di VisualStudios non visualizza nulla all'interno di una sezione CDATA.

Answer 4

È molto tardi, ma si è verificato lo stesso problema, l'utilizzo di <![CDATA[]]> nasconderà il commento in Intellisense.

Sostituire sia < che > è stato un grande lavoro per me (pigro :)). Ho scoperto che la semplice sostituzione di < con <=> è stata sufficiente per Intellisense perché rende xml non valido e adatto a Intellisense per analizzare come testo nel blocco di riepilogo.

Ecco un esempio:

/// <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 mostrerà questo:

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