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.
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
- Abra sua solução no Visual Studio.
- 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 escolhaNuGet Package Manager
->Package Manager Settings
. - Navegue até a página
Package Source Mappings
.
- Pressione o botão
Add
na páginaPackage Source Mappings
para abrir a caixa de diálogoAdd 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.
- A página de opções
Package Source Mapping
mostrará o mapeamento de origem recém-criado.
- Pressione
OK
na caixa de diálogo Opções para salvar as alterações nonuget.config
aplicável. - 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. O trabalho para melhorar a experiência com a pasta de pacotes globais padrão está 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:
- Declarar uma nova pasta de pacotes globais para seu repositório.
- Executar a restauração do dotnet para restaurar dependências.
- 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 arquivopackages.config
terá uma lista simples de todos os pacotes diretos e transitivos.
- Para projetos do .NET Framework usando o
- 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.
- Executar dotnet nuget locals global-packages -c para limpar o diretório global-packages.
- 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.
- 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 prefixosfeed-
em sua configuração de mapeamento de origens. No entanto, recomenda-se usarNuGetAuthenticate
para suas necessidades de autenticação e chamar a CLI do dotnet diretamente de uma tarefa de script. Consulte microsoft/azure-pipelines-tasks#15542.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de