Mappage de source de package

Article
11/08/2022
6 minutes de lecture

La protection de votre chaîne d’approvisionnement logicielle est essentielle si vous utilisez une combinaison de sources de packages publics et privés. Utilisez le mappage de source de package avec d’autres bonnes pratiques pour vous aider à fortifier votre chaîne d’approvisionnement contre les attaques.

À compter de NuGet 6.0, vous pouvez déclarer de manière centralisée la source à partir de laquelle chaque package de votre solution doit être restauré dans votre fichier nuget.config.

La 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é, vérifiez que tous vos environnements de build utilisent des versions d’outils compatibles.

Les mappages de sources de package s’appliquent à tous les types de projet, y compris .NET Framework, tant que les outils compatibles sont utilisés.

Vidéo de 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écuriser vos packages NuGet avec la vidéo de mappage de source de package sur YouTube.

Activation du mappage de source de package

Pour choisir cette fonctionnalité, vous devez disposer d’un nuget.config fichier. Le fait d’avoir un seul nuget.config à la racine de votre dépôt est considéré comme une bonne pratique. Pour en savoir plus , consulteznuget.config documentation .

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

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

Les paramètres de mappage de source de package sont appliqués après nuget.config règles de précédence lorsque plusieurs nuget.config fichiers à différents niveaux (au niveau de l’ordinateur, au niveau de l’utilisateur, au niveau du dépôt) sont présents.

Règles de mappage de source de package

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

Configuration requise pour le modèle 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 packageSourceMapping élément, vous devez définir explicitement les sources à partir de laquelle chaque package , y compris les packages transitifs , sera restauré.

Les packages de niveau supérieur et transitif doivent correspondre aux modèles définis. Il n’est pas nécessaire qu’un package de niveau supérieur et ses dépendances proviennent de la même source.
Le 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 l’un des flux qui définissent le modèle. Toutefois, cela n’est pas recommandé en raison 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 respectives.

Syntaxe du modèle de package

Modèle	Exemple de syntaxe	Description
Modèle de préfixe de package	``, `NuGet.`, `NuGet.*`	Doit se terminer par un ``caractère , où `` correspond à 0 ou plusieurs caractères. `*` est le modèle de préfixe autorisé le plus court et 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, celui le plus spécifique est 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 plus long est prioritaire.

Exemples de précédence des modèles de package

Définition des sources par défaut

Le * modèle peut être utilisé pour déclarer 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 tels que , nuget.orget n’avez que quelques packages internes, ou 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 les packages vétérinaires nuget.org avant l’installation, la création d’une source privée adaptée à vos besoins est meilleure.

Notes

Lorsque le package demandé existe déjà dans le dossier des 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 dépôt afin d’obtenir les avantages de sécurité complets de cette fonctionnalité. Travailler pour améliorer l’expérience avec le dossier de packages globaux par défaut dans la planification d’une prochaine itération. Pour en savoir plus sur le fonctionnement de l’installation du package, consultez le document conceptuel.

Prendre en main

Il existe 2 façons d’intégrer entièrement votre référentiel, manuellement ou à l’aide de l’outil NuGet.PackageSourceMapper.

Intégration manuelle

Pour l’intégration manuelle, vous pouvez effectuer les étapes suivantes :

Déclarez un nouveau dossier de packages globaux pour votre dépôt.
Exécutez la restauration dotnet pour restaurer les dépendances.
Exécutez dotnet list package --include-transitive pour afficher tous les packages de niveau supérieur et transitif dans votre solution.
- Pour les projets .NET Framework utilisant packages.config, le packages.config fichier aura une liste plate de tous les packages directs et transitifs.
Définissez des mappages de sorte que chaque ID de package de votre solution , y compris les packages transitifs , correspond à 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é vos mappages. Si vos mappages ne couvrent pas entièrement chaque ID de package dans votre solution, les messages d’erreur vous aideront à identifier le problème.
Une fois la restauration réussie, vous avez terminé ! Envisagez éventuellement les éléments suivants :
- Simplification de la configuration à 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.
- La vérification de la source à partir de laquelle chaque package a été restauré en vérifiant 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 effectuent le travail manuellement peuvent prendre du temps. L’outil NuGet.PackageSourceMapper peut générer automatiquement une NuGet.config pour vous, en fonction des packages et sources connus de votre projet.

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

L’outil a plusieurs options pour générer un modèle de mappage en fonction de vos besoins, consultez le billet de blog et l’instruction lisez-moi de l’outil pour plus d’informations.

Pour une idée de l’apparence de vos mappages sources, reportez-vous à notre dépôt d’exemples.