Mapeamento de origem do pacote

O Mapeamento de Origem de Pacotes é uma ferramenta que pode ser usada para melhorar a segurança da sua cadeia de suprimentos, especialmente se você usar uma combinação de fontes de pacotes públicas e privadas.

Por padrão, o NuGet pesquisará todas as fontes de pacotes configuradas quando precisar baixar um pacote. Quando um pacote existe em várias fontes, pode não ser determinístico de qual fonte o pacote será baixado. Com o Mapeamento de origem do pacote, você pode filtrar, por pacote, qual(is) fonte(s) o NuGet pesquisará.

Também temos sugestões de outras práticas recomendadas para ajudá-lo a fortalecer sua cadeia de suprimentos contra ataques.

O mapeamento de origem do pacote foi adicionado ao NuGet 6.0. A partir do Visual Studio 17.5, você pode adicionar e remover mapeamentos de origem de pacote com a caixa de diálogo Opções do Visual Studio. Para obter informações detalhadas sobre todas as opções NuGet do Visual Studio, consulte Opções NuGet no Visual Studio.

Suporte ao Visual Studio

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

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

As ferramentas mais antigas ignorarão a configuração do Mapeamento de Origem do Pacote. 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 Origem do Pacote serão aplicados a todos os tipos de projeto – incluindo o .NET Framework – desde que ferramentas compatíveis sejam usadas.

Vídeo passo a passo

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

Habilitando o mapeamento de origem do pacote

Para optar por este recurso, você deve ter um nuget.config arquivo. Ter um único nuget.config na raiz do repositório é considerado uma prática recomendada. Consulte nuget.config documentação 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 Package Source Mappings caixa de diálogo Opções.

A partir da IU do Gestor de Pacotes

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

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

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

Para obter detalhes sobre como gerenciar mapeamentos de origem de pacotes NuGet, consulte Opções do NuGet no Visual Studio.

A janela Gerenciador de Pacotes NuGet será atualizada e refletirá o novo status dos mapeamentos de origem do pacote selecionado.

Ativar editando manualmente nuget.config

• Declare as fontes de pacotes que deseja no seu arquivo nuget.config.
• Após as declarações de origem, adicione um <packageSourceMapping> elemento que especifique os mapeamentos desejados para cada fonte.
• 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 origem do pacote são aplicadas seguindo as regras de precedência do nuget.config quando vários nuget.config ficheiros em vários níveis (nível de máquina, nível de usuário, nível de repositório) estão presentes.

Instalação com a interface do Gestor de Pacotes

A partir do Visual Studio 17.8 ou mais recente, quando os critérios abaixo forem cumpridos, a interface do Gestor de Pacotes tentará criar automaticamente mapeamentos de código-fonte de pacotes para os IDs de pacote instalados (os pacotes de topo e dependentes), ao utilizar as funcionalidades de Instalação ou Atualização do pacote.

A seguinte mensagem será mostrada quando os critérios para que isto aconteça sejam cumpridos automaticamente:

Será criado um mapeamento da fonte do pacote.

Atualmente, a criação de mapeamentos de origem é automática apenas quando:

• O projeto está a utilizar o PackageReference.
• O mapeamento de origem de pacotes já está ativado (já adicionou um mapeamento ou criou uma secção no seu NuGet.Config).
• Uma única fonte de pacotes é selecionada no menu suspenso (isto é, selecionar "Todos" para as fontes de pacotes não é suportado, pois é ambíguo qual fonte deve ser mapeada).

A operação pode falhar com o NU1110 se for descoberto que uma dependência na tua pasta Global Packages veio de uma fonte de pacotes que não está ativada na tua solução atual. Consulte a documentação do código de erro para formas de resolver este problema.

Selecionar a opção "Mostrar janela de pré-visualização" irá listar os novos mapeamentos de origem do pacote que estão a ser criados.

Se a pré-visualização não for o que pretende para os mapeamentos de origem, cancele a instalação e configure manualmente os mapeamentos de origem relevantes antes de realizar a Instalação/Atualização.

Por exemplo, a instalação do pacote Polly resulta na associação automática de Polly e da sua dependência Polly.Core à fonte de pacotes selecionada, nuget.org. Os pacotes dependentes da Microsoft são instalados usando mapeamentos de fontes de pacotes existentes.

Regras de mapeamento de origem do pacote

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 do padrão do pacote

Todos os pacotes solicitados devem ser mapeados para uma ou mais fontes, correspondendo a um padrão de pacote definido. Em outras palavras, depois de definir um packageSourceMapping elemento, é necessário definir explicitamente de quais fontes cada pacote - incluindo pacotes transitivos - será restaurado.

• Os pacotes de nível superior e transitivo devem corresponder a padrões definidos. Não há exigência de que um pacote de nível superior e suas dependências venham da mesma fonte.
• O mesmo padrão de ID pode ser definido em várias fontes, permitindo que IDs de pacote correspondentes sejam restauradas a partir 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 vir de várias fontes). Esta pode ser uma configuração válida se você confiar em todas as respetivas fontes.

Sintaxe do padrão do pacote

Precedência do padrão de pacote

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

Definindo fontes padrão

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

Se a sua equipa não utiliza prefixos padrão para IDs de pacotes internos ou avalia pacotes nuget.org antes da instalação, definir uma fonte privada como padrão atenderá melhor às suas necessidades.

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. Declare uma nova pasta de pacotes globais para seu repositório.
2. Execute dotnet restore para restaurar dependências.
3. Execute dotnet list package --include-transitive para visualizar todos os pacotes transitivos e de nível superior em sua solução.
   • Para projetos do .NET Framework usando packages.config, o arquivo packages.config conterá uma lista plana de todos os pacotes diretos e transitivos.
4. Defina mapeamentos de modo que cada ID de pacote em sua solução - incluindo pacotes transitivos - corresponda a um padrão para a origem de destino.
5. Execute dotnet nuget locals global-packages -c para limpar o diretório global-packages.
6. Execute a restauração para validar que você configurou seus mapeamentos corretamente. Se os mapeamentos não cobrirem totalmente todos os 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 definindo uma fonte padrão sempre que possível.
   • Verificar a origem a partir da qual cada pacote foi restaurado verificando os arquivos de metadados na pasta global packages ou revisando os logs de restauração.

Integração automatizada usando 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 fontes conhecidos do seu projeto.

A ferramenta de mapeamento de código-fonte de pacotes requer que você tenha concluído uma restauração de pacote bem-sucedida, na qual ele lerá cada respetivo .nupkg.metadata arquivo gerado como parte de sua compilação para entender melhor como você mapeia seus respetivos pacotes e fontes. A ferramenta não só cobre as principais dependências, mas também considera todas as dependências transitivas ao gerar mapeamento.

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

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