Trabalhando com o registro NuGet

Quem pode usar esse recurso?

O Packages está disponível com Free, Pro, Free para organizações, Team, Enterprise Cloud e Enterprise Server 3.0 ou superior.
O Packages não está disponível para repositórios privados de contas que utilizam planos antigos por-repositório. Além disso, as contas que usam planos herdados por repositório não podem acessar registros que oferecem suporte a permissões granulares, pois essas contas são cobradas por repositório. Para obter a lista de registros que oferecem suporte a permissões granulares, confira Sobre permissões para o Packages. Para saber mais, confira Planos do .

Neste artigo

Observação

O Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

Você precisa de um token de acesso para publicar, instalar e excluir pacotes privados, públicos e internos.

Você pode usar um personal access token (classic) para se autenticar no Packages ou na API do . Ao criar um personal access token (classic), você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para personal access token (classic), confira Sobre permissões para o Packages.

Para efetuar a autenticação em um registro do Packages dentro de um fluxo de trabalho de Actions, você pode utilizar:

  • _TOKEN para publicar pacotes associados ao repositório do fluxo de trabalho.
  • Um personal access token (classic) com pelo menos escopo read:packages para instalar pacotes associados a outros repositórios privados (_TOKEN pode ser usado se o repositório receber acesso de leitura ao pacote. Confira, Configurando o controle de acesso e visibilidade de um pacote).

Esse registro dá suporte a permissões granulares. Para registros que dão suporte a permissões granulares, se seu fluxo de trabalho Actions estiver usando um personal access token para autenticar em um registro, será altamente recomendável que você atualize seu fluxo de trabalho de modo que ele use o _TOKEN. Para obter diretrizes sobre como atualizar seus fluxos de trabalho que são autenticados em um registro com um personal access token, confira Publicar e instalar um pacote no Actions.

Observação

A capacidade dos fluxos de trabalho do Actions de excluir e restaurar pacotes usando a API REST está em versão prévia pública e está sujeita a alterações.

Você poderá usar um _TOKEN em um fluxo de trabalho do Actions para excluir ou restaurar pacotes usando a API REST, se o token tiver permissão de admin ao pacote. Repositórios que publicam pacotes usando um fluxo de trabalho e repositórios conectados explicitamente a pacotes recebem permissão admin para pacotes no repositório automaticamente.

Para obter mais informações sobre _TOKEN, confira Autenticação automática de token. Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira Fortalecimento de segurança para o Actions.

Use o seguinte comando para autenticar o Packages em um fluxo de trabalho do Actions usando o _TOKEN em vez de codificar um personal access token em um arquivo nuget.config no repositório:

dotnet nuget add source --username USERNAME --password ${{ secrets._TOKEN }} --store-password-in-clear-text --name  "https://nuget.pkg..com/NAMESPACE/index.json"

Substitua NAMESPACE pelo nome da conta pessoal ou organização a qual seus pacotes têm escopo definido.

Substitua USERNAME pelo nome de usuário a ser usado ao se conectar a uma fonte autenticada.

Também é possível optar por conceder permissões de acesso a pacotes de maneira independente para Codespaces e Actions. Para saber mais, confira Configurando o controle de acesso e visibilidade de um pacote e Configurando o controle de acesso e visibilidade de um pacote.

Observação

O Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

Você precisa de um token de acesso para publicar, instalar e excluir pacotes privados, públicos e internos.

Você pode usar um personal access token (classic) para se autenticar no Packages ou na API do . Ao criar um personal access token (classic), você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para personal access token (classic), confira Sobre permissões para o Packages.

Para efetuar a autenticação em um registro do Packages dentro de um fluxo de trabalho de Actions, você pode utilizar:

  • _TOKEN para publicar pacotes associados ao repositório do fluxo de trabalho.
  • Um personal access token (classic) com pelo menos escopo read:packages para instalar pacotes associados a outros repositórios privados (_TOKEN pode ser usado se o repositório receber acesso de leitura ao pacote. Confira, Configurando o controle de acesso e visibilidade de um pacote).

Você precisa usar um personal access token (classic) com os escopos apropriados para publicar e instalar pacotes no Packages. Para saber mais, confira Introdução ao Packages.

Para se autenticar no Packages com a CLI (interface de linha de comando) do dotnet, crie um arquivo nuget.config no diretório do projeto especificando o Packages como uma fonte em packageSources para o cliente da CLI do dotnet.

Você deve substituir:

  • USERNAME com o nome de sua conta de usuário em .
  • TOKEN com seu personal access token (classic).
  • NAMESPACE pelo nome da conta pessoal ou organização a qual seus pacotes têm escopo definido.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="" value="https://nuget.pkg..com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </>
    </packageSourceCredentials>
</configuration>

Observação

O arquivo nupkg para uma versão do pacote NuGet deve ter o tamanho menor que 2,147 GB.

Você pode publicar um pacote no Packages autenticando-se com um arquivo nuget.config, usando a opção de linha de comando do --api-key com seu personal access token (classic) ou usando um comando que possa ser executado diretamente da linha de comando usando a interface de linha de comando (CLI) do dotnet.

Substitua OWNER pelo seu nome de usuário ou nome da empresa e YOUR__PAT pelo seu personal access token.

dotnet nuget add source --username OWNER --password YOUR__PAT --store-password-in-clear-text --name  "https://nuget.pkg..com/OWNER/index.json"

O registro do NuGet armazena pacotes em sua organização ou conta pessoal e permite que você associe pacotes a um repositório. Você pode escolher se deve herdar permissões de um repositório ou definir permissões granulares, independentemente de um repositório.

Ao publicar um pacote pela primeira vez a visibilidade-padrão será privada. Para mudar a visibilidade ou definir permissões de acesso, confira Configurando o controle de acesso e visibilidade de um pacote. Para obter mais informações sobre como vincular um pacote publicado a um repositório, confira Conectar um repositório a um pacote.

Se você especificar RepositoryURL no arquivo .csproj do seu projeto, o pacote publicado será automaticamente conectado ao repositório especificado. Para saber mais, confira Trabalhando com o registro NuGet. Para obter mais informações sobre como vincular um pacote já publicado a um repositório, confira Conectar um repositório a um pacote.

Se você ainda não tem um personal access token para usar em sua conta no , confira Gerenciar seus tokens de acesso pessoal.

  1. Criar um novo projeto. Substitua PROJECT_NAME pelo nome que deseja dar ao projeto.

    dotnet new console --name PROJECT_NAME

  2. Empacotar o projeto.

    dotnet pack --configuration Release

  3. Publicar o pacote usando seu personal access token como a chave de API. Substitua PROJECT_NAME pelo nome do projeto, 1.0.0 pelo número de versão do pacote e YOUR__PAT pelo seu personal access token.

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --api-key YOUR__PAT --source ""

Após publicar um pacote, você poderá visualizá-lo no . Para saber mais, confira Visualizar pacotes.

Ao publicar, se você estiver vinculando seu pacote a um repositório, o OWNER do repositório especificado em seu arquivo .csproj deverá corresponder ao NAMESPACE que você usa em seu arquivo de autenticação nuget.config. Especifique ou incremente o número de versão no arquivo .csproj e use o comando dotnet pack para criar um arquivo .nuspec para essa versão. Para obter mais informações sobre como criar seu pacote, confira Criar e publicar um pacote na documentação da Microsoft.

Observação

Se você publicar um pacote vinculado a um repositório, o pacote herdará automaticamente as permissões de acesso do repositório vinculado e os fluxos de trabalho do Actions no repositório vinculado obterão automaticamente acesso ao pacote, a menos que a sua organização tenha desabilitado a herança automática das permissões de acesso. Para saber mais, confira Configurando o controle de acesso e visibilidade de um pacote.

  1. Autenticar para Packages. Para saber mais, confira Autenticação no Packages.

  2. Criar um novo projeto. Substitua PROJECT_NAME pelo nome que deseja dar ao projeto.

    dotnet new console --name PROJECT_NAME

  3. Adicione informações específicas do seu projeto ao arquivo do projeto, que termina com .csproj. Substitua:

    • 1.0.0 pelo número de versão do pacote.
    • OWNER pelo nome da conta pessoal ou organização que é proprietário do repositório ao qual você deseja vincular seu pacote.
    • REPOSITORY pelo nome do repositório ao qual você deseja conectar seu pacote.
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>PROJECT_NAME</PackageId>
    <Version>1.0.0</Version>
    <Authors>AUTHORS</Authors>
    <Company>COMPANY_NAME</Company>
    <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>
    <RepositoryUrl>https://.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  4. Empacotar o projeto.

    dotnet pack --configuration Release

  5. Publique o pacote usando a key que você especificou no arquivo nuget.config. Substitua PROJECT_NAME pelo nome do projeto e 1.0.0 pelo número de versão do pacote.

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source ""

Após publicar um pacote, você poderá visualizá-lo no . Para saber mais, confira Visualizar pacotes.

Para conectar vários pacotes ao mesmo repositório, use a mesma URL de repositório do nos campos RepositoryURL em todos os arquivos de projeto .csproj. O corresponde ao repositório baseado nesse campo.

O seguinte exemplo publica os projetos MY_APP e MY_OTHER_APP no mesmo repositório:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company></Company>
    <PackageDescription>This package adds a singing Octocat!</PackageDescription>
    <RepositoryUrl>https://.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_OTHER_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company></Company>
    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>
    <RepositoryUrl>https://.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

O uso de pacotes do no projeto é semelhante ao uso de pacotes de nuget.org. Adicione as dependências do pacote ao arquivo .csproj especificando o nome e a versão do pacote. Para obter mais informações sobre como usar um arquivo .csproj no seu projeto, confira Como trabalhar com pacotes NuGet na documentação da Microsoft.

  1. Autenticar para Packages. Para saber mais, confira Autenticação no Packages.

  2. Para usar um pacote, adicione ItemGroup e configure o campo PackageReference no arquivo de projeto .csproj. Substitua o valor PACKAGE_NAME em Include="PACKAGE_NAME" por sua dependência de pacote, e o valor X.X.X em Version="X.X.X" pela versão do pacote que deseja usar:

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>My-app</PackageId>
    <Version>1.0.0</Version>
   <Authors>Octocat</Authors>
    <Company></Company>
   <PackageDescription>This package adds an Octocat!</PackageDescription>
    <RepositoryUrl>https://.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

  3. Instale os pacotes com o comando restore.

    dotnet restore

Se você estiver usando um _TOKEN para autenticação em um registro Packages em um fluxo de trabalho Actions, o token não poderá acessar pacotes baseados em repositório privado em um repositório diferente de onde o fluxo de trabalho está sendo executado. Para acessar pacotes associados a outros repositórios, em vez disso, gere um personal access token (classic) com o escopo read:packages e passe esse token como um segredo.