Come si includono documenti Xml per una libreria di classi in un pacchetto NuGet?

104

Sto creando un pacchetto NuGet per una libreria di classi C # e vorrei includere la documentazione Xml generata con la libreria. Questo è il mio file nuspec:

<?xml version="1.0" encoding="utf-8"?>
<package>
  <metadata>
    <id>MyLibrary</id>
    <version>1.0.0.0</version>
    <authors>John Nelson</authors>
    <language>en-US</language>
    <description>A C# class library</description>
  </metadata>
  <files>
    <file src="..\..\build\MyLibrary.dll" target="lib\Net40" />
    <file src="..\..\build\MyLibrary.xml" target="lib\Net40" />
  </files>
</package>

Quando creo il pacchetto con questo comando :

nuget pack MyLibrary.nuspec

Genera un errore. Se rimuovo la riga:

<file src="..\..\build\MyLibrary.xml" target="lib\Net40" />

NuGet.exe crea correttamente il file nupkg. Posso persino decomprimere il pacchetto e verificare che il contenuto sia corretto. Che cosa sto facendo di sbagliato? Il file xml dovrebbe andare in una directory di destinazione diversa?

c# nuget nuget-package

— John Nelson
fonte

Quale comando usi per creare il pacchetto?

— Colonel Panic

@ColonelPanic ha aggiornato la domanda con comando e collegamento ai documenti.

— John Nelson

Grazie John. Sto impacchettando direttamente un csproj nuget pack library.csproj(non ho un nuspec), ma la correzione funziona allo stesso modo.

— Colonel Panic

99

Il problema era che non ho controllato "Genera documentazione Xml" per la configurazione di build che stavo usando. Quel nuspec è corretto.

inserisci qui la descrizione dell'immagine

— John Nelson
fonte

6

Buono a sapersi. Stavo provando a usare la GUI per creare un pacchetto e stava cercando di farmi spostare il file XML nella cartella dei contenuti invece che in lib. Non mi sembrava giusto, quindi volevo avere una seconda opinione. Sono contento che tu abbia avuto questo post. :-)

— Mike Loux

12

In .NET Core / Standard puoi farlo modificando il file XML del progetto, ad esempio:

<PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
</PropertyGroup>

Questo produrrà la documentazione come file XML accanto all'assembly di output.

EDIT: come nota a margine una volta abilitato GenerateDocumentationFile, probabilmente riceverai molti avvisi sui tuoi metodi pubblici per non aver aggiunto tag di documentazione completi. Se vuoi disabilitare questi avvisi, aggiungi semplicemente PropertyGroup:

<NoWarn>$(NoWarn);1591</NoWarn>

— bytedev
fonte

<GenerateDocumentationFile>si traduce in un <DocumentationFile>già, quindi penso che sia richiesto solo uno di entrambi, vedere: docs.microsoft.com/en-us/dotnet/csharp/codedoc

— Kapé

Specificare <DocumentationFile>te stesso ti consente solo di produrre il file dove vuoi. Se non lo specifichi penso che lo inserisca letteralmente nel percorso che ho fornito sopra.

— bytedev