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

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

O guia de início rápido destina-se apenas a usuários do Windows. Se você usa o Visual Studio para Mac, consulte Ferramentas de CLI do dotnet.

Pré-requisitos

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

  É 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 e superior incluem automaticamente os recursos do NuGet quando uma carga de trabalho do .NET é instalada.

• 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

Para criar um projeto de biblioteca de classes, siga estas etapas:

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 (.NET Framework) e, em seguida, selecione Avançar.

4. Na caixa de diálogo Configurar novo projeto, digite AppLogger como Nome do projeto e selecione Criar.

5. 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).

6. (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ê quiser algum código funcional para este pacote de exemplo, inclua o seguinte código:

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

   Em um pacote NuGet do mundo real, você provavelmente implementaria muitos recursos úteis com os quais outras pessoas podem compilar aplicativos. Você também poderá definir as estruturas de destino. Para obter exemplos, consulte UWP e Xamarin.

Configurar propriedades do projeto para o pacote

Um pacote NuGet inclui um manifesto (um arquivo .nuspec), que contém metadados relevantes, como o identificador do pacote, o número de versão, a descrição e muito mais. Alguns desses metadados podem ser obtidos diretamente das propriedades do projeto, o que evita a necessidade de atualizá-los separadamente no projeto e no manifesto. As etapas a seguir descrevem como definir as propriedades aplicáveis:

1. Selecione Projeto > Propriedades e, em seguida, selecione a guia Aplicativo.

2. No campo Nome do assembly, atribua um identificador exclusivo ao pacote. Se você tentar publicar um pacote com um nome que já existe, você verá um erro.

   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.

3. Selecione Informações do Assembly para abrir uma caixa de diálogo na qual será possível inserir outras propriedades contidas no manifesto (consulte Tokens de substituição). Os campos mais usados são Título, Descrição, Empresa, Direitos autorais e Versão do assembly. Como essas propriedades aparecem com o pacote em um host como nuget.org após a publicação, certifique-se de que elas sejam totalmente descritivas.

   

4. (Opcional) Para ver e editar as propriedades diretamente, abra o arquivo Properties/AssemblyInfo.cs no projeto selecionando Projeto>Editar arquivo de projeto.

5. Depois de definir essas propriedades, defina a Configuração da solução ativa em Compilar>Gerenciador de configuração como Release e recompile o projeto para gerar a DLL atualizada.

Gerar o manifesto inicial

Depois de definir as propriedades do projeto e criar a DLL, agora você pode gerar um arquivo .nuspec inicial do projeto. Essa etapa inclui os tokens de substituição correspondentes para obter informações do arquivo de projeto.

Execute nuget spec apenas uma vez para gerar o manifesto inicial. Caso atualize o pacote, altere os valores no projeto ou edite o manifesto diretamente:

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 onde o arquivo AppLogger.csproj está localizado.

2. Execute o seguinte comando: nuget spec AppLogger.csproj.

   O NuGet cria um manifesto que corresponde ao nome do projeto, nesse caso AppLogger.nuspec. Ele também inclui os tokens de substituição no manifesto.

3. Abra AppLogger.nuspec em um editor de texto para examinar seu conteúdo, que será semelhante ao seguinte código:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Editar o manifesto

1. Edite as propriedades a seguir antes de continuar. Caso contrário, se você tentar criar um pacote NuGet com os valores padrão no arquivo .nuspec, um erro ocorrerá. Para obter informações sobre essas propriedades, consulte Elementos de metadados opcionais:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • marcas

2. 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.

3. Você também pode adicionar outros elementos ao manifesto nesse momento, conforme descrito em Referência do arquivo .nuspec.

4. Salve o arquivo antes de continuar.

Executar o comando pack

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: nuget pack.

   O NuGet gera um arquivo .nupkg na forma de identifier-version.nupkg na pasta atual.

Publicar o pacote

Depois de criar um arquivo .nupkg, publique-o em nuget.org usando a CLI do NuGet com uma chave de API adquirida de nuget.org. Para nuget.org, você deve usar nuget.exe 4.1.0 ou superior.

Se você quiser testar e validar seu pacote antes de publicá-lo em uma galeria pública, poderá carregá-lo em um ambiente de teste como int.nugettest.org em vez de nuget.org. Observe que os pacotes carregados para int.nugettest.org podem não ser preservados.

Adquirir a chave de sua 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 NuGet

Usar a CLI do NuGet (nuget.exe) é uma alternativa ao uso da CLI do .NET:

1. Abra um prompt de comando e altere para a pasta que contém o arquivo .nupkg.

2. Execute o comando a seguir. Substitua o <nome do arquivo do pacote> pelo nome do pacote e substitua o <valor da chave de API> pela chave de API. O nome do arquivo do pacote é uma concatenação do ID do pacote e do número da versão com uma extensão .nupkg. Por exemplo, AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   O resultado do processo de publicação é exibido da seguinte forma:

   Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
       PUT https://www.nuget.org/api/v2/package/
       Created https://www.nuget.org/api/v2/package/ 6829ms
   Your package was pushed.
   

Para obter mais informações, consulte nuget push.

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.

Próximas etapas

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

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

• Publicar um pacote
• Compilar um pacote de pré-lançamento
• Suporte a várias estruturas de destino
• Controle de versão do pacote
• Criando um pacote localizado