Este artigo foi traduzido por máquina.

table.one { table-layout:fixed; width : 900px; } table.two { table-layout:fixed;width:600px; margin-bottom: 10px; } .tdwidth{ width:100px; }

Instintos básicos

Documentação de seu código com comentários XML

Lisa Feigenbaum

Este artigo parcialmente se baseia em uma versão de pré-lançamento do Visual Studio. Todas as informações estão sujeitas a alterações.

Conteúdo

Noções básicas de comentário XML
Personalizando os comentários XML
Gerar o arquivo de documentação XML
Aprimorando o Visual Studio com comentários XML
As vantagens de comentários outra pessoa do código
Truques do .NET Framework
Gerando documentação Nicer
Comentários XML no Visual Studio 2010

Procurando uma maneira fácil, porém eficaz documentar o seu código? Comentários XML fornecem uma solução excelente. Comentários XML para o Visual Basic primeiro foram introduzidos no Visual Studio 2005. Elas podem ser usadas para criar um arquivo de documentação para o projeto e fornecem uma experiência de ambiente de desenvolvimento rico para você, seus colegas de equipe ou outras pessoas usando seu código.

Neste artigo, VOU apresentar a você os comentários XML e explicar como usá-los. Irá explorar maneiras em que os comentários XML podem ser usados para personalizar o ambiente de codificação e criar arquivos de documentação de comentários de discussão no seu código. Também mostrarei alguns recursos do Visual Studio futuros que irão criar uma experiência ainda melhor para trabalhar com os comentários XML em seu código.

Noções básicas de comentário XML

Comentários XML podem ser usados para documentar quase todas as definições, exceto os espaços para nome. Isso inclui tipos (classe, módulo, interface, estrutura, enum, delegar), campos (Dim), propriedades (propriedade), eventos (Event) e métodos (Sub, Function, declare, operadores).

Comentários XML são inserido embutido, diretamente no seu código fonte. Isso torna mais fácil mantê-los atualizados como o código evolui. Para inserir um comentário XML, digite três sinais de aspas simples (' ") imediatamente acima a definição, como este:

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Como alternativa, você também pode digitar ' "no início da definição de linha e pressione ENTER. O Visual Studio irá inserir um esqueleto do comentário XML para que você preencha.

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

O objetivo de neste artigo, usei uma função simples com um parâmetro para demonstrar o recurso de comentários XML. O esqueleto XML varia de acordo com a definição. Por exemplo, o esqueleto XML para uma função inclui um elemento retorna, enquanto o esqueleto para um sub não. O número de marcas param para métodos também variará com base no número de parâmetros.

Observe que embora Visual Studio irá inserir o esqueleto XML apropriado para a definição e fornecerá alguns avisos se o comentário ficar fora de sincronização, ele não automaticamente corrigirá o comentário para você. Portanto, não deixe de atualizar o comentário que você alterar a definição.

Depois que o esqueleto XML seja inserido, você pode percorrer os conteúdo wells para inserir seus comentários. O Visual Studio colore o conteúdo XML distintamente das marcas. Você também pode excluir elementos se você não precisar delas, como o elemento de comentários.

Finalmente, você pode adicionar elementos que não estavam no esqueleto XML original. Quando você inicia a digitação de um colchete angular esquerdo (<), uma lista de marcas comuns será exibido em um menu pop-up IntelliSense conforme mostrado na a Figura 1 .

Figura 1 XML comentário no IntelliSense

Você pode adicionar qualquer XML válido para o comentário XML. Uma lista de marcas usadas com freqüência pode ser encontrada no artigo"Recomendado marcas XML para Documentation Comments (Visual Basic)." Se o comentário demorar muito espaço, você pode recolhê-lo ao seu uso resumo o +/-controles no lado esquerdo do editor de códigos, como mostrado na A Figura 2 .

A Figura 2 recolhida comentário XML

Personalizando os comentários XML

No exemplo anterior, eu fiz várias alterações para o esqueleto XML original. Desenvolvedores trabalhando em um ambiente empresarial talvez precise alterar os comentários XML padrão para corresponder às suas diretrizes corporativas específicas. Para ajudar nesses cenários, Visual Basic fornece uma maneira para personalizar o esqueleto XML padrão.

Primeiro, crie um novo arquivo XML chamado VBXMLDoc.xml que inclui seus modelos de comentário do padrão. Um arquivo de exemplo está incluído no download de código deste artigo. Salve VBXMLDoc.xml no local apropriado com base na sua versão do Windows e Visual Studio, conforme mostrado na Figura 3 . <user>Em cada caso, substitua <usuário> no caminho de seu próprio nome de usuário.

O Visual Studio tem padrões internas para os esqueletos XML que obter inseridos, mas quando VBXMLDoc.xml estiver presente durante a inicialização, Visual Studio usa as definições XML partir desse arquivo em vez disso. A versão do VBXMLDoc.xml fornecido no download de código contém as marcas padrão que caso contrário, devem ser inseridas pelo Visual Studio. Para alterar os padrões, localizar o tipo de elemento de código que você está interessado e editar os elementos XML no arquivo.

Por exemplo, vamos alterar o esqueleto XML que é inserido para função. Figura 4 mostra as entradas personalizadas e padrão para uma função. Filhos do elemento de modelo representam os elementos XML que serão inseridos no esqueleto de comentário XML. Filhos do elemento CompletionList representam as sugestões que aparecerão no IntelliSense ao digitar um colchete angular esquerdo (<) acima de uma função.

Figura 4 marcas XML para função

O padrão XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

XML personalizado

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

Como você pode ver na segunda parte da Figura 4 , eu fiz algumas personalizações simples. Em primeiro lugar, removi o elemento de comentários do esqueleto de padrão e o IntelliSense. Além disso, adicionei um elemento author para o esqueleto de padrão e o IntelliSense e adicionei um elemento de histórico a IntelliSense.

Neste ponto você precisará feche e reabra o Visual Studio para as alterações em VBXMLDoc.xml para obter retirados. Após a reinicialização, os comentários XML automaticamente inseridos acima função incluirá um elemento author em vez de comentários:

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Embora seja possível adicionar elementos XML para o modelo, não é possível adicionar valores de XML. Portanto, você pode fazer a inserção IDE <author> </author> por padrão, mas não é possível para torná-lo inserir <author> Microsoft Corporation </author>.

Gerar o arquivo de documentação XML

O compilador do Visual Basic gera um documento XML para o assembly com todos os comentários XML definidos no código. O compilador também resolverá símbolos usados no cref, permissão, e atributos de nome, bem como referências de arquivo em incluem elementos.

O arquivo gerado não mostra seus membros comentados hierarquicamente. Em vez disso, é uma lista plana. Ele inclui uma seqüência de identificação exclusiva para cada definição que permite que os comentários a serem mapeados novamente para suas definições no código (consulte a Figura 5 ). Nesse caso, a seqüência de caracteres é M:RegLib.Helpers.RegKeyExists(System.String). M significa método RegLib.Helpers Especifica o caminho, RegKeyExists é o nome do método e System.String o tipo de parâmetro.

A Figura 5 gerados trecho do documento XML

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
  <summary>Determines whether a specific registry key exists.</summary>
  <param name="regKey">Name or path of the registry key.</param>
  <returns>True if the registry key exists; otherwise, False.</returns>
  <author>Microsoft Corporation</author>
</member>
...
</members>
</doc>

Você pode gerar o arquivo de documentação XML usando o compilador de linha de comando ou pelo Visual Studio interface. Se você está compilando com o compilador de linha de comando, use opções /doc ou doc +. Que irá gerar um arquivo XML com o mesmo nome e no mesmo caminho do assembly. Para especificar um nome de arquivo diferente, use /doc:file.

Se você estiver usando a interface do Visual Studio, há uma configuração que controla se o arquivo de documentação XML é gerado. Para defini-lo, clique duas vezes meu projeto no Solution Explorer para abrir o Project Designer. Navegue até a guia Compile. Localizar " gerar XML arquivo de documentação " na parte inferior da janela e certifique-se de que ele será verificado. Por padrão essa configuração está ativado. Ele gera um arquivo XML usando o mesmo nome e caminho do assembly.

Meu exemplo é um projeto de biblioteca de classe chamado RegLib, portanto o assembly e o arquivo de documentação XML será RegLib.dll e RegLib.xml, respectivamente. O caminho em que elas serão criadas está listado na caixa de texto "caminho de saída de compilação". Deve haver uma compilação explícita para esses arquivos a ser produzido.

A Microsoft usa os comentários XML para gerar a documentação para todos os assemblies do Microsoft .NET Framework. A documentação XML arquivos são colocados ao lado das DLLs eles documentar, e eles corresponderem em nome.

Aprimorando o Visual Studio com comentários XML

Muitos recursos do Visual Studio usam comentários XML para fornecer uma experiência melhor para trabalhar com os membros. Porque o compilador do Visual Basic sempre está sendo executado no plano de fundo, o Visual Studio pode consumir comentários XML conforme eles são criados, sem a necessidade de uma compilação explícita.

O lugar mais predominante onde os comentários XML são usados é IntelliSense. O conteúdo de resumo de comentário XML aparece na dica de ferramenta. Como o método é usado, o IntelliSense também exibe o conteúdo do parâmetro no que é chamado uma dica de ferramenta de ajuda do parâmetro (veja a Figura 6 ).

A Figura 6 parâmetro ajuda a dica de ferramenta com o comentário XML

Explorando a membros no Pesquisador de objetos é uma experiência mais aprimorada com comentários XML. Pesquisador de objetos exibe resumo, parâmetro, retorno, comentários, typeparam e comentários de exceção quando eles existem (veja a Figura 7 ). O Class Designer, modo de exibição de classe e testes de objeto também usar comentários XML quando eles estiverem disponíveis.

A Figura 7 Pesquisador de objetos com comentários XML

As vantagens de comentários outra pessoa do código

Anteriormente, demonstrei como personalizar a experiência Visual Studio para uma função adicionando comentários XML à sua definição. Para membros definidos em assemblies referenciados, no entanto, ele não é prático seguem o mesmo processo uma vez que, necessariamente, você não tenha acesso para a fonte. Felizmente, há um processo diferente (também envolvendo os comentários XML) que você pode usar para membros referenciados!

Há uma diferença de chave. Para membros na solução atual, recursos do Visual Studio trabalhe em uma representação em memória dos comentários XML com base na fonte de. Nesse caso, o arquivo de documentação XML é simplesmente uma saída e não precisa sequer ser gerado para os recursos do Visual Studio para trabalhar. Por outro lado, do caso de assemblies referenciados, os arquivos de documentação XML são lidas como entradas e influenciam o comportamento dentro do ambiente de codificação.

Vamos examinar um exemplo. VOU criar um novo projeto e fazer referência do assembly que criei anterior (RegLib.dll). O arquivo de documentação XML gerado (RegLib.xml) deve ser colocado ao lado do assembly e deve ter o mesmo nome. Se acessar o método RegKeyExists do projeto atual, ele será exibido no IntelliSense. No entanto, pode alterar sua aparência.

EU abrir RegLib.xml e alterar o conteúdo resumo "determina se a chave do Registro existe." A atualização ocorre imediatamente e, na próxima vez que acessar o membro do IntelliSense, vejo o novo texto na dica de ferramenta (consulte a A Figura 8 ).

A Figura 8 dica de ferramenta do IntelliSense

Truques do .NET Framework

O .NET Framework é outro exemplo de assemblies que fazem referência a de seus projetos. Considere Microsoft.VisualBasic.dll, cujo arquivo de documentação XML pode ser encontrado aqui:

C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml 

Abrir o arquivo XML e examinar os comentários XML. Há alguns elementos XML interessantes que você encontrará lá. Por exemplo, Filterpriority determina como um membro é exibido no Visual Basic IntelliSense. Um valor de 1 indica que ela deverá aparecer na guia Common, 2 significa deve aparecer na guia All e 3 significa que ele deve ser ocultado do IntelliSense completamente. Filterpriority esse membro é definido como 1, para que ele será exibido em comuns. Facilmente você pode alterar o valor de filterpriority para 2 e salvar o arquivo XML então o membro aparece na guia todos os.

Observe que, antes de editar os arquivos de documentação XML do .NET Framework, é uma boa idéia para fazer uma cópia antecipadamente. Também será necessário abrir os arquivos em um aplicativo que tem privilégios elevados. Visual Studio é uma boa opção desde que ele preservará o formato de arquivo.

Você pode usar a metodologia descrita nesta seção para influenciar membros em um assembly referenciado, desde que você tem acesso para seu arquivo de documentação XML ou você pode criar um se ele não existir. Para influenciar a filterpriority de um membro definido na montagem atual, use o atributo System.ComponentModel.EditorBrowsable.

Outro elemento interessante é PermissionSet. Esse elemento Especifica sob que condições o membro é acessível. O conteúdo do elemento se refere ao tipo System.Security.Permissions.SecurityPermission.

Vamos inferior nosso nível de permissão atual e ver qual efeito isso tem no nosso acesso FileWidth. Crie um console ou aplicativo do Windows. Clique no meu programa no Solution Explorer para abrir o Project Designer. Selecione a guia Segurança e verificar "Habilitar configurações de segurança de ClickOnce" e "Este é um aplicativo parcialmente confiável."

Neste momento as permissões necessárias não estão disponíveis, por isso, FileWidth e membros vizinhos ficam esmaecidas e inacessível do IntelliSense. Esse recurso do Visual Basic é chamado de IntelliSense in Zone. A dica de ferramenta indica o tipo de permissão é necessária para usar o membro.

Você pode adicionar elementos de PermissionSet a arquivos de documentação XML membro e especificar a permissão apropriada.

Gerando documentação Nicer

O XML gerado pelo compilador do Visual Basic é legível, mas não a mais amigável. Várias ferramentas foram criadas para criar nicer documentação de aparência profissional que é mais fácil de navegar.

A primeira ferramenta é chamada Sandcastle, desenvolvido pela Microsoft. Depois de instalar Sandcastle, coletar os assemblies que você irá ser documentando, suas dependências e seus arquivos de documentação XML. Copie todos os os materiais para a pasta de instalação vSandcastle (normalmente c:\Arquivos Files\Sandcastle\Examples\sandcastle).

Abra um prompt de comando elevado e navegue até o mesmo diretório e execute este comando:

build_Sandcastle.bat prototype <your assembly name without the file extension>

Diretórios e arquivos serão gerados por esta operação. Abra o diretório .chm e abra o arquivo .chm dentro. Ele deve ser semelhante a ajuda na Figura 9 .

A Figura 9 Sandcastle .chm saída

A ferramenta oferece um número de outros formatos de saída diferente. chm. Para obter mais informações e mais anúncios em Sandcastle, observe o blog em blogs.msdn.com/Sandcastle.

NDoc é outra ferramenta popular, que você poderá considerar o uso, ou você pode usar os poderosos recursos XML no Visual Basic 9 para escrever sua própria ferramenta personalizada!

Comentários XML no Visual Studio 2010

Procurando frente, existem novas possibilidades para a forma que você pode interagir com os comentários XML no código. O editor do Visual Studio 2010 for reconfigurado usando o Windows Presentation Foundation (WPF) e permite visualizações ricos. O editor de atualizações também envolvidos mover para um novo sistema de componente, o Managed extensibilidade Framework (MEF), que torna muito mais fácil de registrar o add-ins com o Visual Studio. a Figura 10 mostra um exemplo de um visualizador de comentário XML que foi criado na parte superior do novo editor e modelo de componente.

A Figura 10 Visualizar de comentário XML no Visual Studio 2010

Clicar no botão nas opções do canto superior direito a exibição entre o controle do WPF e o XML original. O controle WPF certamente fornece uma quantidade visão mais clara. Ele também aproveita recursos do WPF, como gradientes e bordas arredondadas. WPF possibilita a incluir imagens ou vídeos, muito! Certamente, será uma área rich para suplementos de terceiros aproveitar na versão Visual Studio 2010.

Envie suas dúvidas e comentários para instinct@microsoft.com.

ela Feigenbaum é gerente de programa do Microsoft da comunidade do Visual Basic. Ela tem sido um membro da equipe de Visual Basic de desde 2004. Antes de sua função atual, Lisa era o gerente de programa para o Editor do Visual Basic e o depurador, trabalhando em recursos como o IntelliSense, edição e a continuar e trechos de código. Você pode encontrar Lisa em vários dos EUA e conferências internacionais e grupos de usuários, assista seu webcasts do Channel 9 ou Leia suas postagens no blog da equipe VB no https://blogs.msdn.com/vbteam.