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

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

O início rápido é somente para usuários Windows. Se você estiver usando Visual Studio para Mac, consulte dotnet CLI tools em vez disso.

Pré-requisitos

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

    Você pode instalar a edição Community 2022 gratuitamente de visualstudio.microsoft.comou usar a edição Profissional ou Enterprise.

    Visual Studio 2017 e superior inclui automaticamente os recursos do NuGet quando uma carga de trabalho de .NET é instalada.

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

  • Instale a CLI do NuGet baixando-a de nuget.org. Adicione o arquivo nuget.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 classes, siga estas etapas:

  1. Em Visual Studio, selecione File>New>Project.

  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 selecione Next.

  4. Na janela Configurar seu novo projeto, insira AppLogger para o Nome do projeto e selecione Criar.

  5. Para garantir que o projeto foi criado corretamente, selecione Compilar>Compilar Solução. A DLL é encontrada dentro da pasta Debug (ou Release se você criar essa configuração em vez disso).

  6. (Opcional) Para este 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 implementará muitos recursos úteis com os quais outras pessoas podem criar aplicativos. Você também pode definir os frameworks de destino. Para obter um exemplo, consulte UWP.

Configurar propriedades do projeto para o pacote

Um pacote NuGet inclui um manifesto (um .nuspec arquivo), que contém metadados relevantes, como o identificador do pacote, o número da versão, a descrição e muito mais. Alguns desses metadados podem ser extraídos 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 Project > Properties e selecione a guia Application.

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

    Important

    Você deve fornecer 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 porque a etapa de publicação torna o pacote publicamente visível.

  3. Selecione Informações do Assembly, que exibe uma caixa de diálogo na qual você pode inserir outras propriedades que levam para o 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 seu pacote em um host como nuget.org depois de publicá-lo, verifique se elas são totalmente descritivas.

    Screenshot mostrando a página Informações do Assembly em um projeto do .NET Framework em Visual Studio.

  4. (Opcional) Para ver e editar as propriedades diretamente, abra o arquivo Properties/AssemblyInfo.cs no project selecionando Project>Edit Project File.

  5. Depois de definir essas propriedades, defina a configuração da solução Active em Build>Configuration Manager para Release e recompilar 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. Esta etapa inclui os tokens de substituição relevantes para extrair informações do arquivo de projeto.

Execute nuget spec apenas uma vez para gerar o manifesto inicial. Se você atualizar o pacote, altere os valores em seu projeto ou edite o manifesto diretamente:

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

    O prompt de comando é aberto no diretório do projeto em que o AppLogger.csproj arquivo 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 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 propriedades a seguir antes de continuar. Caso contrário, se você tentar criar um pacote NuGet com os valores padrão em seu .nuspec arquivo, ocorrerá um erro. Para obter informações sobre essas propriedades, consulte elementos de metadados opcionais:

    • URL da licença
    • URL do projeto
    • releaseNotes
    • tags

  2. Para pacotes criados para consumo público, preste atenção especial à propriedade Tags, pois as tags ajudam outras pessoas a encontrar seu pacote e entender o que ele faz.

  3. Você também pode adicionar outros elementos ao manifesto no momento, conforme descrito na referência de arquivo .nuspec.

  4. Salve o arquivo antes de continuar.

Executar o comando pack

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

    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 no 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 em int.nugettest.org podem não ser preservados.

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.

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

Usar a CLI do NuGet (nuget.exe) é uma alternativa ao uso da CLI .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 arquivo do pacote e substitua <o valor> da chave de api pela chave de API. O nome do arquivo do pacote é uma concatenação da 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 é exibido da seguinte maneira:

    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.

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.

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.

Criar um pacote usando a CLI do NuGet

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

  • Last updated on