Partilhar via

Criar um pacote NuGet com a CLI dotnet

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

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

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

O comando MSBuild msbuild -t:pack é 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 as 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 seguintes propriedades. 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], onde -Suffix identifica as versões de pré-lançamento. Se 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á o AssemblyName.
  • Company é informação da empresa. Se não for especificado, o valor padrão será o Authors valor.
  • Product é informação sobre o produto. Se não for especificado, o valor padrão será o 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 arquivo .csproj ou outro arquivo de projeto.

O exemplo a seguir mostra um arquivo de projeto com propriedades de 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ê constrói para consumo público, preste especial atenção à PackageTags propriedade. As tags ajudam outras pessoas a encontrar seu pacote e entender o que ele faz.

O comando dotnet pack converte automaticamente PackageReferences nos ficheiros do projeto em dependências no package criado. Você pode controlar quais ativos incluir por meio das IncludeAssetstags , 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 da 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 entre nuget.org e 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 um namespace .NET, usando notação de ponto. Por exemplo, use Contoso.Utility.UsefulStuff em vez de Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Também é útil para os consumidores se a correspondência entre o identificador do pacote e o namespace usado pelo código for realizada.

  • Se você produzir um pacote de código de exemplo que demonstra como usar outro pacote, anexe .Sample 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 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. Combinar a versão é simples quando você limita um pacote a um único assembly. O próprio NuGet lida com versões de pacotes 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 em Controle de versão de pacote. O NuGet é principalmente compatível com o Semantic Versioning 2.0.0.

Observação

Para obter mais informações sobre 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 LEIA-ME da página nuget.org do pacote. A descrição é extraída do arquivo de projeto <Description> ou do arquivo $description.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 na 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 executar dotnet build, adicione a seguinte linha ao seu arquivo de projeto na <PropertyGroup> tag :

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Observação

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

A execução dotnet pack em uma solução empacota todos os projetos na solução que podem ser empacotados, ou seja, têm a IsPackable propriedade 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. Os testes garantem que os arquivos necessários acabem em seus lugares corretos no projeto.

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

Importante

  • Não é possível alterar os pacotes depois de criados. Caso corrija um problema, altere o conteúdo da embalagem e volte a embalá-la.

  • Depois de recriar o pacote, 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óximos passos

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:

  • Last updated on