Criar um pacote NuGet com a CLI do dotnet

  • Artigo

Os pacotes NuGet contêm código que os desenvolvedores podem reutilizar em seus projetos. Não importa o que seu código faça ou contém, você usa uma ferramenta de linha de comando, nuget.exe ou dotnet.exe, para criar o pacote NuGet.

Este artigo descreve como criar um pacote usando a CLI do dotnet. A partir do Visual Studio 2017, a CLI do dotnet está incluída em todas as cargas de trabalho do .NET e .NET Core. Se você precisar instalar a CLI do dotnet ou outras ferramentas de cliente NuGet, consulte Instalar ferramentas de cliente NuGet.

Este tópico se aplica somente ao .NET e a outros projetos que usam o formato estilo SDK. Para esses projetos, o NuGet usa informações do arquivo de projeto para criar um pacote. Para ver tutoriais passo a passo, consulte Criar pacotes com a CLI do dotnet e Criar pacotes com o Visual Studio.

O comando msbuild -t:pack do MSBuild é funcionalmente equivalente ao dotnet pack. Para obter mais informações sobre como criar um pacote com o MSBuild, consulte Criar um pacote NuGet usando o MSBuild.

Observação

Definir propriedades

Você pode criar um projeto de biblioteca de classes de exemplo usando o comando dotnet new classlib e empacotar o projeto usando dotnet pack. O comando dotnet pack usa as propriedades a seguir. Se você não especificar valores no arquivo de projeto, o comando usará valores padrão.

  • PackageId, o identificador do pacote, deve ser exclusivo em nuget.org e em quaisquer outros destinos que hospedam o pacote. Se você não especificar um valor, o comando usará o AssemblyName.
  • Version é um número de versão específico no formato Major.Minor.Patch[-Suffix], onde -Suffix identifica versões de pré-lançamento. Se esse campo não for especificado, o valor padrão será 1.0.0.
  • Authors são os autores do pacote. Se esse campo não for especificado, o valor padrão será AssemblyName.
  • Company são informações da empresa Se o valor não for especificado, o valor padrão será o valor de Authors.
  • Product são informações sobre produtos. Se esse campo não for especificado, o valor padrão será AssemblyName.

No Visual Studio, você pode definir esses valores nas propriedades do projeto. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções, selecione Propriedades e, em seguida, selecione a seção Pacote. Você também pode adicionar as propriedades diretamente em .csproj ou outro arquivo de projeto.

O exemplo a seguir mostra um arquivo de projeto com propriedades do pacote adicionadas.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Você pode adicionar outras propriedades opcionais, como Title, PackageDescription e PackageTags.

Observação

Para pacotes que você cria para consumo público, preste atenção especial à propriedade PackageTags. As tags ajudam outras pessoas a encontrar seu pacote e entender o que ele faz.

O comando dotnet pack converte automaticamente PackageReferences em seus arquivos de projeto em dependências no pacote criado. Você pode controlar quais ativos incluir por meio das tags IncludeAssets, ExcludeAssets e PrivateAssets. Para obter mais informações, consulte Controlar ativos de dependências.

Para obter mais informações sobre dependências, propriedades opcionais e controle de versão, consulte:

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

O identificador do pacote e o número de versão identificam de forma exclusiva o código exato que está contido no pacote.

Siga estas práticas recomendadas para criar o identificador do pacote:

  • O identificador deve ser exclusivo em nuget.org e em todos os outros locais que hospedam o pacote. Para evitar conflitos, um bom padrão é usar o nome da sua empresa como a primeira parte do identificador.

  • Siga uma convenção de nomenclatura semelhante a namespaces do .NET, usando a notação de pontos. Por exemplo, use Contoso.Utility.UsefulStuff em vez de Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Também é útil para os consumidores se você corresponder o identificador do pacote ao namespace usado pelo código.

  • Se você produzir um pacote de código de exemplo que demonstre como usar outro pacote, anexe .Sample como um sufixo ao identificador, como em Contoso.Utility.UsefulStuff.Sample.

    O pacote de exemplo tem uma dependência do pacote original. Ao criar o pacote de exemplo, adicione <IncludeAssets> com o valor contentFiles. Na pasta content, organize o código de exemplo em uma pasta chamada \Samples\<identificador>, como \Samples\Contoso.Utility.UsefulStuff.Sample.

Siga estas melhores práticas para definir a versão do pacote:

  • Em geral, defina a versão do pacote para corresponder à versão do projeto ou assembly, embora isso não seja estritamente necessário. Igualar a versão é uma questão simples quando você limita um pacote a um único assembly. O NuGet em si lida com versões do pacote ao resolver as dependências, não 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 em Controle de versão de pacotes. O NuGet é em grande parte compatível com o Controle de Versão Semântico 2.0.0.

Observação

Para obter mais informações sobre a resolução de dependências, confira Resolução de dependências com PackageReference. Para obter informações que podem ajudar a entender o controle de versão, confira esta série de postagens no blog.

Adicionar um campo de descrição opcional

A descrição opcional do pacote aparece na guia LEIAME da página nuget.org do pacote. A descrição é transferida do <Description> no arquivo de projeto ou do $description no arquivo .nuspec.

O exemplo a seguir mostra um Description no arquivo .csproj para um pacote .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://video2.skills-academy.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://video2.skills-academy.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://video2.skills-academy.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Executar o comando pack

Para compilar um pacote do NuGet ou arquivo .nupkg, execute o comando dotnet pack da pasta do projeto, que também compila o projeto automaticamente.

dotnet pack

A saída mostra o caminho até o arquivo .nupkg.

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Gerar pacote automaticamente no build

Para executar dotnet pack automaticamente sempre que você executar dotnet build, adicione a seguinte linha ao arquivo de projeto na tag <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Observação

Quando o pacote é gerado automaticamente, o empacotamento aumenta o tempo de compilação do seu projeto.

Executar dotnet pack em uma soluçãoempacota todos os projetos na solução que são empacotáveis, ou sejam que têm a propriedade IsPackable definida como true.

Instalação do pacote de teste

Antes de publicar um pacote, você deve testar a instalação do pacote em um projeto. Testar garante que os arquivos todos terminem em seus lugares corretos no projeto.

Teste a instalação manualmente no Visual Studio ou na linha de comando usando as etapas normais de instalação do pacote.

Importante

  • Não é possível alterar pacotes depois de criados. Se você corrigir um problema, altere o conteúdo do pacote e refaça o pacote

  • Após o pacote ser recriado, o novo teste ainda usa a versão antiga do pacote até que você limpe a pasta de pacotes globais. Limpar a pasta é especialmente importante para pacotes que não usam um rótulo de pré-lançamento exclusivo em cada compilação.

Próximas etapas

Depois de criar o pacote, você pode publicar o arquivo .nupkg no host de sua escolha.

Publicar um pacote

Consulte os seguintes artigos para obter maneiras de estender os recursos do seu pacote ou oferecer suporte a outros cenários: