Compartilhar via

Criar um pacote NuGet usando o MSBuild

Ao criar um pacote NuGet a partir do 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 o NuGet. Além disso, você também pode usar o MSBuild por meio da CLI dotnet 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 não estilo SDK que usa <PackageReference>, o NuGet também usa o arquivo de projeto para criar um pacote.

Projetos no estilo SDK têm a funcionalidade do pacote disponível por padrão. Para projetos PackageReference que não usam o 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 os destinos do pacote MSBuild, consulte o pacote NuGet e a restauração como destinos do MSBuild.

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 não estilo SDK que usam PackageReference.

Definir propriedades

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

  • PackageId, o identificador do pacote, que deve ser exclusivo em toda a galeria que hospeda o pacote. Se esse campo não for especificado, o valor padrão será AssemblyName.
  • Version, um número de versão específico no formato Major.Minor.Patch[-Sufixo] que -Sufixo 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 de autor e proprietário. Se esse campo não for especificado, o valor padrão será AssemblyName.
  • Company, o nome da sua empresa. Se esse campo não for especificado, o valor padrão será AssemblyName.

Além disso, se você estiver empacotando projetos não estilo SDK que usam PackageReference, o seguinte é necessário:

  • PackageOutputPath, a pasta de saída do pacote gerado ao chamar 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 nuget.org ou 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 nos destinos do pacote MSBuild, controlando ativos de dependência e propriedades de metadados do NuGet.

Observação

Para pacotes criados para consumo público, preste atenção especial à 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 do pacote. Também é possível exibir ativos 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 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>

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:

Configurar o projeto para empacotamento

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

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

O Visual Studio 2022 e anterior não tem 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 o 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 comando a seguir para restaurar o pacote NuGet.Build.Tasks.Pack.

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

    Verifique se a saída do MSBuild indica que o build foi concluído com êxito.

Executar o comando msbuild -t:pack

Para criar um pacote NuGet (um .nupkg arquivo) 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ê compilar ou restaurar o projeto, adicione a seguinte linha ao 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> a propriedade é definida como true).

Observação

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

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.

Importante

Os pacotes são imutáveis. Se você corrigir um problema, alterar o conteúdo interno do pacote e empacotar novamente, quando você testar novamente 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 build.

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:

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

  • Last updated on