Pakketbrontoewijzing

Pakketbrontoewijzing is een hulpprogramma dat kan worden gebruikt om de beveiliging van uw toeleveringsketen te verbeteren, met name als u een combinatie van openbare en particuliere pakketbronnen gebruikt.

Standaard doorzoekt NuGet alle geconfigureerde pakketbronnen wanneer het een pakket moet downloaden. Wanneer een pakket bestaat op meerdere bronnen, is het mogelijk niet deterministisch van welke bron het pakket wordt gedownload. Met pakketbrontoewijzing kunt u per pakket filteren op welke bron(en) NuGet zoekt.

We hebben ook suggesties voor andere best practices om u te helpen uw toeleveringsketen te versterken tegen aanvallen.

Pakketbrontoewijzing is toegevoegd in NuGet 6.0. Vanaf Visual Studio 17.5 kunt u pakketbrontoewijzingen toevoegen en verwijderen met het dialoogvenster Opties voor Visual Studio. Zie NuGet-opties in Visual Studio voor gedetailleerde informatie over alle NuGet-opties van Visual Studio.

Visual Studio-ondersteuning

De functie is beschikbaar in alle geïntegreerde NuGet-hulpprogramma's.

• Visual Studio 2022 en hoger
• .NET SDK 6.0.100 en hoger
• nuget.exe 6.0.0 en hoger

Oudere hulpprogramma's negeren de configuratie van pakketbrontoewijzing. Als u deze functie wilt gebruiken, moet u ervoor zorgen dat al uw buildomgevingen compatibele hulpprogrammaversies gebruiken.

Pakketbrontoewijzingen zijn van toepassing op alle projecttypen, inclusief .NET Framework, zolang compatibele hulpprogramma's worden gebruikt.

Video-overzicht

Voor een video-gebaseerd overzicht van de functie Pakketbrontoewijzing kunt u overwegen om de NuGet-pakketten beveiligen met pakketbrontoewijzingsvideo op YouTube te bekijken.

Pakketbrontoewijzing inschakelen

Als u zich wilt aanmelden voor deze functie, moet u een nuget.config bestand hebben. Een enkele nuget.config in de hoofdmap van uw repository wordt beschouwd als een beste werkwijze. Zie nuget.config documentatie voor meer informatie.

Inschakelen met het dialoogvenster Visual Studio-opties

1. Open uw oplossing in Visual Studio.
2. Navigeer naar het Package Source Mappings dialoogvenster Opties.

Vanuit de gebruikersinterface van Package Manager

• Selecteer een pakket in de lijst om het weer te geven in het detailvenster.
• Druk op de Configure knop om de pagina Opties voor pakketbrontoewijzingen te openen.

Het venster NuGet Package Manager in Visual Studio met een geselecteerd pakket en een uitlichting rond de status Pakketbrontoewijzing is uit, met een knop om te configureren.

Vanuit het dialoogvenster Visual Studio-opties

• Ga naar het Tools menu in de hoofdwerkbalk van Visual Studio en kies NuGet Package Manager ->Package Manager Settings.
• Navigeer naar de Package Source Mappings pagina.

Zie NuGet-opties in Visual Studio voor meer informatie over het beheren van NuGet-pakketbrontoewijzingen.

Het Venster NuGet Package Manager wordt vernieuwd en geeft de nieuwe status van de brontoewijzingen van het geselecteerde pakket weer.

Inschakelen door handmatig te bewerken nuget.config

• Declareer de gewenste pakketbronnen in uw nuget.config bestand.
• Voeg na uw brondeclaraties een <packageSourceMapping> element toe dat de gewenste toewijzingen voor elke bron aangeeft.
• Declareer precies één packageSource element voor elke bron die in gebruik is.
  • Voeg zo veel patronen toe als u nodig hebt.

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

Instellingen voor pakketbrontoewijzing worden toegepast volgens nuget.config prioriteitsregels wanneer meerdere nuget.config bestanden op verschillende niveaus (op machineniveau, gebruikersniveau, opslagplaatsniveau) aanwezig zijn.

Installeren met de gebruikersinterface van Package Manager

Vanaf Visual Studio 17.8 of nieuwer, wanneer aan de onderstaande criteria wordt voldaan, zal de Gebruikersinterface van Package Manager automatisch pakketbrontoewijzingen maken voor de pakket-id's die geïnstalleerd worden (zowel de top-level als de afhankelijke pakketten), bij gebruik van de installatie- of updatefuncties voor pakketten.

Het volgende bericht wordt weergegeven wanneer aan de criteria voor dit automatisch wordt voldaan:

Er wordt een pakketbrontoewijzing gemaakt.

Op dit moment wordt het maken van brontoewijzingen alleen automatisch uitgevoerd wanneer:

• Het project maakt gebruik van PackageReference.
• Pakketbrontoewijzing is al ingeschakeld (u hebt al een toewijzing toegevoegd of een sectie gemaakt in uw NuGet.Config).
• Er wordt één pakketbron geselecteerd in de vervolgkeuzelijst ('Alles' selecteren voor pakketbronnen wordt niet ondersteund omdat het onduidelijk is welke bron moet worden toegewezen).

De bewerking kan mislukken met NU1110 als wordt vastgesteld dat een afhankelijkheid in de algemene pakketmap afkomstig is van een pakketbron die niet is ingeschakeld in uw huidige oplossing. Raadpleeg de documentatie over foutcodes voor manieren om dit probleem op te lossen.

Als u de optie "Voorbeeldvenster weergeven" selecteert, worden de nieuwe pakketbrontoewijzingen die worden aangemaakt weergegeven.

Als de preview niet is wat u wilt voor de brontoewijzingen, annuleert u de installatie en configureert u de relevante brontoewijzingen handmatig voordat u de installatie/update uitvoert.

Als u bijvoorbeeld het pakket installeert Polly , worden beide Polly en de afhankelijkheid Polly.Core automatisch toegewezen aan de geselecteerde pakketbron, nuget.org. Afhankelijke Microsoft-pakketten worden geïnstalleerd met behulp van bestaande pakketbrontoewijzingen.

Regels voor pakket-brontoewijzing

Voor maximale flexibiliteit en controle vereist NuGet dat alle pakketten overeenkomen met een pakketpatroon via een goed gedefinieerde prioriteit.

Vereisten voor pakketpatroon

Alle aangevraagde pakketten moeten worden toegewezen aan een of meer bronnen door een gedefinieerd pakketpatroon te koppelen. Met andere woorden, nadat u een packageSourceMapping element hebt gedefinieerd, moet u expliciet definiëren vanaf welke bronnen elk pakket , inclusief transitieve pakketten , wordt hersteld.

• Zowel op het hoogste niveau als transitieve pakketten moeten overeenkomen met gedefinieerde patronen. Er is geen vereiste dat een pakket op het hoogste niveau en de bijbehorende afhankelijkheden afkomstig zijn van dezelfde bron.
• Hetzelfde id-patroon kan worden gedefinieerd voor meerdere bronnen, zodat overeenkomende pakket-id's kunnen worden hersteld vanuit een van de feeds die het patroon definiëren. Dit wordt echter niet aanbevolen vanwege de impact op herstel voorspelbaarheid (een bepaald pakket kan afkomstig zijn van meerdere bronnen). Dit kan een geldige configuratie zijn als u alle respectieve bronnen vertrouwt.

Syntax van pakketpatroon

Prioriteit van pakketpatroon

Wanneer meerdere unieke patronen overeenkomen met een pakket-id, krijgt de meest specifieke voorkeur. Pakket-id-patronen hebben altijd de hoogste prioriteit, terwijl de algemene * altijd de laagste prioriteit heeft. Voor pakketvoorvoegselpatronen heeft de langste prioriteit.

Standaardbronnen instellen

Het * patroon kan worden gebruikt om een de-facto standaardbron te declareren. Dit betekent dat elk pakket dat niet overeenkomt met andere opgegeven patronen, wordt hersteld vanuit die bron zonder een fout te genereren. Deze configuratie is voordelig als u voornamelijk pakketten van bijvoorbeeld, nuget.orgen slechts enkele interne pakketten hebt, of standaardvoorvoegsels gebruikt voor alle interne pakketten, zoals Contoso.*.

Als uw team geen standaardvoorvoegsels voor interne pakket-id's gebruikt of pakketten vooraf goedkeurt nuget.org vóór de installatie, dan past het beter bij uw behoeften om een privébron als standaard in te stellen.

Get started

Er zijn twee manieren waarop u uw opslagplaats volledig kunt onboarden, handmatig of met het hulpprogramma NuGet.PackageSourceMapper.

Handmatig onboarden

Voor handmatige onboarding kunt u de volgende stappen uitvoeren:

1. Declareer een nieuwe map met globale pakketten voor uw opslagplaats.
2. Voer dotnet-herstel uit om afhankelijkheden te herstellen.
3. Voer deze dotnet list package --include-transitive opdracht uit om alle pakketten op het hoogste niveau en transitieve pakketten in uw oplossing weer te geven.
   • Voor .NET Framework-projecten die packages.config gebruiken, bevat het packages.config bestand een doorlopende lijst van alle directe en transitieve pakketten.
4. Definieer toewijzingen zodanig dat elke pakket-id in uw oplossing, inclusief transitieve pakketten , overeenkomt met een patroon voor de doelbron.
5. Voer dotnet nuget locals global-packages -c uit om de map global-packages te wissen.
6. Voer de herstelbewerking uit om te controleren of u de toewijzingen correct hebt geconfigureerd. Als uw toewijzingen niet alle pakket-ID's in uw oplossing volledig behandelen, zullen de foutberichten u helpen het probleem te identificeren.
7. Wanneer het herstellen is voltooid, bent u klaar. U kunt eventueel het volgende overwegen:
   • Vereenvoudig de configuratie tot minder declaraties door bredere voorvoegsels voor pakket-id's te gebruiken of waar mogelijk een standaardbron in te stellen .
   • Controleer of de bron van elk pakket is hersteld door de metagegevensbestanden in de map met globale pakketten te controleren of de herstellogboeken te controleren.

Geautomatiseerde onboarding met behulp van hulpprogramma

Veel opslagplaatsen hebben een groot aantal pakketten en het handmatig uitvoeren van het werk kan tijdrovend zijn. Het hulpprogramma NuGet.PackageSourceMapper kan automatisch een NuGet.config voor u genereren op basis van de bekende pakketten en bronnen van uw project.

Het pakketbrontoewijzingshulpmiddel vereist dat u een succesvolle pakketherstel hebt voltooid, waarbij elk respectief .nupkg.metadata bestand wordt gelezen dat als onderdeel van uw build wordt gegenereerd. Hierdoor begrijpt u optimaal hoe u uw respectieve pakketten en bronnen toewijst. Het tool behandelt niet alleen de belangrijkste afhankelijkheden, maar overweegt ook alle transitieve afhankelijkheden bij het genereren van de mapping.

Het hulpprogramma heeft verschillende opties om een toewijzingspatroon te genereren, afhankelijk van uw behoeften. Raadpleeg de blogpost en de leesmij-instructie voor meer informatie.

Raadpleeg onze opslagplaats met voorbeelden voor een idee van hoe uw brontoewijzingen eruit kunnen zien.