<include> (Guía de programación de C#)
<include file='filename' path='tagpath[@name="id"]' />
Parámetros
filename
El nombre del archivo XML que contiene la documentación. El nombre de archivo se puede completar con una ruta de acceso. Agregue filename entre comillas simples (' ').tagpath
Ruta de acceso de las etiquetas de filename que conduce a la etiqueta name. Ponga la ruta de acceso entre comillas simples (' ').name
Especificador de nombre en la etiqueta que precede a los comentarios; name poseerá un id.id
Identificador para la etiqueta que precede a los comentarios. Ponga el id. entre comillas dobles (" ").
Comentarios
La etiqueta <include> permite hacer referencia a comentarios colocados en otro archivo que describen los tipos y miembros del código fuente. Ésta es una alternativa al método habitual de colocar los comentarios de la documentación directamente en el archivo de código fuente. Colocando la documentación en un archivo independiente, puede aplicar el control de código fuente a la documentación independientemente del código fuente. Una persona puede tener el archivo de código fuente desprotegido y alguien más puede tener el archivo de documentación desprotegido.
La etiqueta <include> utiliza la sintaxis XPath de XML. Consulte la documentación de XPath para conocer diversos modos de personalizar el uso de <include>.
Ejemplo
Este ejemplo utiliza varios archivos. El primer archivo, que utiliza <include>, se muestra a continuación:
// compile with: /doc:DocFileName.xml
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
static void Main()
{
}
}
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{
}
}
El segundo archivo, xml_include_tag.doc, contiene los siguientes comentarios de documentación:
<MyDocs>
<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>
<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>
</MyDocs>
Resultado del programa
Se genera el siguiente resultado al compilar las clases Test y Test2 con la siguiente línea de comandos: /doc:DocFileName.xml. En Visual Studio, se especifica que la opción Comentarios de documento XML del recuadro Compilación del Diseñador de proyectos. Cuando el compilador de C# ve la etiqueta <inclue>, buscará comentarios de documentación en xml_include_tag.doc en lugar del archivo de código fuente actual. A continuación, el compilador genera DocFileName.xml, este el archivo que es utilizado por herramientas de documentación como Sandcastle para crear la documentación final.
<?xml version="1.0"?>
<doc>
<assembly>
<name>xml_include_tag</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
The summary for this other type.
</summary>
</member>
</members>
</doc>
Vea también
Referencia
Etiquetas recomendadas para comentarios de documentación (Guía de programación de C#)