Compartilhar via

Criar um pacote NuGet com a CLI do dotnet

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 contenha, você usa uma ferramenta de linha de comando, nuget.exe ou , dotnet.exepara 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 é incluída em todas as cargas de trabalho do .NET e do .NET Core. Se você precisar instalar a CLI do dotnet ou outras ferramentas de cliente do NuGet, consulte Instalar ferramentas de cliente do NuGet.

Este tópico se aplica apenas 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 obter tutoriais de início rápido, consulte Criar pacotes com a CLI do dotnet ou criar pacotes com o Visual Studio.

O comando MSBuild msbuild -t:pack é funcionalmente equivalente ao pacote dotnet. 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 dotnet new classlib comando e empacotar o projeto usando dotnet pack. O dotnet pack comando 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 entre nuget.org e 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 formulário Major.Minor.Patch[-Suffix], em que -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 não for especificado, o valor padrão será .AssemblyName
  • Company é informação da empresa. Se não for especificado, o valor padrão será o Authors valor.
  • Product é informações do produto. Se 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 selecione a seção Pacote . Você também pode adicionar as propriedades diretamente ao .csproj ou a outro arquivo de projeto.

O exemplo a seguir mostra um arquivo de projeto com as 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, PackageDescriptione PackageTags.

Observação

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

O comando dotnet pack converte automaticamente os PackageReference nos 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 Controlando ativos de dependência.

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

Escolha um identificador de pacote exclusivo e defina o número da versão

O identificador do pacote e o número de versão identificam exclusivamente o código exato contido no pacote.

Siga estas práticas recomendadas para criar o identificador de 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 empresa como a primeira parte do identificador.

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

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

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

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

  • Em geral, defina a versão do pacote para corresponder à versão do projeto ou do assembly, embora isso não seja estritamente necessário. A correspondência da versão é simples quando você limita um pacote a um único conjunto. O nuGet em si lida com versões de pacote ao resolver dependências, não com versões de assembly.

  • Se você 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. O NuGet é principalmente 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ência, consulte Resolução de dependência com PackageReference. Para obter informações que possam ajudá-lo a entender o controle de versão, consulte esta série de postagens no blog:

Adicionar um campo de descrição opcional

A descrição opcional do pacote aparece na guia README da página nuget.org do pacote. A descrição é extraída 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://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Executar o comando pack

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

dotnet pack

A saída mostra o caminho para 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 automaticamente o pacote na compilação

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

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Observação

Quando você gera automaticamente o pacote, o empacotamento aumenta o tempo de compilação do projeto.

A execução de dotnet pack em uma solução empacota todos os projetos da solução que podem ser empacotados, ou seja, têm a propriedade IsPackable definida como true.

Testar a instalação do pacote

Antes de publicar um pacote, você deve testar a instalação do pacote em um projeto. O teste garante que os arquivos necessários acabem em seus locais corretos no projeto.

Teste a instalação manualmente no Visual Studio ou na linha de comando usando o processo normal de instalação do pacote.

Importante

  • Você não pode alterar pacotes uma vez criados. Se você corrigir um problema, altere o conteúdo do pacote e reempacote.

  • Depois de recriar o pacote, o reteste ainda usa a versão antiga do pacote até limpar 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 build.

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 pacote ou dar suporte a outros cenários:

  • Last updated on