Mapeamento de origens de pacotes

O mapeamento de origem de pacotes é uma ferramenta que pode ser usada para melhorar a segurança da cadeia de suprimentos, principalmente se você usar uma combinação de origens públicas e privadas de pacotes.

Por padrão, o NuGet pesquisará todas as fontes de pacotes configuradas quando precisar baixar um pacote. Quando um pacote existe em vários códigos-fonte, pode não ser determinístico de qual fonte o pacote será baixado. Com o Mapeamento de Origens de Pacotes, você pode filtrar, por pacote, quais origens o NuGet pesquisará.

Também temos sugestões de outras práticas recomendadas para ajudar você a fortalecer sua cadeia de suprimentos contra ataques.

O Mapeamento de Origem de Pacotes foi adicionado ao NuGet 6.0. A partir do Visual Studio 17.5, você pode adicionar e remover os Mapeamentos de Origem de Pacotes com a caixa de diálogo Opções do Visual Studio.

Suporte do Visual Studio

Visual Studio	Mapeamento de origens de pacotes	Suporte em Ferramentas -> Opções	Suporte na interface do usuário do Gerenciador de Pacotes
17.0 – 17.4	✅ Disponível	❌ Não disponível	❌ Não disponível
17.5	✅ Disponível	✅ Disponível	❌ Não disponível
17.7 Versão Prévia 3	✅ Disponível	✅ Disponível	✅ Status exibido

O recurso está disponível em todas as ferramentas integradas do NuGet.

• Visual Studio 2022 e posterior
• SDK do .NET 6.0.100 e posterior
• nuget.exe 6.0.0 e posterior

As ferramentas mais antigas ignorarão a configuração do Mapeamento de origens de pacotes Para usar esse recurso, certifique-se de que todos os seus ambientes de compilação usem versões de ferramentas compatíveis.

Os mapeamentos de origens de pacotes serão aplicados a todos os tipos de projeto – incluindo o .NET Framework – desde que ferramentas compatíveis sejam usadas.

Passo a passo em vídeo

Para obter uma visão geral baseada em vídeo do recurso Mapeamento de origem de pacotes, considere assistir ao vídeo Proteja seus pacotes NuGet com o mapeamento de origens de pacotes no YouTube.

Habilitando o mapeamento de origens de pacotes

Para ativar esse recurso, você deve ter um arquivo nuget.config. Ter um único nuget.config na raiz do seu repositório é considerado uma melhor prática. Consulte a documentação do nuget.config para saber mais.

Habilitar usando a caixa de diálogo Opções do Visual Studio

1. Abra sua solução no Visual Studio.
2. Navegue até a caixa de diálogo Opções do Package Source Mappings.

Da interface do usuário do Gerenciador de Pacotes

• Selecione um pacote na lista para mostrá-lo no painel Detalhes.
• Pressione o botão Configure para abrir a página de opções de Mapeamentos de Origens de Pacotes.

Na caixa de diálogo Opções do Visual Studio

• Vá para o menu Tools na barra de ferramentas principal do Visual Studio e escolha NuGet Package Manager ->Package Manager Settings.
• Navegue até a página Package Source Mappings.

3. Pressione o botão Add na página Package Source Mappings para abrir a caixa de diálogo Add Package Source Mappings.

4. Insira um ID de Pacote ou Padrão de Pacote e selecione uma ou mais origens de pacotes ativando/desativando a caixa de seleção para suas origens desejadas.

5. A página de opções de Package Source Mapping mostrará o mapeamento de origem recém-criado.

6. Pressione OK na caixa de diálogo Opções para salvar as alterações no nuget.config aplicável.
7. A janela Gerenciador de Pacotes NuGet atualizará e refletirá o novo status dos mapeamentos de origem do pacote selecionado.

Habilitar editando nuget.config manualmente

• Declare as origens de pacotes desejadas em seu arquivo nuget.config.
• Após suas declarações de origem, adicione um elemento <packageSourceMapping> que especifique os mapeamentos desejados para cada origem.
• Declare exatamente um elemento packageSource para cada fonte em uso.
  • Adicione quantos padrões achar necessário.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

As configurações de Mapeamento de Origens de Pacotes são aplicadas seguindo as regras de precedência de nuget.config quando vários arquivos nuget.config em vários níveis (nível de computador, nível de usuário, nível de repositório) estão presentes.

Regras do Mapeamento de Origens de Pacotes

Para máxima flexibilidade e controle, o NuGet exige que todos os pacotes correspondam a um padrão de pacote por meio de uma precedência bem definida.

Requisitos de padrão de pacotes

Todos os pacotes solicitados devem ser mapeados para uma ou mais origens correspondendo a um padrão de pacote definido. Em outras palavras, uma vez definido um elemento packageSourceMapping, você deve definir explicitamente de quais origens cada pacote, incluindo pacotes transitivos, será restaurado.

• Os pacotes de nível superior e transitivos devem corresponder a padrões definidos. Não é necessário que um pacote de nível superior e suas dependências tenham a mesma origem.
• O mesmo padrão de ID pode ser definido em várias origens, permitindo que IDs de pacote correspondentes sejam restaurados de qualquer um dos feeds que definem o padrão. No entanto, isso não é recomendado devido ao impacto na previsibilidade da restauração (um determinado pacote pode ser proveniente de várias origens). Essa poderá ser uma configuração válida se você confiar em todas as respectivas origens.

Sintaxe do padrão de pacote

Padrão	Exemplo de sintaxe	Descrição
Padrão de prefixo do pacote	*, NuGet.*	Deve terminar com um *, onde * corresponde a 0 ou mais caracteres. * é o padrão de prefixo permitido mais curto e corresponde a todos os IDs de pacotes.
Padrão de ID do pacote	NuGet.Common, Contoso.Contracts	ID exato do pacote.

Precedência do padrão de pacote

Quando vários padrões exclusivos correspondem a um ID de pacote, o mais específico é o preferido. Os padrões de ID de pacote sempre têm a precedência mais alta, enquanto o * genérico sempre tem a precedência mais baixa. Para padrões de prefixo de pacote, o mais longo tem precedência.

Definindo origens padrão

O padrão * pode ser usado para fazer uma declaração de uma origem padrão de fato, o que significa que qualquer pacote que não corresponda a outros padrões especificados será restaurado a partir dessa origem sem causar um erro. Essa configuração é vantajosa se você usa principalmente pacotes de digamos, nuget.org, e tem apenas alguns pacotes internos, ou usar prefixos padrão para todos os pacotes internos como Contoso.*.

Se sua equipe não usar prefixos padrão para IDs de pacotes internos ou validar pacotes nuget.org antes da instalação, tornar uma fonte privada o padrão atenderá melhor às suas necessidades.

Observação

Quando o pacote solicitado já existir na pasta de pacotes globais, nenhuma pesquisa de origem ocorrerá e os mapeamentos serão ignorados. Considere declarar uma pasta de pacotes globais para seu repositório para obter todos os benefícios de segurança desse recurso. Trabalhe para melhorar a experiência com a pasta de pacotes globais padrão no planejado para uma próxima iteração. Para saber mais sobre como a instalação de pacotes funciona, consulte o documento conceitual.

Introdução

Há 2 maneiras de integrar totalmente seu repositório, manualmente ou usando a ferramenta NuGet.PackageSourceMapper.

Integração manual

Para a integração manual, você pode seguir as seguintes etapas:

1. Declarar uma nova pasta de pacotes globais para seu repositório.
2. Executar a restauração do dotnet para restaurar dependências.
3. Executar dotnet list package --include-transitive para exibir todos os pacotes transitórios e de nível superior em sua solução.
   • Para projetos do .NET Framework usando o packages.config, o arquivo packages.config terá uma lista simples de todos os pacotes diretos e transitivos.
4. Definir mapeamentos de forma que cada ID de pacote em sua solução, incluindo pacotes transitivos corresponda a um padrão para a origem do destino.
5. Executar dotnet nuget locals global-packages -c para limpar o diretório global-packages.
6. Executar a restauração para validar se você configurou seus mapeamentos corretamente. Se os mapeamentos não cobrirem totalmente todas as IDs de pacote em sua solução, as mensagens de erro ajudarão você a identificar o problema.
7. Quando a restauração for bem-sucedida, você está pronto! Opcionalmente, considere:
   • Simplificar a configuração para menos declarações usando prefixos de ID de pacote mais amplos ou definir uma fonte padrão sempre que possível.
   • Verificar a origem da qual cada pacote foi restaurado verificando os arquivos de metadados na pasta de pacotes globais ou revisando os logs de restauração.

Integração automatizada usando a ferramenta

Muitos repositórios têm um grande número de pacotes, e fazer o trabalho manualmente pode ser demorado. A ferramenta NuGet.PackageSourceMapper pode gerar automaticamente um NuGet.config para você com base nos pacotes e origens conhecidos do seu projeto.

A ferramenta mapeadora de origem de pacote requer que você tenha concluído uma restauração de pacote bem-sucedida na qual ela lerá cada respectivo arquivo .nupkg.metadata gerado como parte de sua compilação para entender melhor como você mapeia seus respectivos pacotes e origens. A ferramenta não cobre apenas as principais dependências, mas também considera todas as dependências transitivas ao gerar o mapeamento.

Ferramenta tem várias opções de como gerar padrão de mapeamento dependendo de sua necessidade. Consulte a postagem do blog e as instruções LEIAME da ferramenta para obter mais detalhes.

Para ter uma ideia de como seus mapeamentos de origem podem parecer, consulte nosso repositório de amostras.

Observação

• Não há comandos nuget.exe ou dotnet.exe para gerenciar a configuração de mapeamento de origens de pacotes, consulte NuGet/Home#10735.
• Não há meios de mapear pacotes no momento da instalação do pacote, consulte NuGet/Home#10730.
• Há uma limitação ao usar a tarefa DotNetCoreCLI@2 do Azure Pipelines que pode ser contornada com o uso de prefixos feed- em sua configuração de mapeamento de origens. No entanto, recomenda-se usar NuGetAuthenticate para suas necessidades de autenticação e chamar a CLI do dotnet diretamente de uma tarefa de script. Consulte microsoft/azure-pipelines-tasks#15542.