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

Com Microsoft Visual Studio, podes criar um pacote NuGet a partir de uma biblioteca de classes .NET Framework e depois publicá-lo para nuget.org usando a ferramenta CLI NuGet.

O quickstart é apenas para utilizadores de Windows. Se estiveres a usar Visual Studio para Mac, vê dotnet CLI tools em vez disso.

Pré-requisitos

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

  Você pode instalar a edição Community 2022 gratuitamente a partir do visualstudio.microsoft.comou usar a edição Professional ou Enterprise.

  O Visual Studio 2017 e superiores inclui automaticamente capacidades NuGet quando uma carga de trabalho .NET é instalada.

• Registe-se para obter uma conta gratuita no nuget.org se ainda não tiver uma. Você deve se registrar e confirmar a conta antes de carregar um pacote NuGet.

• Instala a CLI NuGet descarregando-a do nuget.org. Adicione o ficheironuget.exe a 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 turmas, siga estes passos:

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

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

3. Na lista resultante de modelos de projeto, selecione Class Library (.NET Framework) e depois selecione Next.

4. Na janela Configurar o seu novo projeto, introduza AppLogger para o nome do projeto, e depois selecione Criar.

5. Para garantir que o projeto foi criado corretamente, selecione Build>Build Solution. A DLL encontra-se na pasta Debug (ou Release, se construir essa configuração em vez disso).

6. (Opcional) Para este início rápido, não precisa de escrever código adicional para o pacote NuGet porque a biblioteca de classes fornecida pelo modelo é suficiente para criar um pacote. No entanto, se 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);
           }
       }
   }
   

   Num pacote NuGet do mundo real, provavelmente implementarias muitas funcionalidades úteis com as quais outros podem construir aplicações. Também podes definir os frameworks-alvo. Para um exemplo, veja UWP.

Configurar as propriedades do projeto para o pacote

Um pacote NuGet inclui um manifesto (um .nuspec ficheiro), que contém metadados relevantes como o identificador do pacote, número de versão, descrição e mais. Alguns destes metadados podem ser retirados diretamente das propriedades do projeto, o que evita a necessidade de os atualizar separadamente tanto no projeto como no manifesto. Os passos seguintes descrevem como definir as propriedades aplicáveis:

1. Selecione Project > Propriedades e depois selecione o separador Application.

2. Para Assembly name, dê ao seu pacote um identificador único. Se tentar publicar um pacote com um nome que já existe, verá um erro.

   Importante

   Deve dar ao pacote um identificador que seja único num contexto global em nuget.org ou em qualquer outro host que esteja a usar. Caso contrário, ocorre um erro. Para este quickstart, recomendamos incluir Sample ou Test no nome, pois a etapa de publicação torna o pacote visível publicamente.

3. Selecione Informação de Montagem, que apresenta uma caixa de diálogo onde pode introduzir outras propriedades que são transferidas para o manifesto (ver Tokens de substituição). Os campos mais usados são Título, Descrição, Empresa, Direitos de Autor e Versão Assembly. Como estas propriedades aparecem com o seu pacote num alojamento como nuget.org depois de o publicar, certifique-se de que são totalmente descritivas.

   

4. (Opcional) Para ver e editar diretamente as propriedades, abra o ficheiro Properties/AssemblyInfo.cs no projeto ao selecionar Project>Editar Ficheiro do Projeto.

5. Depois de definires estas propriedades, define a configuração da solução Ativa em Build>Configuration Manager para Release e reconstrói o projeto para gerar a DLL atualizada.

Gerar o manifesto inicial

Depois de definir as propriedades do projeto e criar a DLL, pode agora gerar um ficheiro .nuspec inicial a partir do projeto. Esta etapa inclui os tokens de substituição apropriados para extrair informações do arquivo do projeto.

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

1. Com o seu projeto aberto em Solution Explorer, abra um prompt de comandos selecionando Tools>Command Line>Developer Command Prompt.

   O prompt de comandos abre-se no diretório do projeto onde o AppLogger.csproj ficheiro está localizado.

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

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

3. Abra AppLogger.nuspec num editor de texto para examinar o 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 seguintes propriedades antes de prosseguir. Caso contrário, se tentar criar um pacote NuGet com os valores predefinidos no seu .nuspec ficheiro, ocorre um erro. Para informações sobre estas propriedades, veja Elementos opcionais de metadados:

   • licenseUrl
   • projectUrl
   • notas de versão
   • etiquetas

2. Para pacotes criados para consumo público, preste especial atenção à propriedade Etiquetas , pois as etiquetas ajudam outros a encontrar o seu pacote e a perceber o que ele faz.

3. Também pode adicionar quaisquer outros elementos ao manifesto neste momento, conforme descrito na referência do ficheiro .nuspec.

4. Guarde o ficheiro antes de prosseguir.

Executar o comando pack

1. Com o seu projeto aberto em Solution Explorer, abra um prompt de comandos selecionando Tools>Command Line>Developer Command Prompt.

   O prompt de comandos abre-se no diretório do teu projeto.

2. Execute o seguinte comando: nuget pack.

   O NuGet gera um ficheiro .nupkg sob a forma de identifier.version.nupkg na pasta atual.

Publicar o pacote

Depois de criar um ficheiro .nupkg , publique-o para nuget.org usando a CLI NuGet com uma chave API adquirida da nuget.org. Para nuget.org, deve usar nuget.exe a 4.1.0 ou superior.

Se quiseres testar e validar o teu pacote antes de o publicar numa galeria pública, podes carregá-lo num ambiente de teste como o int.nugettest.org em vez de nuget.org. Note que os pacotes carregados para int.nugettest.org podem não ser preservados.

Adquira a sua chave 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.

   

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 a CLI do NuGet

Usar a CLI NuGet (nuget.exe) é uma alternativa à utilização da CLI .NET:

1. Abre um prompt de comandos e muda para a pasta que contém o ficheiro .nupkg .

2. Execute o seguinte comando. Substitua <o nome> do ficheiro do pacote pelo nome do ficheiro do seu pacote e substitua <o valor> da chave API pela sua chave API. O nome do ficheiro do pacote é uma concatenação do ID do pacote e do número de 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 é apresentado 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 mais informações, consulte 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.

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.

   

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

   

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

Passos seguintes

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

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

• Publicar um pacote
• Construir um pacote de pré-lançamento
• Suporte para múltiplos frameworks alvo
• Controle de versão do pacote
• Criação de um pacote localizado