Criar um pacote usando a CLI nuget.exe

Não importa o que o pacote faz ou qual código ele contém, você usa uma das ferramentas da CLI, ou nuget.exedotnet.exe, para empacotar essa funcionalidade em um componente que pode ser compartilhado e usado por qualquer número de outros desenvolvedores. Para instalar as ferramentas da CLI do NuGet, consulte Instalar ferramentas de cliente do NuGet. Observe que o Visual Studio não inclui automaticamente uma ferramenta da CLI.

• Para projetos não estilo SDK, normalmente projetos do .NET Framework, siga as etapas descritas neste artigo para criar um pacote. Para obter instruções passo a passo usando o Visual Studio e a nuget.exe CLI, consulte Criar e publicar um pacote do .NET Framework.

• Para projetos .NET Core e .NET Standard que usam o formato estilo SDK e quaisquer outros projetos no estilo SDK, consulte Criar um pacote NuGet usando a CLI do dotnet.

• Para projetos migrados de packages.config para PackageReference, use msbuild -t:pack.

Tecnicamente falando, um pacote NuGet é apenas um arquivo ZIP que foi renomeado com a .nupkg extensão e cujo conteúdo corresponde a determinadas convenções. Este tópico descreve o processo detalhado de criação de um pacote que atenda a essas convenções.

O empacotamento começa com o código compilado (assemblies), símbolos e/ou outros arquivos que você deseja entregar como um pacote (consulte Visão geral e fluxo de trabalho). Esse processo é independente de compilar ou gerar os arquivos que entram no pacote, embora você possa extrair informações em um arquivo de projeto para manter os assemblies e pacotes compilados em sincronia.

Decidir quais assemblies empacotar

A maioria dos pacotes de uso geral contém um ou mais assemblies que outros desenvolvedores podem usar em seus próprios projetos.

• Em geral, é melhor ter um assembly por pacote NuGet, desde que cada um seja útil de forma independente. Por exemplo, se você tiver um Utilities.dll que dependa de Parser.dll e Parser.dll for útil por conta própria, então crie um pacote para cada um. Isso permite que os desenvolvedores usem Parser.dll independentemente de Utilities.dll.

• Se a sua biblioteca for composta por um conjunto de assemblies que não são úteis independentemente, é aceitável combiná-los em um único pacote. Usando o exemplo anterior, se Parser.dll contiver o código usado apenas por Utilities.dll, tudo bem manter Parser.dll no mesmo pacote.

• Da mesma forma, se Utilities.dll depender de Utilities.resources.dll, onde novamente o último não é útil por conta própria, coloque ambos no mesmo pacote.

Os recursos são, de fato, um caso especial. Quando um pacote é instalado em um projeto, o NuGet adiciona automaticamente referências de assembly às DLLs do pacote, excluindo aquelas nomeadas .resources.dll porque elas são consideradas assemblies satélite localizados (consulte Criando pacotes localizados). Por esse motivo, evite usar .resources.dll em arquivos que contenham código de pacote essencial.

Se sua biblioteca contiver assemblies de interoperabilidade COM, siga as diretrizes adicionais em Criar pacotes com assemblies de interoperabilidade COM.

A função e a estrutura do arquivo .nuspec

Depois de saber quais arquivos deseja empacotar, a próxima etapa é criar um manifesto de pacote em um .nuspec arquivo XML.

O manifesto:

1. Descreve o conteúdo do pacote e está incluído nele.
2. Conduz a criação do pacote e instrui o NuGet sobre como instalar o pacote em um projeto. Por exemplo, o manifesto identifica outras dependências de pacote, de modo que o NuGet também pode instalar essas dependências quando o pacote principal é instalado.
3. Contém propriedades necessárias e opcionais, conforme descrito abaixo. Para obter detalhes exatos, incluindo outras propriedades não mencionadas aqui, consulte a referência .nuspec.

Propriedades necessárias:

• O identificador do pacote, que deve ser exclusivo em toda a galeria que hospeda o pacote.
• Um número de versão específico no formato Major.Minor.Patch[-Sufixo] onde -Sufixo identifica versões de pré-lançamento
• O título do pacote como deve aparecer no host (como nuget.org)
• Informações de autor e proprietário.
• Uma descrição longa do pacote.

Propriedades opcionais comuns:

• Notas de lançamento
• Informações sobre direitos autorais
• Uma breve descrição da interface do usuário do Gerenciador de Pacotes no Visual Studio
• Uma ID de localidade
• URL do Projeto
• Licença como uma expressão ou arquivo (licenseUrl foi preterido, use license o elemento de metadados nuspec em vez disso)
• Um arquivo de ícone (iconUrl foi preterido usando icon o elemento de metadados nuspec em vez disso)
• Listas de dependências e referências
• Tags que ajudam nas pesquisas na galeria

Veja a seguir um arquivo típico (mas fictício), .nuspec com comentários que descrevem as propriedades:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Para obter detalhes sobre como declarar dependências e especificar números de versão, consulte packages.config e controle de versão do pacote. Também é possível exibir ativos de dependências diretamente no pacote usando os atributos include e exclude no elemento dependency. Consulte .nuspec Reference – Dependencies.

Como o manifesto está incluído no pacote criado a partir dele, você pode encontrar vários exemplos adicionais examinando pacotes existentes. Uma boa origem é a pasta global-packages em seu computador, cuja localização é retornada pelo seguinte comando:

nuget locals -list global-packages

Vá para qualquer pasta package\version , copie o .nupkg arquivo para um .zip arquivo e, em seguida, abra esse .zip arquivo e examine-o .nuspec dentro dele.

Criar o arquivo .nuspec

A criação de um manifesto completo normalmente começa com um arquivo básico .nuspec gerado por meio de um dos seguintes métodos:

• Um diretório de trabalho baseado em convenção
• Uma DLL de montagem
• Um projeto do Visual Studio
• Novo arquivo com valores padrão

Em seguida, edite o arquivo manualmente para que ele descreva o conteúdo exato desejado no pacote final.

De um diretório de trabalho baseado em convenção

Como um pacote NuGet é apenas um arquivo ZIP que foi renomeado com a .nupkg extensão, geralmente é mais fácil criar a estrutura de pastas desejada em seu sistema de arquivos local e, em seguida, criar o .nuspec arquivo diretamente dessa estrutura. O comando nuget pack então adiciona automaticamente todos os arquivos naquela estrutura de pastas (excluindo qualquer pasta que comece com ., permitindo assim que você mantenha arquivos privados na mesma estrutura).

A vantagem dessa abordagem é que você não precisa especificar no manifesto quais arquivos você deseja incluir no pacote (conforme explicado posteriormente neste tópico). Você pode simplesmente fazer com que o processo de build produza a estrutura de pasta exata que entra no pacote e pode incluir facilmente outros arquivos que podem não fazer parte de um projeto, caso contrário:

• Conteúdo e código-fonte que devem ser injetados no projeto de destino.
• Scripts do PowerShell
• Transformações em arquivos de configuração e código-fonte existentes em um projeto.

As convenções de pasta são as seguintes:

Como sua estrutura de pastas pode conter qualquer número de assemblies para qualquer número de estruturas de destino, esse método é necessário ao criar pacotes que dão suporte a várias estruturas.

De qualquer forma, depois de ter a estrutura de pasta desejada em vigor, execute o seguinte comando nessa pasta para criar o .nuspec arquivo:

nuget spec

Novamente, o gerado .nuspec não contém referências explícitas a arquivos na estrutura de pastas. O NuGet inclui automaticamente todos os arquivos quando o pacote é criado. No entanto, você ainda precisa editar valores de espaço reservado em outras partes do manifesto.

De uma DLL de assembly

No caso simples de criar um pacote a partir de um assembly, você pode gerar um arquivo .nuspec dos metadados no assembly usando o seguinte comando:

nuget spec <assembly-name>.dll

O uso deste formulário substitui alguns espaços reservados no manifesto por valores específicos do conjunto. Por exemplo, a <id> propriedade é definida como o nome do assembly e <version> é definida como a versão do assembly. No entanto, outras propriedades no manifesto não têm valores correspondentes no assembly e, portanto, ainda contêm marcadores de posição.

De um projeto do Visual Studio

Criar um .nuspec a partir de um arquivo .csproj ou .vbproj é conveniente porque outros pacotes que foram instalados nesses projetos são automaticamente referenciados como dependências. Basta usar o seguinte comando na mesma pasta que o arquivo de projeto:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

O arquivo resultante <project-name>.nuspec contém tokens que são substituídos durante o processo de empacotamento por valores do projeto, incluindo referências a quaisquer outros pacotes que já tenham sido instalados.

Se você tiver dependências de pacote para incluir no .nuspec, use nuget packe obtenha o arquivo .nuspec de dentro do arquivo .nupkg gerado. Por exemplo, use o comando a seguir.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

Um token é delimitado por $ símbolos em ambos os lados da propriedade do projeto. Por exemplo, o <id> valor em um manifesto gerado dessa maneira normalmente aparece da seguinte maneira:

<id>$id$</id>

Esse token é substituído pelo valor AssemblyName do arquivo de projeto no momento do empacotamento. Para obter o mapeamento exato de valores do projeto para .nuspec tokens, consulte a referência de tokens de substituição.

Os tokens eliminam a necessidade de atualizar valores cruciais, como o número de versão .nuspec, no momento em que você atualiza o projeto. (Você sempre pode substituir os tokens por valores literais, se desejado).

Observe que há várias opções de empacotamento adicionais disponíveis ao trabalhar em um projeto do Visual Studio, conforme descrito em Executar pacote nuget para gerar o arquivo .nupkg posteriormente.

Pacotes no nível da solução

Somente NuGet 2.x. Não disponível no NuGet 3.0+.

O NuGet 2.x dá suporte à noção de um pacote nível de solução que instala ferramentas ou comandos adicionais para o Console do Gerenciador de Pacotes (o conteúdo da pasta tools), mas não adiciona referências, conteúdo ou personalizações de build a nenhum projeto na solução. Esses pacotes não contêm arquivos em suas pastas diretas lib, content ou build, e nenhuma de suas dependências tem arquivos em suas respectivas pastas lib, content ou build.

O NuGet rastreia pacotes instalados no nível de solução em um arquivo packages.config dentro da pasta .nuget, em vez do arquivo packages.config do projeto.

Novo arquivo com valores padrão

O comando a seguir cria um manifesto padrão com espaços reservados, o que garante que você comece com a estrutura de arquivo adequada:

nuget spec [<package-name>]

Se você omitir <o nome> do pacote, o arquivo resultante será Package.nuspec. Se você fornecer um nome como Contoso.Utility.UsefulStuff, o arquivo será Contoso.Utility.UsefulStuff.nuspec.

O resultado .nuspec contém espaços reservados para valores como .projectUrl Certifique-se de editar o arquivo antes de usá-lo para criar o arquivo final .nupkg .

Escolher um identificador de pacote exclusivo e definir o número de versão

O identificador do pacote (<id> elemento) e o número da versão (<version> elemento) são os dois valores mais importantes no manifesto porque identificam exclusivamente o código exato contido no pacote.

Práticas recomendadas para o identificador de pacote:

• Exclusividade: o identificador deve ser exclusivo entre nuget.org ou qualquer galeria que hospede o pacote. Antes de decidir sobre um identificador, pesquise na galeria aplicável para verificar se o nome já está em uso. Para evitar conflitos, um bom padrão é usar o nome da empresa como a primeira parte do identificador, como Contoso..
• Nomes semelhantes a namespace: siga um padrão semelhante aos namespaces no .NET, usando notação de ponto em vez de hifens. Por exemplo, use Contoso.Utility.UsefulStuff em vez de Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Os consumidores também acham útil quando o identificador de pacote corresponde aos namespaces usados no código.
• Pacotes de exemplo: se você produzir um pacote de código de exemplo que demonstra como usar outro pacote, anexe .Sample como um sufixo ao identificador, como em Contoso.Utility.UsefulStuff.Sample. (O pacote de exemplo, naturalmente, teria uma dependência no outro pacote.) Ao criar um pacote de exemplo, use o método de diretório de trabalho baseado em convenção descrito anteriormente. Na pasta content, organize o código de exemplo em uma pasta chamada \Samples\<identifier> como em \Samples\Contoso.Utility.UsefulStuff.Sample.

Práticas recomendadas para a versão do pacote:

• Em geral, defina a versão do pacote para corresponder à biblioteca, embora isso não seja estritamente necessário. Essa é uma questão simples quando você limita um pacote a um único assembly, conforme descrito anteriormente em Decidir quais assemblies empacotar. No geral, lembre-se de que o NuGet em si lida com versões de pacote ao resolver dependências, não com versões de assembly.
• Ao usar um esquema de versão não padrão, considere as regras de controle de versão do NuGet, conforme explicado no controle de versão do Pacote.

A seguinte série de breves postagens no blog também são úteis para entender o controle de versão:

• Parte 1: Enfrentando o Inferno da DLL
• Parte 2: O algoritmo principal
• Parte 3: Unificação por meio de redirecionamentos de vínculo

Adicionar um README e outros arquivos

Para especificar os arquivos a serem <files> no pacote, use o .nuspec nó no arquivo, que segue a <metadata> tag.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Quando você inclui um arquivo nomeado readme.txt na raiz do pacote, o Visual Studio exibe o conteúdo desse arquivo como texto sem formatação imediatamente após a instalação do pacote diretamente. (Os arquivos Readme não são exibidos para pacotes instalados como dependências). Por exemplo, veja como o arquivo README do pacote HtmlAgilityPack é exibido:

Incluir props e alvos do MSBuild em um pacote

Em alguns casos, talvez você queira adicionar destinos de build personalizados ou propriedades em projetos que consomem seu pacote, como executar uma ferramenta personalizada ou um processo durante o build. Saiba mais sobre props e alvos do MSBuild em pacotes NuGet

Criar <package_id>.targets ou <package_id>.props (como Contoso.Utility.UsefulStuff.targets) dentro das pastas de build do projeto.

Em seguida, no arquivo .nuspec, consulte estes arquivos no node <files>.

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Quando os pacotes são adicionados a um projeto, o NuGet incluirá automaticamente esses adereços e destinos.

Executar o pacote nuget para gerar o arquivo .nupkg

Ao usar um assembly ou o diretório de trabalho baseado em convenção, crie um pacote executando nuget pack com o arquivo .nuspec, substituindo <project-name> pelo nome de arquivo específico.

nuget pack <project-name>.nuspec

Ao usar um projeto do Visual Studio, execute nuget pack com o arquivo de projeto, que carrega automaticamente o arquivo do .nuspec projeto e substitui todos os tokens dentro dele usando valores no arquivo de projeto:

nuget pack <project-name>.csproj

Em todos os casos, nuget pack exclui pastas que começam com um período, como .git ou .hg.

O NuGet indica se há erros no .nuspec arquivo que precisam ser corrigidos, como esquecer de alterar valores de espaço reservado no manifesto.

Depois que nuget pack for concluído com sucesso, você terá um arquivo .nupkg que pode ser publicado em uma galeria adequada, conforme descrito em Publicação de Pacote.

Opções adicionais

Você pode usar várias opções de linha de comando com nuget pack para excluir arquivos, substituir o número de versão no manifesto e alterar a pasta de saída, entre outros recursos. Para obter uma lista completa, consulte a referência de comando do pacote.

As opções a seguir são algumas que são comuns com projetos do Visual Studio:

• Projetos referenciados: se o projeto fizer referência a outros projetos, você poderá adicionar os projetos referenciados como parte do pacote ou como dependências usando a opção -IncludeReferencedProjects :

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Esse processo de inclusão é recursivo, portanto, se MyProject.csproj fizer referência aos projetos B e C, e esses projetos fizerem referência a D, E e F, os arquivos de B, C, D, E e F serão incluídos no pacote.

  Se um projeto referenciado incluir um .nuspec arquivo próprio, o NuGet adicionará esse projeto referenciado como uma dependência. Você precisa empacotar e publicar esse projeto separadamente.

• Configuração de build: Por padrão, o NuGet usa a configuração de build padrão definida no arquivo de projeto, tipicamente Debug. Para empacotar arquivos de uma configuração de build diferente, como Release, use a opção -properties com a configuração:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Símbolos: para incluir símbolos que permitem aos consumidores avançar pelo código do pacote no depurador, use a opção -Symbols:

  nuget pack MyProject.csproj -symbols
  

Testar a instalação do pacote

Antes de publicar um pacote, você normalmente deseja testar o processo de instalação de um pacote em um projeto. Os testes garantem que os arquivos necessários sejam colocados corretamente em seus locais no projeto.

Você pode testar instalações manualmente no Visual Studio ou na linha de comando usando as etapas normais de instalação do pacote.

Para testes automatizados, o processo básico é o seguinte:

1. Copie o .nupkg arquivo para uma pasta local.
2. Adicione a pasta às fontes do pacote usando o nuget sources add -name <name> -source <path> comando (consulte fontes do nuget). Observe que você só precisa definir essa fonte local uma vez em um determinado computador.
3. Instale o pacote dessa origem usando nuget install <packageID> -source <name> onde <name> corresponde ao nome da fonte conforme fornecido nuget sources. Especificar a origem garante que o pacote seja instalado apenas dessa origem.
4. Examine o sistema de arquivos para verificar se os arquivos estão instalados corretamente.

Próximas etapas

Depois de criar um pacote, que é um .nupkg arquivo, você pode publicá-lo na galeria de sua escolha, conforme descrito na publicação de um pacote.

Talvez você também queira estender os recursos do pacote ou dar suporte a outros cenários, conforme descrito nos seguintes tópicos:

• Controle de versão do pacote
• Suporte a vários frameworks de destino
• Transformações de arquivos de origem e configuração
• Localization
• Versões de pré-lançamento
• Definir tipo de pacote
• Criar pacotes com assemblies de interoperabilidade COM

Por fim, há tipos de pacotes adicionais dos quais devemos estar cientes:

• Pacotes nativos
• Pacotes de símbolos