¿Cómo se incluyen Xml Docs para una biblioteca de clases en un paquete NuGet?

103

Estoy creando un paquete NuGet para una biblioteca de clases C # y me gustaría incluir la documentación Xml generada con la biblioteca. Este es mi archivo 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>

Cuando construyo el paquete con este comando :

nuget pack MyLibrary.nuspec

Genera un error. Si elimino la línea:

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

NuGet.exe crea correctamente el archivo nupkg. Incluso puedo descomprimir el paquete y verificar que el contenido sea correcto. ¿Qué estoy haciendo mal? ¿Debería el archivo xml ir a un directorio de destino diferente?

John Nelson
fuente
¿Qué comando usas para construir el paquete?
Coronel Panic
@ColonelPanic actualizó la pregunta con comando y enlace a documentos.
John Nelson
Gracias John. Estoy empaquetando un csproj directamente nuget pack library.csproj(no tengo un nuspec), pero la solución funciona igual.
Coronel Panic

Respuestas:

98

El problema fue que no verifiqué "Generar documentación Xml" para la configuración de compilación que estaba usando. Esa nuspec es correcta.

ingrese la descripción de la imagen aquí

John Nelson
fuente
6
Bueno saber. Estaba tratando de usar la GUI para crear un paquete, y estaba tratando de hacerme mover el archivo XML a la carpeta de contenido en lugar de lib. No parecía correcto, así que quería obtener una segunda opinión. Me alegro de que tuvieras esta publicación. :-)
Mike Loux
11

En .NET Core / Standard, puede hacer esto editando el archivo XML del proyecto, por ejemplo:

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

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

Esto generará la documentación como un archivo XML junto a su ensamblado de salida.

EDITAR: Como nota al margen, una vez que lo habilite GenerateDocumentationFile, probablemente recibirá muchas advertencias en sus métodos públicos por no haber agregado etiquetas de documentación completas. Si desea deshabilitar estas advertencias, simplemente agregue PropertyGroup:

<NoWarn>$(NoWarn);1591</NoWarn>
bytedev
fuente
<GenerateDocumentationFile>da como resultado un <DocumentationFile>ya, así que creo que solo se requiere uno de ambos, consulte: docs.microsoft.com/en-us/dotnet/csharp/codedoc
Kapé
Especificarse a <DocumentationFile>sí mismo solo le permite generar el archivo donde quiera. Si no lo especifica, creo que literalmente lo pone en la ruta que he proporcionado anteriormente.
bytedev