Nuget Pakete

NuGet-Pakete

XML-Dokumentation für Konsumenten

Für Bibliotheken, die als NuGet-Paket veröffentlicht werden, sollten öffentliche APIs mit XML-Dokumentationskommentaren (///) beschrieben sein. Damit diese Kommentare in der IDE der Konsumenten (IntelliSense) sichtbar sind, muss beim Build eine XML-Dokumentationsdatei erzeugt und mit dem Paket ausgeliefert werden.

Aktivierung im Build

In der Repository-Directory.Build.props (Root) ist das global gesetzt:

<GenerateDocumentationFile>true</GenerateDocumentationFile>

Der Compiler erzeugt dabei pro Assembly eine Datei AssemblyName.xml im Build-Output (neben der DLL).

NuGet-Verpackung

Beim dotnet pack nimmt das SDK die XML-Datei in der Regel automatisch in das Paket auf (gleicher Pfad wie die DLL unter lib/<tfm>/). Konsumenten erhalten damit die API-Dokumentation ohne zusätzliche Konfiguration.

Hinweise

Thema	Empfehlung
Fehlende ///-Kommentare	Mit aktivierter XML-Generierung meldet der Compiler Warnungen (z. B. CS1591). Für Bibliotheken sinnvoll; für Tests/Apps oft abschalten.
Tests, Apps, UI	In Unterordnern GenerateDocumentationFile auf false setzen, wenn keine API-Doku ausgeliefert wird (siehe Seite Directory.Build.props).
Symbole	Unabhängig davon: snupkg/PDB für Debugging (z. B. IncludeSymbols in der Root-Props).

Kurzfassung

GenerateDocumentationFile=true → XML beim Build → XML landet im NuGet → IntelliSense beim Paket-Konsumenten.