Partilhar via

Criar um pacote NuGet usando o MSBuild

Ao criar um pacote NuGet a partir do seu código, você empacota essa funcionalidade em um componente que pode ser compartilhado e usado por qualquer número de outros desenvolvedores. Este artigo descreve como criar um pacote usando o MSBuild. O MSBuild vem pré-instalado com cada carga de trabalho do Visual Studio que contém NuGet. Além disso, pode também usar o MSBuild através da CLI com dotnet msbuild.

Para projetos .NET Core e .NET Standard que usam o formato estilo SDK e quaisquer outros projetos no estilo SDK, o NuGet usa informações no arquivo de projeto diretamente para criar um pacote. Para um projeto que não seja no estilo SDK que use <PackageReference>, o NuGet também utiliza o arquivo de projeto para criar um pacote.

Projetos no estilo SDK têm a funcionalidade de pacote disponível por padrão. Para projetos PackageReference que não sejam no estilo SDK, ele também está disponível por padrão a partir do Visual Studio 2026. Em versões anteriores do Visual Studio, você precisa adicionar o pacote NuGet.Build.Tasks.Pack às dependências do projeto e recomendamos remover essa referência de pacote ao atualizar para o Visual Studio 2026. Para obter informações detalhadas sobre destinos de pacotes do MSBuild, consulte NuGet pack and restore as MSBuild targets.

Para projetos no estilo SDK, msbuild -t:pack é funcionalmente equivalente a dotnet pack.

Importante

Este tópico se aplica a projetos no estilo SDK , normalmente projetos .NET Core e .NET Standard, e a projetos que não sejam no estilo SDK que usam PackageReference.

Definir as propriedades

As propriedades a seguir são necessárias para criar um pacote.

  • PackageId, o identificador do pacote, que deve ser exclusivo na galeria que hospeda o pacote. Se não for especificado, o valor padrão será 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 não for especificado, o valor padrão será 1.0.0.
  • O título do pacote como deve aparecer no host (como nuget.org)
  • Authors, informações do autor e do proprietário. Se não for especificado, o valor padrão será AssemblyName.
  • Company, o nome da sua empresa. Se não for especificado, o valor padrão será AssemblyName.

Além disso, se estiver a empacotar projetos no estilo não-SDK que usam PackageReference, o seguinte é necessário:

  • PackageOutputPath, a pasta de saída para o pacote gerado ao executar o comando pack.

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, escolha Propriedades e selecione a guia Pacote ). Você também pode definir essas propriedades diretamente nos arquivos de projeto (.csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Importante

Dê ao pacote um identificador exclusivo em todo nuget.org ou em qualquer fonte de pacote que você esteja usando.

O exemplo a seguir mostra um arquivo de projeto simples e completo com essas propriedades incluídas.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Você também pode definir as propriedades opcionais, como Title, PackageDescriptione PackageTags, conforme descrito em Destinos do pacote MSBuild, Controlando ativos de dependência e Propriedades de metadados NuGet.

Observação

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

Para obter detalhes sobre como declarar dependências e especificar números de versão, consulte Referências de pacote em arquivos de projeto e Controle de versão de pacote. Também é possível exibir recursos de dependências diretamente no pacote usando os atributos <IncludeAssets> e <ExcludeAssets>. Para obter mais informações, consulte Controlando ativos de dependência.

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>

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:

Configurar projeto para pacote

Projetos no estilo SDK não exigem nenhuma configuração adicional.

Projetos que não sejam no estilo SDK precisam de pelo menos um pacote instalado (via PackageReference, não packages.config), ou o projeto precisa explicitamente instruir o NuGet a tratar o projeto como um projeto PackageReference por meio da RestoreProjectStyle propriedade.

O Visual Studio 2022 e versões anteriores não têm pacote interno, portanto, você também precisa instalar o pacote NuGet.Build.Tasks.Pack. Ao atualizar para o Visual Studio 2026 ou posterior, recomendamos desinstalar o pacote, para que você se beneficie de novos recursos e correções de bugs.

  1. Edite o arquivo de projeto.

    Se você quiser instruir explicitamente o NuGet a tratar o projeto como PackageReference (o projeto não tem nenhum pacote instalado), localize ou adicione um <PropertyGroup> que não tenha nenhuma Condition instrução e adicione:

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    Se você estiver usando o Visual Studio 2022 ou anterior, adicione o seguinte após o <PropertyGroup> elemento :

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    Observação

    Considere usar a versão mais recente deste pacote disponível.

  2. Abra um prompt de comando do desenvolvedor (na caixa Pesquisar , digite prompt de comando do desenvolvedor).

    Normalmente, você deseja iniciar o prompt de comando do desenvolvedor para Visual Studio no menu Iniciar , pois ele será configurado com todos os caminhos necessários para o MSBuild.

  3. Alterne para a pasta que contém o arquivo de projeto e digite o seguinte comando para restaurar o pacote NuGet.Build.Tasks.Pack.

    # Uses the project file in the current folder by default
msbuild -t:restore

    Certifique-se de que a saída MSBuild indica que a compilação foi concluída com êxito.

Execute o comando msbuild -t:pack

Para criar um pacote NuGet (um .nupkg arquivo) a partir do projeto, execute o msbuild -t:pack comando, que também cria o projeto automaticamente:

No prompt de comando do desenvolvedor para Visual Studio, digite o seguinte comando:

# Uses the project file in the current folder by default
msbuild -t:pack

A saída mostra o caminho para o .nupkg arquivo.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Gerar automaticamente o pacote na compilação

Para executar msbuild -t:pack automaticamente quando você cria ou restaura o projeto, adicione a seguinte linha ao seu arquivo de projeto em <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Quando você executa msbuild -t:pack em uma solução, isso empacota todos os projetos na solução que são empacotáveis (<IsPackable> propriedade está definida como true).

Observação

Quando você gera automaticamente o pacote, o tempo para empacotar aumenta o tempo de compilação para o seu projeto.

Instalação do pacote de teste

Antes de publicar um pacote, você normalmente deseja testar o processo de instalação de um pacote em um projeto. Os testes asseguram que todos os ficheiros necessários acabam nos seus lugares corretos 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.

Importante

Os pacotes são imutáveis. Se corrigir um problema, alterar o conteúdo do pacote e empacotar novamente, ao testar, você ainda estará usando a versão antiga do pacote até limpar a pasta de pacotes globais. Isso é especialmente relevante ao testar pacotes que não usam um rótulo de pré-lançamento exclusivo em cada compilação.

Próximas Etapas

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

Você também pode querer estender os recursos do seu pacote ou oferecer suporte a outros cenários, conforme descrito nos tópicos a seguir:

Finalmente, existem tipos de pacotes adicionais aos quais deve estar atento:

  • Last updated on