Este artículo proviene de un motor de traducción automática.

table.one { table-layout:fixed; width: 610px; font-size: 14px; color: #333; margin-bottom: 5px; } table.two { table-layout:fixed; width: 610px; border-top: 3px; border-top-color: #0569b5; border-top-style:solid; margin-bottom: 10px; } .tdwidth{ width:60px; } tr.heading td { font-size: 14px; padding : 7px; color: #00947d; vertical-align:top; background-color: #cbe1f2; } tr.fig { background-color:white; color: 00599d; padding: 7px; font-weight:bold; vertical-align:top; } tr.dark td { background-color: #e2f4fd; color: black; padding: 7px; vertical-align:top; } tr.lite td { background-color: #fffcd6; color: black; padding: 7px; vertical-align:top; } tr.small td { background-color: #dde8ee; color: black; padding: 5px 10px 5px 10px; vertical-align:top; font-size: 10px; }

Instintos básicos

Documentar el código con comentarios XML

Lisa Feigenbaum

Parcialmente este artículo se basa en una versión preliminar de Visual Studio.Toda la información está sujeta a cambios.

Contenido

Aspectos básicos de comentario XML
Personalizar comentarios XML
Generar el archivo de documentación XML
Mejora de Visual Studio con comentarios XML
Las ventajas de comentarios O alguien de código
Trucos de .NET Framework
Generar documentación mejor
Comentarios XML en 2010 de Visual Studio

¿Busca una forma sencilla pero eficaz para documentar el código?Los comentarios XML ofrecen una solución excelente.En primer lugar se introdujeron los comentarios XML de Visual Basic en Visual Studio 2005.Pueden utilizarse para crear un archivo de documentación para el proyecto y proporcionar una experiencia de entorno de desarrollo variado para usted mismo, sus compañeros de equipo y otros usuarios mediante el código.

En este artículo, se presentar comentarios XML y explique cómo usarlos.Examinará formas en la que se pueden utilizar comentarios XML para personalizar su entorno de programación y para crear archivos de documentación de los comentarios en el código.También mostraré algunas características de Visual Studio futuras que creará una experiencia incluso mejor para trabajar con comentarios XML en el código.

Aspectos básicos de comentario XML

Comentarios pueden utilizarse para documentar casi todas las definiciones de excepto los espacios de nombres.Esto incluye tipos (clase, módulo, enumeración, estructura, interfaz, delegado), los campos (Dim), propiedades (propiedad), eventos (evento) y métodos (Sub, Function, declare, operador).

Los comentarios XML están en línea insertado, directamente en el código fuente.Esto facilita mantenerlos actualizados a medida que evolucione el código.Para insertar un comentario XML, escriba tres marcas de comillas único (" ") justo encima de la definición, como éste:

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

Como alternativa, también puede escribir " "al principio de la línea de definición y presione ENTRAR. Visual Studio insertará un esquema del comentario XML para poder rellenar.

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

Con el propósito de este artículo, usa una función sencilla, con un parámetro para demostrar la característica de comentarios XML.El formato XML varía según la definición.Por ejemplo, el formato XML para una función incluye un elemento devuelve, mientras que el esqueleto de un procedimiento Sub no.El número de etiquetas de param para los métodos también variará según el número de parámetros.

Tenga en cuenta que aunque Visual Studio se insertará el esqueleto XML adecuado para la definición y proporcionará algunas advertencias si el comentario Obtiene fuera de sincronización, no corregirá automáticamente el comentario para usted.Por lo tanto, asegúrese de actualizar el comentario, si se realizan cambios en la definición.

Una vez que se inserta el esquema XML, puede recorrer el tabulador los contenido wells para insertar sus comentarios.Visual Studio colorizes el contenido XML forma distinta de las etiquetas.También puede eliminar los elementos si no necesita, como el elemento de comentarios.

Finalmente, puede agregar elementos que no estén en el esquema XML original.Cuando empiece a escribir un corchete angular izquierdo (<), aparecerá una lista de etiquetas comunes en un menú emergente IntelliSense tal como se muestra en la figura 1 .

Figura 1 el comentario XML en IntelliSense

Puede agregar cualquier XML válido al comentario XML.Puede encontrar una lista de etiquetas utilizadas en el artículo"Recomendadas etiquetas XML para comentarios de documentación (Visual Basic)." Si el comentario tarda demasiado espacio, se puede contraer al su uso resumen la +/-controles en la parte izquierda del editor de código, tal como se muestra enLa figura 2 .

La Figura 2 colapsado comentario XML

Personalizar comentarios XML

En el ejemplo anterior, había realizado una serie de cambios en el esquema XML original.Programadores trabajan en un entorno empresarial es posible que necesite cambiar los comentarios XML predeterminado para que coincida con sus las directrices corporativas determinadas.Para ayudarle con estos escenarios, Visual Basic proporciona una forma de personalizar el formato de XML predeterminado.

En primer lugar, crear un archivo XML nuevo, llamado VBXMLDoc.xml que incluye las plantillas de comentario predeterminado.Un archivo de ejemplo se incluye en la descarga de código de este artículo.Guardar VBXMLDoc.xml en la ubicación apropiada basándose en la versión de Windows y Visual Studio, tal como se muestra en la figura 3 .<user>En cada caso, reemplace <usuario> en la ruta de acceso su propio nombre de usuario.

Visual Studio tiene integrados valores predeterminados para las que obtener insertar esqueletos XML, pero cuando VBXMLDoc.xml está presente en el inicio, Visual Studio utiliza las definiciones XML de ese archivo en su lugar.La versión de VBXMLDoc.xml proporcionada en la descarga de código contiene las etiquetas predeterminadas que en caso contrario, se podrían insertar por Visual Studio.Para cambiar los valores predeterminados, encuentra el tipo de elemento de código que le interesan y modifique los elementos XML en el archivo.

Por ejemplo, vamos a cambiar el formato XML que obtiene insertado para la función.Figura 4 muestra el valor predeterminado y entradas personalizadas para una función.Elementos secundarios del elemento de plantilla representan los elementos XML que se insertará en el formato de comentario XML.Elementos secundarios del elemento CompletionList representan las sugerencias que aparecerán en IntelliSense al escribir un corchete angular izquierdo (<) por encima de una función.

Figura 4 etiquetas XML para (función)

Predeterminado 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 puede ver en la segunda parte de la figura 4 , había realizado personalizaciones simples unas. En primer lugar, quita el elemento de comentarios del formato predeterminado y IntelliSense. Además, agrega un elemento author al tanto el formato predeterminado y IntelliSense y agrega un elemento de historial a IntelliSense.

En este momento deberá cerrar y volver a abrir Visual Studio para los cambios en VBXMLDoc.xml para obtener recoge. Después de reiniciar el equipo, los comentarios XML automáticamente inserta encima (función) incluirá un elemento author en lugar de comentarios:

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

Aunque es posible agregar elementos XML a la plantilla, no es posible agregar valores XML. Por lo tanto, puede realizar la inserción IDE <author> </author> de forma predeterminada, pero no es posible que inserta <author> Microsoft Corporation </author>.

Generar el archivo de documentación XML

El compilador de Visual Basic genera un documento XML para el ensamblado con todos los comentarios XML definidos en el código. El compilador también resolverá símbolos utilizados en cref, permiso, y atributos de nombre, así como las referencias del archivo de incluyen los elementos.

El archivo generado no muestra los miembros comentados jerárquicamente. En su lugar, es una lista plana. Incluye una cadena de IDENTIFICADOR única para cada definición que permite a los comentarios asignar a sus definiciones en el código (consulte la figura 5 ). En este caso, la cadena es M:RegLib.Helpers.RegKeyExists(System.String). Es método M, RegLib.Helpers especifica la ruta de acceso, RegKeyExists es el nombre del método y System.String el tipo de parámetro.

La figura 5 genera el extracto de documentos 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>

Puede generar el archivo de documentación de XML utilizando el compilador de línea de comandos o interfaz a través de la Visual Studio.Si se compila con el compilador de línea de comandos, utilizar las opciones /doc o doc +.Que generar un archivo XML con el mismo nombre y en la misma ruta como el ensamblado.Para especificar un nombre de archivo diferente, utilice /doc:file.

Si estás utilizando la interfaz de Visual Studio, hay un valor que controla si se genera el archivo de documentación XML.Para establecer, haga doble clic en Mi proyecto en el Explorador de soluciones para abrir el Diseñador de proyectos.Vaya a la ficha compilar.Buscar " generar XML archivo de documentación " al final de la ventana y asegúrese de que se comprueba.De forma predeterminada esta opción es en.Genera un archivo XML con el mismo nombre y ruta de acceso que el ensamblado.

Mi ejemplo es un proyecto de biblioteca de clase denominado RegLib, por lo que el ensamblado y el archivo de documentación XML será RegLib.dll y RegLib.xml, respectivamente.La ruta de acceso donde se van a crear aparece en el cuadro "Ruta de salida de generación".Debe haber una generación explícita de estos archivos para que se van a producir.

Microsoft utiliza los comentarios XML para generar documentación para todos los ensamblados de Microsoft .NET Framework.La documentación de XML se colocan archivos junto a los archivos DLL Documente y coinciden en nombre.

Mejora de Visual Studio con comentarios XML

Muchas características de Visual Studio utilizan comentarios para proporcionar un mejor rendimiento para trabajar con miembros.Porque el compilador de Visual Basic siempre está ejecutando en segundo plano, Visual Studio puede consumir los comentarios XML como el se escriben, sin necesidad de una compilación explícito.

El lugar más predominante donde se utilizan los comentarios XML es IntelliSense.El contenido de resumen del comentario XML aparece en la información sobre herramientas.Como se utiliza el método, IntelliSense también muestra el contenido de param en lo que se denomina una información sobre herramientas de Ayuda parámetro (consulte la figura 6 ).

Figura 6 parámetro Ayuda información sobre herramientas con comentarios XML

Explorar los miembros en el Examinador de objetos es una experiencia muy mejorada con comentarios.Examinador de objetos muestra resumen, param, devolución, comentarios, typeparam y los comentarios de la excepción cuando que existen (consulte la figura 7 ).El diseñador de clases, Vista de clases y herramienta de prueba de objetos también utilizan comentarios cuando estén disponibles.

La figura 7 Examinador de objetos con comentarios XML

Las ventajas de comentarios O alguien de código

Anteriormente demuestra cómo personalizar la experiencia de Visual Studio para una función agregando comentarios XML a su definición.Para los miembros definidos en ensamblados de referencia, sin embargo, no resulta práctico seguir el mismo proceso dado que necesariamente no tiene acceso al origen.Afortunadamente, hay un proceso diferente (que también implica comentarios XML) que puede utilizar para los miembros que se hace referencia.

Hay una diferencia clave.Para los miembros de la solución actual, características de Visual Studio funcionan con una representación en memoria de los comentarios XML basado en el origen.En ese caso, el archivo de documentación XML es puramente un resultado y aún no es necesario para que se genere para que las características de Visual Studio para trabajar.Por otro lado, en el caso de los ensamblados a los que se hace referencia, los archivos de documentación XML se leen como entradas y influyen en comportamiento en el entorno de programación.

Veamos un ejemplo.Creará un nuevo proyecto y hacer referencia el ensamblado que creé anteriores (RegLib.dll).El archivo de documentación XML generado (RegLib.xml) se debe colocar junto al ensamblado y debe tener el mismo nombre.Si obtiene acceso al método RegKeyExists desde el proyecto actual, ésta aparecerá en IntelliSense.Sin embargo, puede modificar su aspecto.

ES abrir RegLib.xml y cambiar el contenido de resumen para "determina si la clave del registro existe". La actualización se produce inmediatamente, y la próxima vez que obtener acceso al miembro en IntelliSense, aparece el nuevo texto en la información sobre herramientas (consulte laFigura 8).

Figura 8 IntelliSense información sobre herramientas

Trucos de .NET Framework

.NET Framework es otro ejemplo de los ensamblados que hace referencia de los proyectos.Tenga en cuenta Microsoft.VisualBasic.dll, cuyo archivo de documentación XML encontrará aquí:

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

Abrir el archivo XML y examinar los comentarios XML.Hay algunos elementos XML interesantes que encontrará allí.Por ejemplo, Filterpriority determina el modo en que un miembro aparece en IntelliSense de Visual Basic.Un valor 1 significa que debe aparecer en la ficha común, 2 significa debe aparecer en la ficha todas y 3 significa que ésta debe estar oculta de IntelliSense por completo.Filterpriority este miembro se establece en 1, por lo que se aparecen en común.Puede cambiar el valor filterpriority a 2 fácilmente y guardar el archivo XML para el miembro aparece en la ficha todas.

Tenga en cuenta que, antes de editar los archivos de documentación XML de .NET Framework, es una buena idea para realizar una copia con antelación.También tendrá que abrir los archivos en una aplicación que tiene privilegios elevados.Visual Studio es una buena opción puesto que conservará el formato de archivo.

Puede utilizar la metodología descrita en esta sección para influir en los miembros de un ensamblado al que se hace referencia, siempre y cuando tiene acceso a su archivo de documentación XML o puede crear una si no existe.Para influir en el filterpriority de un miembro definido en el ensamblado actual, utilice el atributo System.ComponentModel.EditorBrowsable.

Otro elemento interesante es PermissionSet.Este elemento especifica en qué circunstancias el miembro es accesible.El contenido del elemento hace referencia al tipo System.Security.Permissions.SecurityPermission.

Vamos a reducir el nivel de permisos actual y ver qué efecto tiene de nuestro acceso a FileWidth.Crear una consola o una aplicación de Windows.Haga clic en mi programa en el Explorador de soluciones para abrir el Diseñador de proyectos.Seleccione la ficha seguridad y, a continuación, comprobar "Habilitar configuración de seguridad de ClickOnce" y "Esto es una aplicación de confianza parcial."

En este momento los permisos necesarios no están disponibles, por lo que FileWidth y los miembros de vecinos se convierten en atenuados y inaccesibles en IntelliSense.Esta función de Visual Basic se denomina IntelliSense de zona.La información sobre herramientas indica qué tipo de permiso es necesario utilizar el miembro.

Puede agregar elementos PermissionSet a archivos de documentación XML miembro y especificar los permisos adecuados.

Generar documentación mejor

El código XML generado por el compilador de Visual Basic es legible, pero no la más descriptivo.Una serie de herramientas se ha creado para crear mejor aspecto documentación que sea más fácil de explorar.

La primera herramienta se denominaSandcastle, desarrollado por Microsoft.Después de instalar Sandcastle, recopilar los ensamblados que se pueden documentar, sus dependencias y sus archivos de documentación XML.Copiar todos los materiales a la carpeta de instalación vSandcastle (normalmente c:\Archivos Files\Sandcastle\Examples\sandcastle).

Abra un símbolo del sistema con privilegios elevados y desplácese al mismo directorio, a continuación, ejecute este comando:

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

Directorios y archivos se generará mediante esta operación.Abra el directorio .chm y, a continuación, abra el archivo .chm dentro.Debe parecerse a la Ayuda en la figura 9 .

Figura 9 Sandcastle .chm resultados

La herramienta ofrece un número de otros formatos de salida distinto,. chm.Para obtener más información y más anuncios en Sandcastle, por favor, ver el blog enblogs.msdn.com/Sandcastle.

NDoces otra herramienta popular que se puede utilizar, o puede utilizar las eficaces características XML en 9 de Visual Basic para escribir su propia herramienta personalizada.

Comentarios XML en 2010 de Visual Studio

Buscar hacia delante, existen nuevas posibilidades para la forma en que puede interactuar con comentarios XML en código.El editor de 2010 de Visual Studio es volver a escribir con Windows Presentation Foundation (WPF) y permite que las visualizaciones enriquecidas.El editor actualiza también implica mover a un nuevo sistema de componente, el administrado extensibilidad Framework (MEF), lo que facilita mucho registrar los complementos con Visual Studio.Figura 10 muestra un ejemplo de un visor de comentario XML que se basa en el editor de nuevo y modelo de componente.

Figura 10 Visor de comentario XML de 2010 de Visual Studio

Hace clic en el botón de en los modificadores de la esquina superior derecha la presentación entre el control WPF y el XML original.El control WPF ciertamente, proporciona una cantidad vista más clara.También aprovecha WPF capacidades como degradados y bordes redondeados.WPF permite incluir imágenes o vídeos, también!Ciertamente, éste será un área enriquecido para complementos de terceros aprovechar las ventajas de en el lanzamiento de 2010 de Visual Studio.

Envíe sus preguntas y comentarios ainstinct@microsoft.com.

Juan Feigenbaum es director de programa de Microsoft de la comunidad de Visual Basic.Ha sido un miembro del grupo de Visual Basic desde de 2004.Antes de su función actual, Juan era el administrador de programas para el Editor de Visual Basic y el depurador, trabajar en las características como IntelliSense, de edición y de seguir y los fragmentos de código.Puede encontrar Juan en distintos Estados Unidosy conferencias internacionales y grupos de usuarios, vea sus webcasts de Channel 9, o leer sus entradas en el blog del equipo de Visual Basic enhttps://blogs.msdn.com/vbteam .