Como você inclui Xml Docs para uma biblioteca de classe em um pacote NuGet?

103

Estou criando um pacote NuGet para uma biblioteca de classes C # e gostaria de incluir a documentação Xml gerada com a biblioteca. Este é meu arquivo 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 eu construo o pacote com este comando :

nuget pack MyLibrary.nuspec

Isso gera um erro. Se eu remover a linha:

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

NuGet.exe cria o nupkg com sucesso. Posso até descompactar o pacote e verificar se o conteúdo está correto. O que estou fazendo de errado? O arquivo xml deve ir para um diretório de destino diferente?

John Nelson
fonte
Que comando você usa para construir o pacote?
Coronel Panic
@ColonelPanic atualizou a pergunta com comando e link para documentos.
John Nelson de
Obrigado John. Estou empacotando um csproj diretamente nuget pack library.csproj(não tenho um nuspec), mas a correção funciona da mesma forma.
Coronel Panic de

Respostas:

98

O problema é que eu não marquei "Gerar documentação Xml" para a configuração de compilação que estava usando. Esse nuspec está correto.

insira a descrição da imagem aqui

John Nelson
fonte
6
Bom saber. Eu estava tentando usar a GUI para criar um pacote, e ela estava tentando me fazer mover o arquivo XML para a pasta de conteúdo em vez de lib. Não parecia certo, então eu queria uma segunda opinião. Que bom que você teve esse post. :-)
Mike Loux
11

No .NET Core / Standard, você pode fazer isso editando o arquivo XML do projeto, por exemplo:

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

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

Isso produzirá a documentação como um arquivo XML próximo ao seu conjunto de saída.

EDITAR: Como uma nota lateral, uma vez que você habilite, GenerateDocumentationFilevocê provavelmente receberá muitos avisos sobre seus métodos públicos por não ter adicionado tags de documentação completa. Se você deseja desativar esses avisos, basta adicionar PropertyGroup:

<NoWarn>$(NoWarn);1591</NoWarn>
bytedev
fonte
<GenerateDocumentationFile>resulta em <DocumentationFile>já, então acho que apenas um dos dois é necessário, consulte: docs.microsoft.com/en-us/dotnet/csharp/codedoc
Kapé
Especificar- <DocumentationFile>se apenas permite que você envie o arquivo para onde quiser. Se você não especificar, acho que literalmente o coloca no caminho que forneci acima.
bytedev