Início Rápido: Criar e publicar um pacote NuGet usando o Visual Studio (somente no Windows)

Com o Microsoft Visual Studio, você pode criar um pacote NuGet desde uma biblioteca de classes .NET e publicá-lo em nuget.org usando uma ferramenta de CLI.

O guia de início rápido destina-se apenas a usuários do Windows. Se você estiver usando o Visual Studio para Mac, consulte Criar um pacote NuGet a partir de projetos de biblioteca existentes ou use a CLI do .NET.

Pré-requisitos

• Instale o Visual Studio 2022 para Windows com qualquer carga de trabalho relacionada ao .NET Core.

  É possível instalar a edição Community 2022 gratuitamente em visualstudio.microsoft.com ou usar a edição Professional ou Enterprise.

  O Visual Studio 2017 em diante inclui automaticamente os recursos do NuGet quando uma carga de trabalho relacionada ao .NET é instalada.

• Instale a CLI do .NET se ela ainda não estiver instalada.

  No Visual Studio 2017 em diante, a CLI do .NET é instalada automaticamente com qualquer carga de trabalho relacionada ao .NET Core. Caso contrário, instale o SDK do .NET Core para ter a CLI do .NET. A CLI do .NET é necessária para projetos do .NET que usam o formato de estilo SDK (atributo do SDK). O modelo de biblioteca de classes .NET padrão no Visual Studio 2017 em diante usa o atributo SDK.

  Importante

  Se você estiver trabalhando com um projeto estilo não SDK, siga os procedimentos em Criar e publicar um pacote de .NET Framework (Visual Studio) para criar e publicar o pacote. Para este artigo, a CLI do .NET é recomendada. Embora você possa publicar qualquer pacote NuGet usando a CLI do NuGet, algumas das etapas neste artigo são específicas para projetos no estilo SDK e a CLI do .NET. A CLI do NuGet é usada para projetos estilo não SDK (normalmente, .NET Framework).

• Registre-se em uma conta gratuita em nuget.org, se ainda não tiver uma. Você deverá se registrar confirmar a conta antes de poder carregar um pacote do NuGet.

• Instale a CLI do NuGet baixando-a de nuget.org. Adicione o arquivo nuget.exe em uma pasta adequada e adicione essa pasta à variável de ambiente PATH.

Criar um projeto de biblioteca de classes

Você pode usar um projeto existente da Biblioteca de Classes .NET para o código que você deseja empacotar, ou criar um da seguinte maneira:

1. No Visual Studio, selecione Arquivo>Novo>Projeto.

2. Na janela Criar um novo projeto, selecione C#, Windows e Biblioteca nas listas suspensas.

3. Na lista resultante de modelos de projeto, selecione Biblioteca de Classes (com a descrição Um projeto para criar uma biblioteca de classes destinada ao .NET ou .NET Standard) e selecione Avançar.

4. Na caixa de diálogo Configurar novo projeto, insira AppLogger como Nome do projeto e selecione Avançar.

5. Na janela Informações adicionais, selecione uma Estrutura apropriada e selecione Criar.

   Se você não tiver certeza de qual estrutura selecionar, a mais recente é uma boa escolha e pode ser facilmente alterada mais tarde. Para obter informações sobre qual estrutura usar, consulte Quando o objetivo é o .NET 5.0 ou .NET 6.0 vs. .NET Standard.

6. Para garantir que o projeto tenha sido criado corretamente, selecione Compilar>Compilar solução. A DLL é encontrada dentro da pasta de Depuração (ou Versão, se você compilar essa configuração).

7. (Opcional) Para este guia de início rápido, você não precisa escrever nenhum código adicional para o pacote NuGet porque a biblioteca de classes de modelo é suficiente para criar um pacote. No entanto, se você desejar algum código funcional para o pacote, inclua o seguinte código:

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

Configurar propriedades do pacote

Depois de criar seu projeto, você poderá configurar as propriedades do pacote NuGet seguindo estas etapas:

1. Selecione seu projeto no Gerenciador de Soluções e, em seguida, selecione Projeto>Propriedades de <nome do projeto>, onde <nome do projeto> é o nome do seu projeto.

2. Expanda o nó Pacote e selecione Geral.

   O nó Pacote aparece somente para projetos estilo SDK no Visual Studio. Se seu objetivo for um projeto estilo não SDK (normalmente .NET Framework), migre o projeto ou consulte Criar e publicar um pacote do .NET Framework para obter instruções passo a passo.

   

3. Para pacotes compilados para consumo público, preste atenção especial à propriedade Tags, à medida que as marcas ajudam outras pessoas a localizar o pacote e entender o que ele faz.

4. Dê ao seu pacote um ID de pacote exclusivo e preencha as outras propriedades desejadas. Para ver uma tabela que mostre como as propriedades do MSBuild (projeto estilo SDK) são mapeadas em um arquivo .nuspec, consulte destinos do pacote. Para obter uma descrição das propriedades do arquivo .nuspec, consulte a referência do arquivo .nuspec. Todas essas propriedades vão para o manifesto .nuspec criado pelo Visual Studio para o projeto.

   Importante

   Você precisa dar ao pacote um identificador exclusivo em nuget.org ou qualquer host que você esteja usando. Caso contrário, ocorrerá um erro. Para este início rápido, recomendamos incluir Exemplo ou Teste no nome, pois a etapa de publicação torna o pacote visível publicamente.

5. (Opcional) Para ver as propriedades diretamente no arquivo de projeto AppLogger.csproj, selecione Projeto>Editar arquivo de projeto.

   A guia AppLogger.csproj é carregada.

   Essa opção está disponível a partir do Visual Studio 2017 para projetos que usam o atributo estilo SDK. Para versões anteriores do Visual Studio, você deve selecionar Projeto>Descarregar projeto antes de editar o arquivo de projeto.

Executar o comando pack

Para criar um pacote NuGet a partir do seu projeto, siga estas etapas:

1. Selecione Compilar>Gerenciador de Configuração e defina a Configuração da solução ativa como Release.

2. Selecione o projeto AppLogger no Gerenciador de Soluções e selecione Pacote.

   O Visual Studio compila o projeto e cria o arquivo .nupkg.

3. Examine a janela Saída para obter detalhes, os quais contêm o caminho até o arquivo do pacote. Neste exemplo, o assembly compilado está em bin\Release\net6.0 como convém a um destino do .NET 6.0:

   1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
   1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
   1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   

4. Se você não vir o comando Pack no menu, seu projeto provavelmente não será um projeto estilo SDK e você precisará usar a CLI do NuGet. Ou migre o projeto e use a CLI do .NET ou consulte Criar e publicar um pacote do .NET Framework para obter instruções passo a passo.

(Opcional) Gerar pacote ao compilar

Você pode configurar o Visual Studio para gerar automaticamente o pacote NuGet ao compilar o projeto:

1. Selecione seu projeto no Gerenciador de Soluções e, em seguida, selecione Projeto>Propriedades de <nome do projeto>, onde <nome do projeto> é o nome do seu projeto (nese caso, AppLogger).

2. Expanda o nó Pacote, selecione Geral e, em seguida, selecione Gerar pacote NuGet na compilação.

   

(Opcional) Empacotar com MSBuild

Como uma alternativa ao uso do comando de menu Pack, o NuGet 4.x+ e o MSBuild 15.1+ são compatíveis com um destino pack quando o projeto contém os dados do pacote necessários:

1. Com o projeto aberto no Gerenciador de Soluções, abra um prompt de comando selecionando Ferramentas>Linha de Comando>Prompt de Comando do Desenvolvedor.

   O prompt de comando é aberto no diretório do projeto.

2. Execute o seguinte comando: msbuild -t:pack.

Para saber mais, confira Criar um pacote usando MSBuild.

Publicar o pacote

Após criar um arquivo .nupkg, publique-o em nuget.org usando a CLI do .NET ou a CLI do NuGet juntamente com uma chave de API adquirida em nuget.org.

Adquirir a chave de sua API

Antes de publicar seu pacote NuGet, crie uma chave de API:

1. Entre em sua conta de nuget.org ou crie uma conta caso ainda não tenha uma.

2. Selecione seu nome de usuário no canto superior direito e selecione Chaves de API.

3. Selecione Criar e forneça um nome para sua chave.

4. Em Selecionar Escopos, selecione Push.

5. Em Selecionar Pacotes>Padrão Glob, insira *.

6. Selecione Criar.

7. Selecione Copiar para copiar a nova chave.

   

Os Escopos permitem criar chaves de API separadas para finalidades diferentes. Cada chave tem um período de expiração e pode ter o escopo definido para pacotes ou padrões glob específicos. Você também define o escopo de cada chave para operações específicas: enviar novos pacotes e versões de pacotes, enviar por push apenas novas versões de pacotes ou remover da lista.

Por meio de escopo, é possível criar chaves de API para diferentes pessoas que gerenciam os pacotes para a sua organização, de modo que elas tenham somente as permissões necessárias.

Para saber mais, confira Chaves de API com escopo.

Publicar com a CLI do .NET ou a CLI do NuGet

Cada uma das ferramentas de CLI a seguir permite enviar um pacote por push para o servidor e publicá-lo. Selecione a guia para sua ferramenta de CLI, CLI do .NET ou CLI do NuGet.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Erros de publicação

Os erros do comando push geralmente indicam o problema. Por exemplo, talvez você tenha esquecido de atualizar o número de versão em seu projeto e, portanto, está tentando publicar um pacote que já existe.

Você também verá erros se sua chave de API for inválida ou tiver expirado, ou se você tentar publicar um pacote usando um identificador que já existe no host. Suponha, por exemplo, que o identificador AppLogger-test já exista em nuget.org. Se você tentar publicar um pacote com esse identificador, o comando push resultará no seguinte erro:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Se você receber esse erro, verifique se está usando uma chave de API válida que ainda não expirou. Se estiver, o erro indicará que o identificador do pacote já existe no host. Para corrigir o erro, altere o identificador do pacote para torná-lo único, recompile o projeto, recrie o arquivo .nupkg e tente novamente o comando push.

Gerenciar o pacote publicado

Quando seu pacote for publicado com êxito, você receberá um e-mail de confirmação. Para ver o pacote que você acabou de publicar, em nuget.org, selecione seu nome de usuário no canto superior direito e selecione Gerenciar pacotes.

Você acabou de publicar um pacote NuGet em nuget.org, o qual pode ser usado por outros desenvolvedores podem usar em seus próprios projetos.

Se você criou um pacote que não é útil (como este pacote de exemplo que foi criado com uma biblioteca de classes vazia) ou decidiu que não deseja que o pacote fique visível, você poderá remover o pacote da lista para ocultá-lo dos resultados da pesquisa:

1. Depois que o pacote aparecer em Pacotes Publicados na página Gerenciar Pacotes, selecione o ícone de lápis ao lado da listagem de pacotes.

   

2. Na próxima página, selecione Listagem, desmarque a caixa de seleção Listar nos resultados da pesquisa e selecione Salvar.

   

O pacote agora aparece em Pacotes não listados em Gerenciar pacotes e não aparece mais nos resultados da pesquisa.

Adicione um Leiame ou outro arquivo

Para especificar diretamente os arquivos a serem incluídos no pacote, edite o arquivo de projeto e adicione a propriedade content:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

Neste exemplo, a propriedade especifica um arquivo chamado readme.txt na raiz do projeto. O Visual Studio exibe o conteúdo do arquivo como texto sem formatação imediatamente após instalar o pacote. Arquivos Leiame não são exibidos para pacotes instalados como dependências. Por exemplo, este é o arquivo Leiame para o pacote HtmlAgilityPack:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Vídeo relacionado

Encontre mais vídeos sobre o NuGet no Channel 9 e no YouTube.

Parabéns por criar um pacote NuGet usando uma biblioteca de classes do Visual Studio .NET. Avance para o próximo artigo para saber como criar um pacote NuGet com o Visual Studio .NET Framework.

Para explorar mais o que o NuGet tem a oferecer, consulte os seguintes artigos:

• Criar um pacote NuGet
• Publicar um pacote
• Compilar um pacote de pré-lançamento
• Suporte a várias versões do .NET Framework
• Controle de versão do pacote
• Criar pacotes NuGet localizados
• Portabilidade para o .NET Core do .NET Framework