Início Rápido: Criar e publicar um pacote com a CLI do dotnet

Este guia de início rápido mostra como criar rapidamente um pacote NuGet de uma biblioteca de classes .NET e publicá-lo no nuget.org usando a interface de linha de comando .NET ou dotnet CLI.

Pré-requisitos

  • O SDK .NET, que fornece a ferramenta de linha de comando dotnet. A partir do Visual Studio 2017, a CLI do dotnet é instalada automaticamente com qualquer pacote de trabalho relacionado a .NET ou .NET Core.

  • Uma conta gratuita no nuget.org. Siga as instruções em Adicionar uma nova conta individual.

Criar um projeto de biblioteca de classes

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

  1. Crie uma pasta chamada AppLogger.
  2. Abra um prompt de comando e alterne para a pasta AppLogger . Todos os comandos da CLI do dotnet neste início rápido são executados na pasta atual por padrão.
  3. Insira dotnet new classlib, que cria um projeto com o nome da pasta atual.

Para obter mais informações, consulte dotnet new.

Adicionar metadados de pacote ao arquivo de projeto

Cada pacote NuGet tem um manifesto que descreve o conteúdo e as dependências do pacote. No pacote final, o manifesto é um arquivo .nuspec , que usa as propriedades de metadados do NuGet que você inclui no arquivo de projeto.

Abra o arquivo de projeto .csproj, .fsproj ou .vbproj e adicione as seguintes propriedades dentro da marca existente <PropertyGroup> . Use seus próprios valores para nome e empresa e substitua o identificador de pacote por um valor exclusivo.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Important

O identificador do pacote deve ser exclusivo entre nuget.org e outras fontes de pacote. A publicação torna o pacote publicamente visível, portanto, se você usar a biblioteca AppLogger de exemplo ou outra biblioteca de teste, use um nome exclusivo que inclua Sample ou Test.

Você pode adicionar quaisquer propriedades opcionais descritas nas propriedades de metadados do NuGet.

Observação

Para pacotes que você cria para consumo público, preste atenção especial à PackageTags propriedade. Tags ajudam outras pessoas a encontrar seu pacote e entender o que ele faz.

Executar o comando pack

Para criar um pacote NuGet ou um arquivo .nupkg do projeto, execute o comando dotnet pack , 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 C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

Gerar automaticamente o pacote na compilação

Para executar dotnet pack automaticamente sempre que você executar dotnet build, adicione a seguinte linha ao arquivo de projeto em <PropertyGroup>:

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Publicar o pacote

Publique seu arquivo .nupkg para nuget.org usando o comando push do dotnet nuget com uma chave de API que você obtém de nuget.org.

Observação

  • Nuget.org examina todos os pacotes carregados em busca de vírus e rejeita todos os pacotes que contêm vírus. Nuget.org também verifica todos os pacotes listados existentes periodicamente.

  • Os pacotes publicados em nuget.org são publicamente visíveis para outros desenvolvedores, a menos que você os desliste. Para hospedar pacotes privadamente, consulte como hospedar seus próprios feeds do NuGet.

Obter sua chave de API

  1. Entre em sua conta nuget.org ou crie uma conta se você ainda não tiver uma.

  2. No canto superior direito, selecione o nome de usuário e, em seguida, selecione Chaves de API.

  3. Selecione Criar e, em seguida, insira um nome para sua chave.

  4. Em Selecionar Escopos, selecione Push.

  5. Em Selecionar Pacotes, para Padrão Glob, insira um asterisco (*).

  6. Selecione Criar.

  7. Selecione Copiar para copiar a nova chave.

    Captura de tela de uma página nuget.org que mostra a nova chave de API, uma mensagem sobre como copiar a chave agora e o botão Copiar, que está realçado.

Important

  • Sempre mantenha sua chave de API em segredo. A chave de API é como uma senha que qualquer pessoa pode usar para gerenciar pacotes em seu nome. Exclua ou regenere sua chave de API se ela for revelada acidentalmente.
  • Salve sua chave em um local seguro, pois não é possível copiar a chave novamente mais tarde. Se você retornar à página de chave da API, será necessário regenerar a chave para copiá-la. Você também pode remover a chave de API se não quiser mais enviar pacotes por push.

Escopo fornece uma maneira de criar chaves de API separadas para diferentes propósitos. Cada chave tem um período de expiração e você pode definir o escopo da chave para pacotes específicos ou padrões globais. Você também define o escopo de cada chave para operações específicas: fazer push de novos pacotes e versões de pacotes, fazer push apenas de novas versões de pacotes ou remover da lista.

Por meio do escopo, você pode criar chaves de API para diferentes pessoas que gerenciam pacotes para sua organização para que tenham apenas as permissões necessárias.

Para obter mais informações, consulte chaves de API restritas.

Publicar com envio do dotnet nuget

Na pasta que contém o arquivo .nupkg , execute o comando a seguir. Substitua <package-file> pelo nome do arquivo .nupkg e substitua pela <API-key> chave de API.

dotnet nuget push <package-file> --api-key <API-key> --source https://api.nuget.org/v3/index.json

A saída mostra os resultados do processo de publicação:

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

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

Publicar erros

Ao executar o push comando, às vezes você encontra um erro. Por exemplo, você pode receber um erro nas seguintes situações:

  • Sua chave de API é inválida ou expirou.
  • Você tenta publicar um pacote que tem um identificador que já existe no host.
  • Você faz alterações em um pacote publicado, mas esquece de atualizar o número de versão antes de tentar publicá-lo novamente.

A mensagem de erro normalmente indica a origem do problema.

Por exemplo, suponha que o identificador Contoso.App.Logger.Test exista no nuget.org. Se você tentar publicar um pacote com esse identificador, receberá o 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.).

Para resolver essa situação, verifique o escopo, a data de validade e o valor da chave de API. Se a chave for válida, o erro indicará que o identificador do pacote já existe no host. Para superar o problema, altere o identificador do pacote para ser exclusivo, recompile o projeto, recrie o arquivo .nupkg e repita o push comando.

Gerenciar o pacote publicado

Quando o pacote for publicado com êxito, você receberá um email de confirmação. Para ver o pacote publicado, vá para nuget.org, selecione o nome de usuário no canto superior direito e selecione Gerenciar Pacotes.

Observação

Pode demorar um pouco para que o pacote seja indexado e apareça nos resultados da pesquisa em que outras pessoas possam encontrá-lo. Durante esse tempo, seu pacote aparece em Pacotes Não Listados e a página do pacote mostra a seguinte mensagem:

Captura de tela de uma mensagem de aviso nuget.org sobre o pacote que ainda não foi publicado. O texto afirma que a validação e a indexação podem levar uma hora.

Agora que seu pacote NuGet é publicado no nuget.org, outros desenvolvedores podem usá-lo em seus projetos.

Se você criar um pacote que não seja útil (como este pacote de exemplo de uma biblioteca de classes vazia) ou se não quiser que o pacote fique visível, você poderá deslistar o pacote para ocultá-lo dos resultados da pesquisa:

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

    Captura de tela da página nuget.org Pacotes. A seção Pacotes Publicados lista um pacote. Seu ícone de edição está realçado.

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

    Captura de tela de uma página de nuget.org. Na seção Listagem, a opção para listar o pacote nos resultados da pesquisa é realçada.

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

Observação

Para evitar que o pacote de teste esteja ativo no nuget.org, você pode enviar por push para o site de teste do nuget.org em https://int.nugettest.org. Observe que os pacotes carregados em int.nugettest.org podem não ser preservados.

Parabéns por criar e publicar seu primeiro pacote NuGet!

Encontre mais vídeos do NuGet no Canal 9 e no YouTube.

Próximas Etapas 

Veja mais detalhes sobre como criar pacotes com a CLI do dotnet:

Criar um pacote NuGet com a CLI do dotnet

Obtenha mais informações sobre como criar e publicar pacotes NuGet:

  • Last updated on