Mappage de source du package

2024-02-07

Le mappage de source de package est un outil qui peut être utilisé pour améliorer la sécurité de votre chaîne d’approvisionnement, en particulier si vous utilisez une combinaison de sources de package publiques et privées.

Par défaut, NuGet recherche toutes les sources de package configurées quand il doit télécharger un package. Lorsqu’un package existe sur plusieurs sources, il peut ne pas être déterministe à partir duquel le package sera téléchargé. Avec le mappage de source de package, vous pouvez filtrer, par package, la ou les sources que recherchera NuGet.

Nous avons également des suggestions pour d’autres meilleures pratiques pour vous aider à fortifier votre chaîne d’approvisionnement contre les attaques.

Le mappage de source de package a été ajouté dans NuGet 6.0. À partir de Visual Studio 17.5, vous pouvez ajouter et supprimer des mappages de sources de package avec la boîte de dialogue Options de Visual Studio.

Visual Studio

Visual Studio	Mappage de source du package	Prise en charge dans Outils -> Options	Prise en charge dans l’interface utilisateur de Gestionnaire de package
17.0 – 17.4	✅ Disponible	❌ indisponible	❌ indisponible
17.5	✅ Disponible	✅ Disponible	❌ indisponible
17.7 Preview 3	✅ Disponible	✅ Disponible	Status ✅ affiché

Cette fonctionnalité est disponible dans tous les outils intégrés NuGet.

Les outils plus anciens ignorent la configuration du mappage de source de package. Pour utiliser cette fonctionnalité, assurez-vous que tous vos environnements de génération utilisent des versions d’outils compatibles.

Les mappages de source de package s’appliquent à tous les types de projets, y compris .NET Framework, dès lors que des outils compatibles sont utilisés.

Vidéo de la procédure pas à pas

Pour obtenir une vue d’ensemble vidéo de la fonctionnalité de mappage de source de package, envisagez de regarder la vidéo Sécurisez vos packages NuGet à l’aide du mappage de source de package sur YouTube.

Activer le mappage de source de package

Pour choisir cette fonctionnalité, vous devez disposer d’un fichier nuget.config. Le fait d’avoir un seul nuget.config à la racine de votre référentiel est considéré comme une meilleure pratique. Pour en savoir plus, consultez la documentation nuget.config.

Activation à l’aide de la boîte de dialogue Options de Visual Studio

Ouvrez votre solution dans Visual Studio.
Accédez à la boîte de dialogue Options Package Source Mappings.

Dans l’interface utilisateur du gestionnaire de package

Sélectionnez un package dans la liste pour l’afficher dans le volet Détails.
Appuyez sur le bouton Configure pour ouvrir la page des options Mappages de source de package.

Fenêtre du Gestionnaire de package NuGet dans Visual Studio montrant un package sélectionné et une mise en surbrillance autour du statut « Mappage de source de package est désactivé » avec un bouton Configurer.

Dans la boîte de dialogue Options de Visual Studio

Accédez au menu Tools de la barre d’outils principale de Visual Studio, puis choisissez NuGet Package Manager ->Package Manager Settings.
Accédez à la page Package Source Mappings.

Boîte de dialogue Options de mappages de source de package de Visual Studio ne montrant aucun mappage de source de package, avec un bouton Ajouter pour créer un mappage.

Appuyez sur le bouton Add de la page Package Source Mappings pour ouvrir la boîte de dialogue Add Package Source Mappings.

Boîte de dialogue Ajouter des mappages de sources de package 4. Saisissez un ID ou un modèle de package, puis sélectionnez une ou plusieurs sources de package en cochant la case à cocher de la (des) source(s) de votre choix.

Boîte de dialogue Ajouter des mappages de sources de package avec un modèle de package rempli et une source de package sélectionnée.

La page d’options de Package Source Mapping affiche le mappage source nouvellement créé.

Page d’options de mappages de sources de package montrant le mappage source nouvellement créé.

Appuyez sur OK sur la boîte de dialogue Options pour enregistrer les modifications apportées aux nuget.config applicables.
La fenêtre de Gestionnaire de package NuGet s’actualise et reflète le nouvel status des mappages sources du package sélectionné.

Activer en modifiant manuellement `nuget.config`

Déclarez vos sources de package souhaitées dans votre fichier nuget.config.
Après vos déclarations de sources, ajoutez un élément <packageSourceMapping> qui spécifie les mappages souhaités pour chaque source.
Déclarez exactement un seul élément packageSource pour chaque source utilisée.
- Ajoutez autant de modèles que vous estimez nécessaire.

<?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>

Les paramètres de mappage de source du package sont appliqués en suivant les règles de priorité nuget.config quand plusieurs fichiers nuget.config sont présents à différents niveaux (au niveau de l’ordinateur, au niveau utilisateur, au niveau du référentiel).

Règles de mappage de source de package

Pour un maximum de flexibilité et de contrôle, NuGet exige que tous les packages correspondent à un modèle de package par le biais d’une priorité bien définie.

Besoins liés aux modèles de package

Tous les packages demandés doivent être mappés à une ou plusieurs sources en correspondant à un modèle de package défini. En d’autres termes, une fois que vous avez défini un élément packageSourceMapping, vous devez définir explicitement les sources de chaque package qui seront restaurée, y compris pour les packages transitifs.

Les packages de niveau supérieur et les packages transitifs doivent correspondre aux modèles définis. Un package de niveau supérieur et ses dépendances ne doivent pas nécessairement provenir d’une seule et même source.
Un seul et même modèle d’ID peut être défini sur plusieurs sources, ce qui permet de restaurer les ID de package correspondants à partir de n’importe quel des flux qui définissent le modèle. Cependant, cela n’est pas recommandé à cause de l’impact sur la prévisibilité de la restauration (un package donné peut provenir de plusieurs sources). Il peut s’agir d’une configuration valide si vous approuvez toutes les sources.

Syntaxe du modèle de package

Modèle	Exemple de syntaxe	Description
Modèle de préfixe de package	``, `NuGet.`	Doit se terminer par un ``, où `` correspond à 0 caractères ou plus. `*` est le modèle de préfixe autorisé le plus court. Il correspond à tous les ID de packages.
Modèle d’ID de package	`NuGet.Common`, `Contoso.Contracts`	ID de package exact.

Priorité du modèle de package

Lorsque plusieurs modèles uniques correspondent à un ID de package, le modèle le plus spécifique sera préféré. Les modèles d’ID de package ont toujours la priorité la plus élevée, tandis que le * générique a toujours la priorité la plus basse. Pour les modèles de préfixe de package, le modèle plus long est prioritaire.

Exemples de priorité du modèle de package

Définition des sources par défaut

Le modèle * peut être utilisé pour créer une source par défaut de facto, ce qui signifie que tout package qui ne correspond pas à d’autres modèles spécifiés sera restauré à partir de cette source sans générer d’erreur. Cette configuration est avantageuse si vous utilisez principalement des packages provenant par exemple de nuget.org et que vous avez peu de packages internes, ou que vous utilisez des préfixes standard pour tous les packages internes comme Contoso.*.

Si votre équipe n’utilise pas de préfixes standard pour les ID de package internes ou approuve les packages nuget.org avant leur installation, la création d’une source privée conviendra mieux à vos besoins.

Remarque

Quand le package demandé existe déjà dans le dossier de packages globaux, aucune recherche source ne se produit et les mappages sont ignorés. Envisagez de déclarer un dossier de packages globaux pour votre référentiel afin d’obtenir l’ensemble des avantages de sécurité offerts par cette fonctionnalité. Un travail d’amélioration de l’expérience avec le dossier des packages globaux par défaut est prévu pour la prochaine itération. Pour en savoir plus sur le fonctionnement de l’installation du package, consultez le document conceptuel.

Bien démarrer

Il existe deux façons d’intégrer pleinement votre référentiel manuellement ou à l’aide de l’outil NuGet.PackageSourceMapper.

Intégration manuelle

Pour l’intégration manuelle, procédez comme suit :

Déclarez un nouveau dossier de packages globaux pour votre référentiel.
Exécutez dotnet restore pour restaurer les dépendances.
Exécutez dotnet list package --include-transitive pour afficher tous les packages de niveau supérieur et les packages transitifs dans votre solution.
- Pour les projets .NET Framework utilisant packages.config, le fichier packages.config aura une liste plate de tous les packages directs et transitifs.
Définissez des mappages de sorte à ce que chaque ID de package de votre solution, y compris les packages transitifs, corresponde à un modèle pour la source cible.
Exécutez dotnet nuget locals global-packages -c pour effacer le répertoire global-packages.
Exécutez la restauration pour vérifier que vous avez correctement configuré les mappages. Si les mappages ne couvrent pas entièrement chaque ID de package de la solution, les messages d’erreur vous aideront à identifier le problème.
Une fois la restauration réussie, vous avez terminé ! Vous pouvez éventuellement envisager les éléments suivants :
- Simplification de la configuration en faisant moins de déclarations à l’aide de préfixes d’ID de package plus larges ou définition d’une source par défaut si possible.
- Vérification de la source à partir de laquelle chaque package a été restauré en examinant les fichiers de métadonnées dans le dossier packages globaux ou en examinant les journaux de restauration.

Intégration automatisée à l’aide de l’outil

De nombreux référentiels ont un grand nombre de packages et effectuer le travail manuellement peuvent prendre du temps. L’outil NuGet.PackageSourceMapper peut générer automatiquement un fichier NuGet.config pour vous, en fonction des packages et sources connus de votre projet.

L’outil mappeur de source de package rend obligatoire la réalisation d’une restauration de package réussie dans laquelle il lit chaque fichier .nupkg.metadata respectif généré dans le cadre de votre génération pour mieux comprendre la manière dont vous mappez vos packages et sources respectifs. L’outil couvre non seulement les principales dépendances, il considère également toutes les dépendances transitives lors de la génération du mappage.

L’outil dispose de plusieurs options pour générer un modèle de mappage en fonction de vos besoins, veuillez consulter les billet de blog et les instructions du fichier Lisez-moi de l'outil pour plus de détails.

Pour une idée de ce à quoi peuvent ressembler vos mappages sources, reportez-vous à notre référentiel d’exemples.