Gängige NuGet-Konfigurationen

  • Artikel

Das Verhalten von NuGet wird durch die akkumulierten Einstellungen in einer oder NuGet.Config mehreren XML-Dateien gesteuert, die auf Projektmappenebene (Projekt, wenn keine Lösung verwendet wird), benutzer- und computerweiten Ebenen vorhanden sein können. Eine globale NuGetDefaults.Config-Datei konfiguriert insbesondere Paketquellen. Die Einstellungen gelten für alle Befehle, die in der CLI, der Konsole oder der Benutzeroberfläche des Paket-Managers ausgeführt werden.

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 Verzeichnis des Projekts als Projektmappenverzeichnis behandelt, was zu Verhaltensunterschieden bei der Wiederherstellung des Projekts und der Projektmappe 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		 Einstellungen gelten für alle Vorgänge, werden aber von allen Einstellungen auf Lösungsebene überschrieben.
Computer Windows:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:$XDG_DATA_HOME. Wenn $XDG_DATA_HOME NULL oder leer ist, wird ~/.local/share oder /usr/local/share verwendet (je nach Betriebssystemverteilung)		 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. Die .NET CLI verwendet ~/.nuget/NuGet ordner, während Mono ordner verwendet ~/.config/NuGet .

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

Unter Mac/Linux variiert der Speicherort der Benutzerkonfigurationsdatei je nach Tool. Die meisten Benutzer verwenden 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ühere Versionen)
  • 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 umfassen, 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 beiden Konfigurationsdateien auf Benutzerebene, und behalten Sie die gewünschte Datei im ~/.nuget/NuGet Ordner bei.
  2. Legen Sie symbolische Verknüpfung von ~/.nuget/NuGet auf fest ~/.config/NuGet. Führen Sie z. B. den Bash-Befehl aus: 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 repositoryPath in the user-level config file
nuget config -set repositoryPath=c:\packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=c:\packages -configfile c:\my.Config
nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config

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

Mac/Linux:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=/home/packages 

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

# Set repositoryPath in the computer-level file (requires elevation)
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

Kopieren Sie die unten aufgeführte Vorlage 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 Speicherorten 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 aufgerufen wird, wobei Einstellungen, die einer Lösung oder dem aktuellen Ordner "am nächsten" sind, Vorrang haben. Wenn ein Befehlszeilentool für eine Projektdatei anstelle einer Projektmappendatei verwendet wird, wird das Projektverzeichnis als "Lösungsverzeichnis" verwendet, was zu inkonsistentem Verhalten führen kann, wenn sich eine NuGet.Config Datei in einem Unterverzeichnis der Projektmappendatei befindet.

NuGet lädt Einstellungen aus verschiedenen Konfigurationsdateien in folgender Reihenfolge:

  1. 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. Die Datei, die mit -configFile angegeben wurde.
  5. Dateien, die in jedem Ordner im Pfad vom Laufwerkstamm zum aktuellen Ordner gefunden werden (wo nuget.exe aufgerufen wird oder der Ordner, der die Visual Studio-Projektmappe enthält). 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 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. Dies bedeutet, dass Einstellungen, die dem aktuellen Ordner oder der aktuellen Lösung "am nächsten" sind, alle zuvor gefundenen Anderen ü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 Datei im Stammverzeichnis Ihres Projektmappenrepositorys hinzu nuget.config . 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>
    <activePackageSource>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
    </activePackageSource>
</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 vorhanden, um Paketquellen anzugeben, von denen aus Pakete installiert und aktualisiert werden können und um das Standardziel für das Veröffentlichen von Paketen mit nuget push anzugeben. 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 jeder im Unternehmen anstelle von nuget.org die richtige Paketquelle verwendet.

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 ein anderer Mechanismus in NuGet den Zugriff auf Paketquellen wie nuget.org verhindern. Wenn eine Organisation solche Zugriffe blockieren möchte, müssen dafür andere Mittel, z.B. eine Firewall, verwendet werden.

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 niedriger oder NuGet 3.x und niedriger:%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>