Come generare documentazione XML e includerla in un pacchetto nuget

Come generare documentazione XML e includerla in un pacchetto nuget

I commenti alla documentazione XML servono a due scopi:

Intellisense mostra i commenti agli sviluppatori usando il tuo codice.
Puoi generare un file di documentazione e includerlo nel pacchetto build e nuget.

In questo articolo mostrerò come generare automaticamente un file di documentazione XML e come includerlo in un pacchetto nuget.

1 – Scrivi i commenti della documentazione XML nel tuo codice

Ho un metodo chiamato MergeInPlace(). Per spiegare cosa sta facendo e mostrare un esempio di come usarlo, ho aggiunto i seguenti commenti alla documentazione 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 ora mostrerà questi commenti nello stesso progetto e in altri progetti che hanno un riferimento non di pacchetto a questo progetto.

Questi commenti hanno questo aspetto in Intellisense:

2 – Genera automaticamente il file di documentazione XML

Inserisci la seguente proprietà nel tuo file .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:questo vale per i progetti .NET Core. Se stai usando .NET Framework, vai in Proprietà del progetto> Compila> e controlla il file di documentazione XML e scatola.

Ora, quando crei il progetto, genererà un file di documentazione XML nella directory di output della build. Questo file avrà lo stesso nome del tuo assembly.

Ad esempio, il mio assembly si chiama DictionaryUtils.dll. Questo ha generato un file di documentazione XML nella directory di output build chiamato DictionaryUtils.xml.

3 – Includere il file di documentazione XML nel pacchetto nuget

Per fare in modo che le persone con un riferimento al pacchetto vedano i tuoi commenti in Intellisense, dovrai generare il file di documentazione XML e includerlo nel pacchetto nuget.

Il modo più semplice per generare un pacchetto nuget consiste nell'aggiungere la proprietà GeneratePackageOnBuild al file con estensione csproj e impostarla su true. Questo equivale a eseguire pacchetto dotnet .

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

Ora, quando crei, creerà un pacchetto nuget e includerà il file di documentazione XML.

Se stai generando un pacchetto nuget e specificando manualmente i file

Se stai utilizzando un altro metodo per generare il pacchetto nuget e stai specificando esplicitamente tutti i file da includere, assicurati di includere il file XML generato automaticamente. Questo avrà lo stesso nome del tuo assembly.

Ad esempio, se stai utilizzando un file nuspec, potrebbe essere simile a questo:

<?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)

Poiché il file di documentazione XML generato automaticamente ha lo stesso nome dell'assembly, puoi utilizzare il token $id$ (che si risolve nel nome dell'assembly).