Los comentarios de la documentación XML tienen dos propósitos:
- Intellisense muestra los comentarios a los desarrolladores usando su código.
- Puede generar un archivo de documentación e incluirlo en su paquete de compilación y nuget.
En este artículo, mostraré cómo generar automáticamente un archivo de documentación XML y cómo incluirlo en un paquete nuget.
1 – Escribe los comentarios de la documentación XML en tu código
Tengo un método llamado MergeInPlace(). Para explicar lo que está haciendo y mostrar un ejemplo de cómo usarlo, agregué los siguientes comentarios de documentación XML.
/// <summary>
/// Merges two dictionaries together.
///
/// <para>
/// Example usage:
/// <c>leftDict.MergeInPlace(rightDict)</c>
/// </para>
///
/// <para>
/// If a key exists in both the left and the right dictionary,
/// it'll take the left value.
/// </para>
/// </summary>
/// <typeparam name="Key"></typeparam>
/// <typeparam name="Value"></typeparam>
/// <param name="left">Dictionary to merge into</param>
/// <param name="right">Merges items from this dictionary into left dictionary</param>
/// <returns>Reference to original left dictionary.</returns>
public static Dictionary<Key, Value> MergeInPlace<Key, Value>(this Dictionary<Key, Value> left,
Dictionary<Key, Value> right)
Code language: C# (cs)Intellisense ahora mostrará estos comentarios en el mismo proyecto y en otros proyectos que no tengan una referencia de paquete a este proyecto.
Estos comentarios se ven así en Intellisense:
2 – Genera automáticamente el archivo de documentación XML
Ponga la siguiente propiedad en su archivo .csproj:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
</Project>
Code language: HTML, XML (xml)Nota:Esto se aplica a los proyectos de .NET Core. Si usa .NET Framework, vaya a Propiedades del proyecto> Generar> y verifique el archivo de documentación XML e caja.
Ahora, cuando construya el proyecto, generará un archivo de documentación XML en el directorio de salida de la compilación. Este archivo tendrá el mismo nombre que su ensamblado.
Por ejemplo, mi ensamblado se llama DictionaryUtils.dll. Esto generó un archivo de documentación XML en el directorio de salida de compilación llamado DictionaryUtils.xml.
3:incluya el archivo de documentación XML en el paquete nuget
Para que las personas con una referencia de paquete vean sus comentarios en Intellisense, deberá generar el archivo de documentación XML e incluirlo en el paquete nuget.
La forma más sencilla de generar un paquete nuget es agregar la propiedad GeneratePackageOnBuild a su archivo .csproj y establecerlo en verdadero. Esto es equivalente a ejecutar dotnet pack .
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
</Project>
Code language: HTML, XML (xml)Ahora, cuando construyas, creará un paquete nuget e incluirá el archivo de documentación XML.
Si está generando un paquete nuget y especificando archivos manualmente
Si está utilizando algún otro método para generar el paquete nuget y está especificando explícitamente todos los archivos para incluir, asegúrese de incluir el archivo XML generado automáticamente. Este tendrá el mismo nombre que su ensamblado.
Por ejemplo, si está utilizando un archivo nuspec, podría verse así:
<?xml version="1.0" encoding="utf-8"?>
<package>
...other info...
<files>
<file src="bin$configuration$$id$.dll" target="lib\netcoreapp3.1" />
<file src="bin$configuration$$id$.xml" target="lib\netcoreapp3.1" />
</files>
</package>
Code language: HTML, XML (xml)Debido a que el archivo de documentación XML generado automáticamente tiene el mismo nombre que el ensamblado, puede usar el token $id$ (que se resuelve en su nombre de ensamblado).