Cadeia de caracteres XML em um comentário C # resumo

StackOverflow https://stackoverflow.com/questions/607094

  •  03-07-2019
  •  | 
  •  

Pergunta

Estou documentando alguns métodos que eu escrevi em C # que lidam com a análise de tokens. Devido a algumas restrições técnicas em outras áreas do sistema, esses tokens precisa assumir a forma de elementos XML (ou seja, <tokenName />). Eu gostaria de colocar o formato dessas fichas na própria declaração sumária.

No entanto, isso gera um erro:.? XML mal formado - Um nome foi iniciado com um caractere inválido" Existe algum tipo de seqüência de caracteres de escape que posso usar para XML incorporar no meu c comentários # sumárias

Foi útil?

Solução

Use o escape XML padrão. Por exemplo: 

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

Não é super-fácil de digitar ou ler como código, mas IntelliSense não escapa corretamente este e você vê à direita, coisa legível na dica.

Outras dicas

Use uma seção CDATA. Por exemplo: 

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

Este é mais elegante e legível na fonte de codificação de caracteres especiais em referências de entidade quando você tem um pedaço XML maior.

Se o XML que você deseja incorporar em si contém seções CDATA, você precisa usar várias seções CDATA, conforme descrito no outra resposta sobre estouro de pilha ou Wikipedia . Ou você sempre pode usar referências claras entidade como descrito em outras respostas aqui.

Eu uso de escape-seqüências, porque VisualStudios dica não mostrar qualquer coisa que está dentro de um CDATA-seção.

É muito tarde, mas correu para o mesmo problema, usando <![CDATA[]]> irá esconder o comentário em Intellisense.

Substituir ambos < e > era muito trabalho para mim (:) preguiçoso). Eu descobri que apenas substituindo o < com &lt; foi suficiente para a Intellisense porque torna o inválido xml e adequado para o Intellisense para analisar como texto em seu bloco de resumo.

Aqui está um exemplo: 

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

O Intellisense irá mostrar o seguinte: 

Parse the queue process response
<?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>
Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top