Início rápido: Crie e publique um pacote com a CLI dotnet

Este quickstart mostra-lhe como criar rapidamente um pacote NuGet a partir de uma biblioteca de classes .NET e publicá-lo para nuget.org usando a interface de linha de comandos .NET, ou dotnet CLI.

Pré-requisitos

  • O SDK .NET, que fornece a ferramenta de linha de comandos dotnet. A partir do Visual Studio 2017, a CLI dotnet instala-se automaticamente com quaisquer cargas de trabalho relacionadas com .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

Pode usar um projeto existente de Biblioteca de Classes .NET para o código que pretende empacotar, ou criar um projeto simples da seguinte forma:

  1. Cria uma pasta chamada AppLogger.
  2. Abre um prompt de comandos e muda para a pasta AppLogger . Todos os comandos dotnet CLI neste quickstart são executados na pasta atual por padrão.
  3. Insira dotnet new classlib, que cria um projeto com o nome atual da pasta.

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

Adicionar metadados do pacote ao ficheiro do projeto

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

Abra o ficheiro do projeto .csproj, .fsproj ou .vbproj e adicione as seguintes propriedades dentro da etiqueta existente <PropertyGroup> . Use os seus próprios valores para nome e empresa, e substitua o identificador da encomenda por um valor único.

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

Importante

O identificador da embalagem deve ser único entre nuget.org e outras fontes de encomenda. Publicar torna o pacote visível publicamente, por isso, se usar a biblioteca AppLogger de exemplo ou outra biblioteca de teste, use um nome único que inclua Sample ou Test.

Pode adicionar quaisquer propriedades opcionais descritas nas propriedades dos metadados NuGet.

Note

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

Executar o comando pack

Para construir um pacote NuGet ou ficheiro .nupkg a partir do projeto, execute o comando dotnet pack , que também constrói 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 correr dotnet pack automaticamente sempre que executar dotnet build, adicione a seguinte linha ao ficheiro do seu projeto dentro de <PropertyGroup>:

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Publicar o pacote

Publica o teu ficheiro .nupkg para nuget.org usando o comando dotnet nuget push com uma chave API que recebes da nuget.org.

Note

  • Nuget.org analisa todos os pacotes carregados à procura de vírus e rejeita quaisquer pacotes que contenham vírus. Nuget.org também analisa periodicamente todos os pacotes listados existentes.

  • Os pacotes que publicas para nuget.org são publicamente visíveis para outros programadores, a menos que os deslistes. Para alojar pacotes de forma privada, consulte Hospedar os seus próprios feeds NuGet.

Obtenha sua chave de API

  1. Inicie sessão na sua conta nuget.org ou crie uma conta se ainda não tiver uma.

  2. No canto superior direito, selecione o seu nome de utilizador e depois selecione Chaves API.

  3. Selecione Criar e depois introduza um nome para a sua chave.

  4. Em Selecione escopos, selecione Push.

  5. Em Select Packages, para Glob Pattern, insira um asterisco (*).

  6. Selecione Criar.

  7. Selecione Copiar para copiar a nova chave.

    Captura de ecrã de uma página nuget.org que mostra a nova chave da API, uma mensagem sobre copiar a chave agora e o botão Copiar, que está destacado.

Importante

  • Mantenha sempre a sua chave API em segredo. A chave API é como uma palavra-passe que qualquer pessoa pode usar para gerir pacotes em seu nome. Exclua ou regenere sua chave de API se ela for revelada acidentalmente.
  • Guarde a sua chave num local seguro, porque não pode copiá-la novamente mais tarde. Se você retornar à página de chave da API, precisará gerar novamente a chave para copiá-la. Você também pode remover a chave da API se não quiser mais enviar pacotes.

O scoping permite criar chaves de API separadas para diferentes fins. Cada chave tem um período de expiração, e podes atribuir a chave a pacotes específicos ou padrões de globos. Você também define o escopo de cada chave para operações específicas: envie novos pacotes e versões de pacotes, envie apenas novas versões de pacotes ou cancele a lista.

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

Para mais informações, consulte Chaves API Restringidas.

Publicar com dotnet nuget push

Na pasta que contém o arquivo .nupkg , execute o seguinte comando. Substitui <package-file> pelo nome do ficheiro .nupkg e substitui <API-key> pela tua chave 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.

Erros de publicação

Quando executas o push comando, por vezes encontras um erro. Por exemplo, pode receber um erro nas seguintes situações:

  • A tua chave API é inválida ou expirada.
  • Tentas publicar um pacote que tenha um identificador que já existe no host.
  • Fazes alterações a um pacote publicado, mas esqueces-te de atualizar o número de versão antes de tentares publicá-lo novamente.

A mensagem de erro indica tipicamente a origem do problema.

Por exemplo, suponha que o identificador Contoso.App.Logger.Test existe em nuget.org. Se tentar publicar um pacote com esse identificador, obtém 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 esta situação, verifique o âmbito, a data de expiração e o valor da sua chave API. Se a chave for válida, o erro indica que o identificador do pacote já existe no host. Para ultrapassar o problema, altere o identificador do pacote para ser único, reconstrua o projeto, recrie o ficheiro .nupkg e tente novamente o push comando.

Gerir o pacote publicado

Quando o seu pacote é publicado com sucesso, recebe um email de confirmação. Para ver o pacote publicado, vá a nuget.org, selecione o seu nome de utilizador no canto superior direito e depois selecione Gerir Pacotes.

Note

Pode demorar algum tempo até o seu pacote ser indexado e aparecer nos resultados de pesquisa onde outros o possam encontrar. Durante esse tempo, a sua encomenda aparece em Pacotes Não Listados, e a página da encomenda mostra a seguinte mensagem:

Captura de ecrã de uma mensagem de aviso nuget.org sobre o pacote ainda não ter sido publicado. O texto afirma que a validação e a indexação podem demorar uma hora.

Agora que o seu pacote NuGet foi publicado em nuget.org, outros programadores podem usá-lo nos seus projetos.

Se criares um pacote que não é útil (como este pacote de exemplo de uma biblioteca de classes vazia), ou se não quiseres que o pacote seja visível, podes deslistar o pacote para o esconder dos resultados de pesquisa:

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

    Captura de ecrã da página nuget.org Pacotes. A secção de Pacotes Publicados lista um pacote. O ícone de edição está destacado.

  2. Na página seguinte, selecione Listagem, elimine a caixa Lista nos resultados de pesquisa e depois selecione Guardar.

    Captura de ecrã de uma página nuget.org. Na secção de Listagem, a opção para listar o pacote nos resultados de pesquisa está destacada.

O pacote agora aparece em Pacotes Não Listados em Gerir Pacotes e já não aparece nos resultados de pesquisa.

Note

Para evitar que o seu pacote de teste fique ativo no nuget.org, pode enviá-lo para o site de teste nuget.org em https://int.nugettest.org. Note que os pacotes carregados para o site de teste int.nugettest.org podem não ser preservados.

Parabéns por criares e publicares o teu primeiro pacote NuGet!

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

Passos seguintes

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

Criar um pacote NuGet com a CLI dotnet

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

  • Last updated on