Paketquellenzuordnung

Die Paketquellzuordnung ist ein Tool, um ihre Lieferkettensicherheit zu verbessern, insbesondere, wenn Sie eine Mischung aus öffentlichen und privaten Paketquellen verwenden.

Standardmäßig durchsucht NuGet alle konfigurierten Paketquellen, wenn es ein Paket herunterladen muss. Wenn ein Paket in mehreren Quellen vorhanden ist, ist es möglicherweise nicht deterministisch, aus welcher Quelle das Paket heruntergeladen wird. Mit der Paketquellzuordnung können Sie pro Paket filtern, welche Quelle(n) NuGet durchsuchen soll.

Wir haben auch Vorschläge für andere bewährte Methoden, die Ihnen helfen, Ihre Lieferkette gegen Angriffe zu stärken.

Die Paketquellzuordnung wurde in NuGet 6.0 hinzugefügt. Ab Visual Studio 17.5 können Sie Paketquellzuordnungen mit dem Dialogfeld „Visual Studio-Optionen“ hinzufügen und entfernen.

Visual Studio-Unterstützung

Visual Studio	Paketquellenzuordnung	Unterstützung in Tools –> Optionen	Unterstützung in Paket-Manager UI
17.0 – 17.4	✅ Verfügbar	❌ Nicht verfügbar	❌ Nicht verfügbar
17,5	✅ Verfügbar	✅ Verfügbar	❌ Nicht verfügbar
17.7 Preview 3	✅ Verfügbar	✅ Verfügbar	✅ Angezeigter Status

Das Feature ist für alle in NuGet integrierten Tools verfügbar.

• Visual Studio 2022 und höher
• .NET SDK 6.0.100 und höher
• nuget.exe 6.0.0 und höher

Ältere Tools ignorieren die Konfiguration der Paketquellenzuordnung. Um dieses Feature zu verwenden, stellen Sie sicher, dass all Ihre Buildumgebungen kompatible Toolversionen verwenden.

Paketquellenzuordnungen gelten für alle Projekttypen, einschließlich .NET Framework, solange kompatible Tools verwendet werden.

Exemplarische Vorgehensweise per Video

Eine videobasierte Übersicht über das Feature für die Paketquellenzuordnung finden Sie im Video zum Schützen Ihrer NuGet-Pakete mit der Paketquellenzuordnung auf YouTube.

Aktivieren der Paketquellenzuordnung

Um dieses Feature zu aktivieren, benötigen Sie eine nuget.config-Datei. Als bewährte Methode wird empfohlen, eine einzige Datei nuget.config im Stammverzeichnis Ihres Repositorys zu verwenden. Weitere Informationen hierzu finden Sie in der Dokumentation zu „nuget.config“.

Aktivieren mithilfe des Dialogfelds „Visual Studio-Optionen“

1. Öffnen Sie Ihre Projektmappe in Visual Studio.
2. Navigieren Sie zum Dialogfeld Package Source Mappings „Optionen“.

Über die Paket-Manager-UI

• Wählen Sie ein Paket aus der Liste aus, um es im Detailbereich anzuzeigen.
• Drücken Sie die Configure Schaltfläche, um die Optionsseite „Paketquellzuordnungen“ zu öffnen.

Im Dialogfeld „Visual Studio-Optionen“

• Wechseln Sie zur Menüleiste Tools Standard Visual Studio, und wählen Sie NuGet Package Manager –>Package Manager Settings aus.
• Navigieren Sie zur Package Source Mappings-Seite.

3. Drücken Sie die Schaltfläche Add auf der Seite Package Source Mappings, um das Dialogfeld Add Package Source Mappings zu öffnen.

4. Geben Sie eine Paket-ID oder ein Paketmuster ein, und wählen Sie eine oder mehrere Paketquellen aus, indem Sie das Kontrollkästchen für Die gewünschten Quellen umschalten.

5. Auf der Optionsseite Package Source Mapping wird die neu erstellte Quellzuordnung angezeigt.

6. Drücken Sie OK im Dialogfeld „Optionen“, um Änderungen am zutreffenden nuget.config zu speichern.
7. Das NuGet-Paket-Manager-Fenster wird aktualisiert und spiegelt den neuen Status der Quellzuordnungen des ausgewählten Pakets wider.

Durch manuelles Bearbeiten von nuget.config aktivieren

• Deklarieren Sie Ihre gewünschten Paketquellen in Ihrer nuget.config-Datei.
• Fügen Sie nach der Quellendeklaration ein Element <packageSourceMapping> hinzu, das die gewünschten Zuordnungen für die einzelnen Quellen angibt.
• Deklarieren Sie genau ein packageSource-Element für jede verwendete Quelle.
  • Fügen Sie beliebig viele Muster hinzu.

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

Die Einstellungen der Paketquellenzuordnung werden nach den Regeln für die Rangfolge für „nuget.config“ angewendet, wenn mehrere nuget.config-Dateien auf mehreren Ebenen vorliegen (Computerebene, Benutzerebene, Repositoryebene).

Regeln für die Paketquellenzuordnung

Für maximale Flexibilität und Kontrolle erfordert NuGet, dass alle Pakete über eine klar definierte Rangfolge einem Paketmuster entsprechen.

Paketmusteranforderungen

Alle angeforderten Pakete müssen durch Übereinstimmung mit einem definierten Paketmuster einer oder mehreren Quellen zugeordnet werden. Mit anderen Worten: Sobald Sie ein packageSourceMapping-Element definiert haben, müssen Sie explizit definieren, aus welchen Quellen jedes Paket – einschließlich transitiver Pakete – wiederhergestellt werden soll.

• Sowohl Pakete der obersten Ebene als auch transitive Pakete müssen definierten Mustern entsprechen. Es ist nicht erforderlich, dass ein Paket der obersten Ebene und seine Abhängigkeiten aus derselben Quelle stammen.
• Dasselbe ID-Muster kann für mehrere Quellen definiert werden, sodass übereinstimmende Paket-IDs aus jedem der Feeds wiederhergestellt werden können, die das Muster definieren. Dies wird jedoch aufgrund der Auswirkungen auf die Vorhersagbarkeit der Wiederherstellung nicht empfohlen (da ein bestimmtes Paket aus mehreren Quellen stammen kann). Diese Konfiguration kann gültig sein, wenn Sie allen entsprechenden Quellen vertrauen.

Paketmustersyntax

Muster	Beispielsyntax	Beschreibung
Paketpräfixmuster	*, NuGet.*	Muss mit *, enden, wobei * 0 oder mehr Zeichen entspricht. * ist das kürzeste zulässige Präfixmuster und entspricht allen Paket-IDs.
Paket-ID-Muster	NuGet.Common, Contoso.Contracts	Genaue Paket-ID.

Rangfolge des Paketmusters

Wenn mehrere eindeutige Muster mit einer Paket-ID übereinstimmen, wird das spezifischste Muster bevorzugt. Paket-ID-Muster haben immer die höchste Priorität, während das generische * immer die niedrigste Priorität aufweist. Im Hinblick auf Paketpräfixmuster hat das längste Muster Vorrang.

Festlegen von Standardquellen

Anhand des *-Musters wird de facto eine Standardquelle deklariert. Alle Pakete, die nicht mit anderen angegebenen Mustern übereinstimmen, werden aus dieser Quelle wiederhergestellt, ohne dass ein Fehler ausgegeben wird. Diese Konfiguration ist von Vorteil, wenn Sie in erster Linie Pakete aus nuget.org verwenden und nur über wenige interne Pakete verfügen oder wenn Sie Standardpräfixe wie Contoso.* für alle internen Pakete einsetzen.

Wenn Ihr Team keine Standardpräfixe für interne Paket-IDs verwendet oder nuget.org-Pakete vor der Installation überprüft, ist es besser, eine private Quelle als Standardquelle zu verwenden.

Hinweis

Wenn das angeforderte Paket bereits im globalen Paketordner vorhanden ist, wird keine Quellsuche durchgeführt, und die Zuordnungen werden ignoriert. Erwägen Sie die Deklaration eines globalen Paketordners für Ihr Repository, um von allen Sicherheitsvorteilen dieses Features zu profitieren. Für eine nächste Version ist eine Verbesserung der Benutzererfahrung mit dem standardmäßigen globalen Paketordner geplant. Weitere Informationen zur Funktionsweise der Paketinstallation finden Sie im Konzeptdokument.

Erste Schritte

Es gibt zwei Möglichkeiten, ein vollständiges Onboarding für Ihr Repository durchzuführen, entweder manuell oder mithilfe des NuGet.PackageSourceMapper-Tools.

Manuelles Onboarding

Für das manuelle Onboarding können Sie die folgenden Schritte ausführen:

1. Deklarieren Sie einen neuen globalen Paketordner für Ihr Repository.
2. Führen Sie dotnet restore aus, um Abhängigkeiten wiederherzustellen.
3. Führen Sie dotnet list package --include-transitive aus, um alle Pakete auf oberster Ebene und alle transitiven Pakete in Ihrer Projektmappe anzuzeigen.
   • Für .NET Framework-Projekte, die packages.config verwenden, enthält die Datei packages.config eine unstrukturierte Liste aller direkten und transitiven Pakete.
4. Definieren Sie Zuordnungen so, dass jede Paket-ID in Ihrer Projektmappe – einschließlich transitiver Pakete – einem Muster für die Zielquelle entspricht.
5. Führen Sie dotnet nuget locals global-packages -c aus, um das Verzeichnis der globalen Pakete zu löschen.
6. Führen Sie die Wiederherstellung aus, um zu überprüfen, ob Sie Ihre Zuordnungen ordnungsgemäß konfiguriert haben. Wenn Ihre Zuordnungen nicht alle Paket-IDs in Ihrer Projektmappe vollständig abdecken, helfen Ihnen die Fehlermeldungen beim Identifizieren des Problems.
7. Wenn die Wiederherstellung erfolgreich ist, haben Sie den Vorgang abgeschlossen! Ziehen Sie optional Folgendes in Betracht:
   • Reduzieren Sie die Konfiguration auf weniger Deklarationen, indem Sie umfassendere Paket-ID-Präfixe verwenden oder nach Möglichkeit eine Standardquelle festlegen.
   • Überprüfen Sie die Quelle, aus der die einzelnen Pakete wiederhergestellt wurden, indem Sie die Metadatendateien im globalen Paketordner oder die Wiederherstellungsprotokolle überprüfen.

Automatisiertes Onboarding mithilfe des Tools

Viele Repositorys verfügen über eine große Anzahl von Paketen, die manuelle Arbeit kann deshalb zeitaufwändig sein. Das Tool NuGet.PackageSourceMapper kann basierend auf den bekannten Paketen und Quellen Ihres Projekts automatisch eine NuGet.config für Sie generieren.

Das Tool für das Paketquellzuordnungstool erfordert, dass Sie eine erfolgreiche Paketwiederherstellung abgeschlossen haben, in der die einzelnen .nupkg.metadata-Dateien gelesen werden, die als Teil Ihres Builds generiert wurden. So können Sie nachvollziehen, wie Sie Ihre jeweiligen Pakete und Quellen zuordnen können. Das Tool deckt nicht nur die wichtigsten Abhängigkeiten ab, es berücksichtigt auch alle transitiven Abhängigkeiten beim Generieren der Zuordnung.

Das Tool verfügt über mehrere Optionen zum Generieren von Zuordnungsmustern nach Bedarf. Sehen Sie sich dazu den Blogbeitrag die Infodatei für das Tool für weitere Informationen an.

Eine Vorstellung davon, wie Ihre Quellzuordnungen aussehen könnten, gewinnen Sie durch unser Beispielrepository.

Hinweis

• Es gibt keine Befehle „nuget.exe“ oder „dotnet.exe“ zum Verwalten der Konfiguration der Paketquellenzuordnung. Weitere Informationen finden Sie unter NuGet/Home#10735.
• Es gibt keine Möglichkeit zum Zuordnen von Paketen zur Paketinstallationszeit. Weitere Informationen finden Sie unter NuGet/Home#10730.
• Es gibt eine Einschränkung bei der Verwendung der Azure Pipelines-Aufgabe DotNetCoreCLI@2, die mithilfe von feed--Präfixen in Ihrer Quellzuordnungskonfiguration umgangen werden kann. Es wird jedoch empfohlen, für Ihre Authentifizierungsanforderungen NuGetAuthenticate zu verwenden und die dotnet CLI direkt über einen Skripttask aufzurufen. Weitere Informationen finden Sie unter microsoft/azure-pipelines-tasks#15542.