Freigeben über

Gängige NuGet-Konfigurationen

  • Artikel

Das Verhalten von NuGet wird durch die gesammelten Einstellungen in einer oder mehreren config-(XML)-Dateien gesteuert, die auf Lösungs- (Projekt, wenn keine Lösung verwendet wird), Benutzer- und Computerebene existieren können.

Speicherorte und Verwendungsmöglichkeiten von Konfigurationsdateien

Bereich Speicherort der Datei NuGet.Config Beschreibung
Lösung Aktueller Ordner (bzw. Projektmappenordner) oder ein beliebiger anderer Ordner im Stammlaufwerk. In einem Projektmappenordner gelten die Einstellungen für alle Projekte in sämtlichen Unterordnern. Beachten Sie, dass eine Konfigurationsdatei, die in einem Projektordner gespeichert wird, keine Auswirkungen auf das Projekt hat. Beim Wiederherstellen eines Projekts in der Befehlszeile wird das Projektverzeichnis als Lösungsverzeichnis behandelt, was zu Verhaltensunterschieden beim Wiederherstellen des Projekts im Vergleich zur Lösung führen kann.
Benutzer Windows: %appdata%\NuGet\NuGet.Config
Mac/Linux: ~/.config/NuGet/NuGet.Config oder ~/.nuget/NuGet/NuGet.Config (variiert je nach Tool)
Zusätzliche Konfigurationen werden auf allen Plattformen unterstützt. Diese Konfigurationen können von den Tools nicht bearbeitet werden.
Windows: %appdata%\NuGet\config\*.Config
Mac/Linux: ~/.config/NuGet/config/*.config oder ~/.nuget/config/*.config		 Die Einstellungen gelten für alle Vorgänge, werden jedoch durch sämtliche Einstellungen auf Lösungsebene überschrieben.
Computer Windows: %ProgramFiles(x86)%\NuGet\Config
Mac/Linux: /etc/opt/NuGet/Config (Linux) oder /Library/Application Support (Mac) als Standard. Wenn $NUGET_COMMON_APPLICATION_DATA weder null noch leer ist, dann gilt stattdessen $NUGET_COMMON_APPLICATION_DATA/NuGet/Config		 Die Einstellungen gelten für alle Vorgänge auf dem Computer, werden jedoch von allen Einstellungen auf Benutzer- oder Lösungsebene überschrieben.

Hinweis

Unter Mac/Linux variiert der Speicherort der Benutzerkonfigurationsdatei je nach Tool. .NET CLI verwendet ~/.nuget/NuGet-Ordner, während Mono Ordner ~/.config/NuGet-Ordner verwendet.

Unter Mac/Linux variiert der Speicherort der Konfigurationsdatei auf Benutzerebene je nach Tool

Unter Mac/Linux variiert der Speicherort der Benutzerkonfigurationsdatei je nach Tool. Der Großteil der Benutzer verwendet Tools, die nach der Benutzerkonfigurationsdatei unter dem ~/.nuget/NuGet-Ordner suchen. Diese anderen Tools suchen nach der Benutzerkonfigurationsdatei unter dem ~/.config/NuGet-Ordner:

  • Mono
  • NuGet.exe
  • Visual Studio 2019 für Mac und früher
  • Visual Studio 2022 für Mac (und höhere Versionen) nur bei der Arbeit an klassischen Mono-Projekten.

Wenn die von Ihnen verwendeten Tools beide Speicherorte beinhalten, sollten Sie diese mithilfe der folgenden Schritte konsolidieren, damit Sie nur mit einer Konfigurationsdatei auf Benutzerebene arbeiten können:

  1. Überprüfen Sie den Inhalt der zwei Konfigurationsdateien auf Benutzerebene, und behalten Sie den gewünschten Ordner bei ~/.nuget/NuGet.
  2. Erstellen Sie eine symbolische Verknüpfung von ~/.nuget/NuGet zu ~/.config/NuGet. Beispiel: Ausführen des Bash-Befehls: ln -s ~/.nuget/NuGet ~/.config/NuGet.

Hinweise für frühere Versionen von NuGet:

  • In NuGet 3.3 und früher wurde ein .nuget-Ordner für projektmappenweite Einstellungen verwendet. Dieser Ordner wird in NuGet 3.4 oder höher nicht verwendet.
  • Für NuGet 2.6 bis 3.x befand sich die Konfigurationsdatei auf Computerebene unter Windows in %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, wobei {IDE} gleich VisualStudio sein kann, {Version} die Visual Studio-Version wie 14.0 war, und {SKU} entweder Community, Pro oder Enterprise ist. Um die Einstellungen zu NuGet 4.0+ zu migrieren, kopieren Sie einfach die Konfigurationsdatei in %ProgramFiles(x86)%\NuGet\Config. Unter Linux war dieser vorherige Speicherort /etc/opt und auf einem Mac /Library/Application Support.

Ändern von Konfigurationseinstellungen

Bei einer NuGet.Config-Datei handelt es sich um eine einfache XML-Textdatei, die wie im Artikel NuGet Configuration Settings (NuGet-Konfigurationseinstellungen) beschrieben Schlüssel/Wert-Paare enthält.

Einstellungen werden mithilfe des NuGet CLI-Befehls config verwaltet:

  • Standardmäßig werden Änderungen an der Konfigurationsdatei auf Benutzerebene vorgenommen. (Unter Mac/Linux variiert der Speicherort der Konfigurationsdatei auf Benutzerebene je nach Tool)
  • Verwenden Sie den -configFile-Parameter, um die Einstellungen in einer anderen Datei zu ändern. In diesem Fall kann ein beliebiger Dateiname für Dateien verwendet werden.
  • Bei Schlüsseln wird die Groß-/Kleinschreibung immer beachtet.
  • Es ist eine Erhöhung der Rechte erforderlich, um die Einstellungen in der Einstellungsdatei auf Computerebene zu ändern.

Warnung

Sie können die Datei zwar in jedem Text-Editor bearbeiten, NuGet (3.4.3 und höher) ignoriert jedoch die gesamte Konfigurationsdatei, wenn diese falsche XML-Formatierungen (nicht übereinstimmende Tags, ungültige Anführungszeichen usw.) enthält. Deshalb wird empfohlen, Einstellungen mithilfe von nuget config zu verwalten.

Festlegen eines Werts

Windows:

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder "C:\packages"

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath "C:\packages"

# Set repositoryPath in solution-level files
dotnet nuget config set repositoryPath "C:\packages" --configfile "C:\my.config"
dotnet nuget config set repositoryPath "c:\packages" --configfile "..\..\my.config"

# Set repositoryPath in the computer-level file (requires elevation)
dotnet nuget config set repositoryPath "c:\packages" --configfile "%appdata%\NuGet\NuGet.Config"

Mac/Linux:

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder /home/packages

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath /home/packages

# Set repositoryPath in solution-level files
dotnet nuget config set repositoryPath /home/projects/packages --configfile /home/my.Config
dotnet nuget config set repositoryPath /home/packages --configfile home/myApp/NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
dotnet nuget config set repositoryPath /home/packages --configfile $XDG_DATA_HOME/NuGet.Config

Hinweis

In NuGet 3.4 und höher können Sie Umgebungsvariablen in jedem Wert verwenden, z.B. in repositoryPath=%PACKAGEHOME% (Windows) oder repositoryPath=$PACKAGEHOME (Mac/Linux).

Entfernen eines Werts

Geben Sie einen Schlüssel mit einem leeren Wert an, um einen Wert zu entfernen.

# Windows
nuget config -set repositoryPath= -configfile c:\my.Config

# Mac/Linux
nuget config -set repositoryPath= -configfile /home/my.Config

Erstellen einer neuen Konfigurationsdatei

Erstellen Sie mithilfe der .NET CLI eine standardmäßige nuget.config, indem Sie dotnet new nugetconfig ausführen. Weitere Informationen finden Sie unter dotnet-CLI-Befehle.

Kopieren Sie alternativ die Vorlage unten manuell in die neue Datei, und verwenden Sie dann nuget config -configFile <filename>, um Werte festzulegen:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
</configuration>

Anwenden der Einstellungen

Mit mehreren NuGet.Config-Dateien können Sie Einstellungen an verschiedenen Orten speichern, sodass sie für eine einzelne Lösung oder eine Gruppe von Lösungen gelten. Diese Einstellungen gelten zusammen für jeden NuGet-Vorgang, der über die Befehlszeile oder über Visual Studio ausgeführt wird. Hierbei haben die Einstellungen Vorrang, die der Lösung oder dem aktuellen Ordner am „nächsten“ liegen. Wenn ein Befehlszeilentool in einer Projektdatei anstelle einer Lösungsdatei verwendet wird, wird das Projektverzeichnis als „Lösungsverzeichnis“ verwendet, was zu inkonsistenten Verhalten führen kann, wenn eine NuGet.Config Datei in einem Unterverzeichnis der Lösungsdatei vorhanden ist.

Wenn eine Konfigurationsdatei nicht explizit in der Befehlszeile angegeben wird, lädt NuGet die Einstellungen aus den verschiedenen Konfigurationsdateien in der folgenden Reihenfolge:

  1. (Ungewöhnlich) Die NuGetDefaults.Config-Datei, die ausschließlich Einstellungen für die Paketquellen enthält.
  2. Die Datei auf Computerebene.
  3. Die Datei auf Benutzerebene.
  4. Dateien, die vom Stamm des Laufwerks bis zum aktuellen Ordner (in dem nuget.exe ausgeführt wird oder der die Visual Studio-Lösung enthält) in jedem Ordner im Pfad gefunden werden. Wenn beispielsweise ein Befehl in c:\A\B\C aufgerufen wird, sucht NuGet in c:\, dann in c:\A, dann in c:\A\B und schließlich in c:\A\B\C nach Konfigurationsdateien und lädt diese.

Wenn eine Konfigurationsdatei explizit in der Befehlszeile angegeben wird, zum Beispiel nuget -configFile my.config oder dotnet restore --configfile my.config, werden nur die Einstellungen aus der angegebenen Datei verwendet.

Wenn NuGet Einstellungen in diesen Dateien vorfindet, werden diese folgendermaßen angewendet:

  1. Für einzelne Elemente ersetzt NuGet jeden zuvor gefundenen Wert mit demselben Schlüssel. Das bedeutet, dass die Einstellungen, die dem aktuellen Ordner oder der Lösung „am nächsten“ liegen die zuvor gefundenen überschreiben. Die defaultPushSource-Einstellung in NuGetDefaults.Config wird beispielsweise überschrieben, wenn diese in einer anderen Konfigurationsdatei vorhanden ist.
  2. Bei Auflistungselementen (z.B. <packageSources>) kombiniert NuGet die Werte aller Konfigurationsdateien zu einer einzelnen Auflistung.
  3. Wenn <clear /> für einen bestimmten Knoten vorhanden ist, ignoriert NuGet die zuvor definierten Konfigurationswerte für diesen Knoten.

Tipp

Fügen Sie eine nuget.config-Datei im Stammverzeichnis Ihres Lösungs-Repositorys hinzu. Dies gilt als bewährte Methode, da sie die Wiederholbarkeit fördert und sicherstellt, dass verschiedene Benutzer dieselbe NuGet-Konfiguration haben.

Exemplarische Vorgehensweise: Einstellungen

Nehmen wir an, dass Sie über folgende Ordnerstruktur auf zwei separaten Laufwerken verfügen:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

Sie verfügen dann über vier NuGet.Config-Dateien an folgenden Speicherorten mit dem angegebenen Inhalt. (Die Datei auf Computerebene ist in diesem Beispiel nicht enthalten. Diese würde sich jedoch ähnlich wie die Datei auf Benutzerebene verhalten.)

Datei A auf Benutzerebene (%appdata%\NuGet\NuGet.Config unter Windows, ~/.config/NuGet/NuGet.Config unter Mac/Linux):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

Datei B. disk_drive_2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="disk_drive_2/tmp" />
    </config>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Datei C. disk_drive_2/Project1/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="External/Packages" />
        <add key="defaultPushSource" value="https://MyPrivateRepo/ES/api/v2/package" />
    </config>
    <packageSources>
        <clear /> <!-- ensure only the sources defined below are used -->
        <add key="MyPrivateRepo - ES" value="https://MyPrivateRepo/ES/nuget" />
    </packageSources>
</configuration>

Datei D. disk_drive_2/Project2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <!-- Add this repository to the list of available repositories -->
        <add key="MyPrivateRepo - DQ" value="https://MyPrivateRepo/DQ/nuget" />
    </packageSources>
</configuration>

Je nachdem, wo aus NuGet aufgerufen wird, werden die Einstellungen folgendermaßen geladen und angewendet:

  • Aufgerufen von disk_drive_1/users: Es wird nur das Standardrepository verwendet, das in der Konfigurationsdatei auf Benutzerebene (A) aufgeführt wird, da dies die einzige Datei ist, die auf disk_drive_1 gefunden wurde.

  • Aufgerufen von disk_drive_2/ oder disk_drive_/tmp: Die Datei auf Benutzerebene (A) wird zuerst geladen, dann sucht NuGet im Stamm von disk_drive_2 und findet Datei (B). NuGet sucht ebenfalls in /tmp nach einer Konfigurationsdatei, findet aber keine. Deshalb wird das Standardrepository auf nuget.org verwendet, außerdem wird die Paketwiederherstellung aktiviert und Pakete werden in disk_drive_2/tmp erweitert.

  • Aufgerufen von disk_drive_2/Project1 oder disk_drive_2/Project1/Source: Die Datei auf Benutzerebene (A) wird zuerst geladen, dann lädt NuGet aus dem Stamm von disk_drive_2 zunächst Datei (B) und anschließend Datei (C). Die Einstellungen in Datei (C) überschreiben die in Datei (A) und (B), sodass der repositoryPath, in dem Pakete installiert werden, disk_drive_2/Project1/External/Packages anstelle von disk_drive_2/tmp lautet. Da <packageSources> durch Datei C gelöscht wird, ist nuget.org nicht mehr als Quelle verfügbar, sondern nur noch https://MyPrivateRepo/ES/nuget.

  • Aufgerufen von disk_drive_2/Project2 oder disk_drive_2/Project2/Source: Die Datei auf Benutzerebene (A) wird zuerst geladen, anschließend folgen Datei (B) und Datei (D). Da packageSources nicht gelöscht wurde, sind nuget.org und https://MyPrivateRepo/DQ/nuget als Quellen verfügbar. Die Pakete werden, wie in Datei (B) angegeben, in disk_drive_2/tmp erweitert.

Zusätzliche benutzerübergreifende Konfigurationen

Ab 5.7 bietet NuGet Unterstützung für weitere benutzerübergreifende Konfigurationsdateien. Dies ermöglicht es Drittanbietern, ohne Rechteerweiterungen weitere Benutzerkonfigurationsdateien hinzuzufügen. Diese Konfigurationsdateien befinden sich im Standardordner für benutzerübergreifende Konfigurationen in einem Unterordner config. Alle Dateien, die auf .config oder .Config enden, werden berücksichtigt. Diese Dateien können mit den Standardtools nicht bearbeitet werden.

Betriebssystemplattform Zusätzliche Konfigurationen
Windows %appdata%\NuGet\config\*.Config
Mac/Linux ~/.config/NuGet/config/*.config oder ~/.nuget/config/*.config

NuGet-Standarddatei

Die NuGetDefaults.Config-Datei ist ungewöhnlich und kann nur Paketquellen angeben, von denen aus Pakete installiert und aktualisiert werden können, oder das Standardziel für das Veröffentlichen von Paketen mit nuget push kontrollieren.

Da Administratoren konsistente NuGetDefaults.Config-Dateien einfach für Entwickler- und Buildcomputer bereitstellen können (z. B. mithilfe des Tools Gruppenrichtlinie), können diese sicherstellen, dass alle im Unternehmen konsistente Paketquellen verwenden (mit oder ohne nuget.org).

Wichtig

Durch die NuGetDefaults.Config-Datei werden Paketquellen niemals aus der NuGet-Konfiguration eines Entwicklers gelöscht. Wenn der Entwickler also bereits NuGet verwendet und deshalb eine Paketquelle von nuget.org registriert, wird diese nach der Erstellung der NuGetDefaults.Config-Datei nicht entfernt.

Darüber hinaus kann weder NuGetDefaults.Config noch jeder andere Mechanismus in NuGet den Zugriff auf Paketquellen wie nuget.org verhindern. Wenn eine Organisation diesen Zugriff blockieren möchte, muss sie andere Mittel wie Firewalls verwenden, um dies zu tun.

NuGetDefaults.Config-Speicherort

In der folgenden Tabelle wird beschrieben, wo die NuGetDefaults.Config-Datei gespeichert werden soll. Dies ist vom jeweiligen Betriebssystem abhängig:

Betriebssystemplattform NuGetDefaults.Config Speicherort
Windows Visual Studio 2017 oder NuGet 4.x und höher: %ProgramFiles(x86)%\NuGet
Visual Studio 2015 und früher oder NuGet 3.x und früher: %PROGRAMDATA%\NuGet
Mac/Linux $XDG_DATA_HOME (in der Regel ~/.local/share oder /usr/local/share, abhängig von der Betriebssystemverteilung)

Einstellungen von NuGetDefaults.Config

  • packageSources: Diese Auflistung hat in regulären Konfigurationsdateien die gleiche Bedeutung wie packageSources und gibt die Standardquellen an. NuGet verwendet die Quellen in der chronologischen Reihenfolge der Installation oder Aktualisierung von Paketen in Projekten unter Verwendung der Verwaltungsformate von packages.config. Für Pakete, die das PackageReference-Format verwenden, verwendet NuGet unabhängig von der Reihenfolge der Konfigurationsdateien zuerst die lokalen Quellen, dann die Quellen auf Netzwerkfreigaben und anschließend HTTP-Quellen. NuGet ignoriert immer die Reihenfolge von Quellen mit Wiederherstellungsvorgängen.

  • disabledPackageSources: Diese Auflistung hat ebenfalls die gleiche Bedeutung wie in NuGet.Config-Dateien, bei denen jede betroffene Quelle mit ihrem Namen und einem true-/false-Wert aufgeführt wird, der angibt, ob diese deaktiviert ist oder nicht. Dadurch wird ermöglicht, dass der Quellname und die URL in packageSources verbleiben, ohne dass diese standardmäßig aktiviert sein muss. Einzelne Entwickler können die Quelle erneut aktivieren, indem sie den Wert der Quelle in anderen NuGet.Config-Dateien auf false festlegen. Die richtige URL muss somit nicht erneut gesucht werden. Dies ist nützlich, um Entwicklern eine vollständige Liste der internen Quell-URLs für eine Organisation bereitzustellen und gleichzeitig nur eine einzige Quelle für das Team standardmäßig zu aktivieren.

  • defaultPushSource: Gibt das Standardziel für nuget push-Vorgänge an und überschreibt die integrierten Standardeinstellungen von nuget.org. Administratoren können diese Einstellung bereitstellen, um das versehentliche Veröffentlichen von internen Paketen für den öffentlichen Katalog von nuget.org zu verhindern, da Entwickler spezifisch nuget push -Source verwenden müssen, um auf nuget.org zu veröffentlichen.

Beispiel für NuGetDefaults.Config und eine Anwendung

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- defaultPushSource key works like the 'defaultPushSource' key of NuGet.Config files. -->
    <!-- This can be used by administrators to prevent accidental publishing of packages to nuget.org. -->
    <config>
        <add key="defaultPushSource" value="https://contoso.com/packages/" />
    </config>

    <!-- Default Package Sources; works like the 'packageSources' section of NuGet.Config files. -->
    <!-- This collection cannot be deleted or modified but can be disabled/enabled by users. -->
    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

    <!-- Default Package Sources that are disabled by default. -->
    <!-- Works like the 'disabledPackageSources' section of NuGet.Config files. -->
    <!-- Sources cannot be modified or deleted either but can be enabled/disabled by users. -->
    <disabledPackageSources>
        <add key="nuget.org" value="true" />
    </disabledPackageSources>
</configuration>