Paketen mit NuGet-Paketwiederherstellung wiederherstellen

  • Artikel

Die NuGet-Paketwiederherstellung stellt alle Abhängigkeiten eines Projekts wieder her, die entweder in einer Projektdatei oder einer Packages.config-Datei aufgeführt sind. Sie können Pakete manuell mit nuget restore, dotnet restore, msbuild -t:restore oder über Visual Studio wiederherstellen. Die Befehle dotnet build und dotnet run stellen Pakete automatisch wieder her, und Sie können Visual Studio so konfigurieren, dass Pakete automatisch wiederhergestellt werden, wenn ein Projekt erstellt wird.

Um eine sauber er Entwicklungsumgebung zu fördern und die Größe des Repositorys zu reduzieren, stellt die Paketwiederherstellung alle Abhängigkeiten eines Projekts zur Verfügung, ohne sie in der Quellcodeverwaltung speichern zu müssen. Informationen zur Konfiguration Ihres Repositorys zum Ausschließen von Paketbinärdateien finden Sie unter Überspringen von NuGet-Paketen in Quellcodeverwaltungssystemen.

Verhalten der Paketwiederherstellung

Die Paketwiederherstellung versucht, alle Paketabhängigkeiten in dem Zustand zu installieren, der den <PackageReference>s in einer Projektdatei, z. B. .csproj, oder den <package>s in einer packages.config-Datei entspricht. Bei der Paketwiederherstellung werden zunächst die direkten Abhängigkeiten eines Projekts bedarfsbasiert installiert. Anschließend werden alle Abhängigkeiten dieser Pakete im gesamten Abhängigkeitsdiagramm installiert.

Wenn ein benötigtes Paket noch nicht installiert ist, versucht NuGet zunächst, es aus den lokalen globalen Paketen oder den HTTP-Cache-Ordnern abzurufen. Wenn sich das Paket nicht in den lokalen Ordnern befindet, versucht NuGet, es von allen Quellen herunterzuladen, die in Visual Studio unter Extras>Optionen>NuGet Package Manager>Paketquellen konfiguriert sind.

Während der Wiederherstellung ignoriert NuGet die Reihenfolge der Paketquellen und verwendet das Paket aus der ersten Quelle, die auf Anfragen antwortet. Wenn die Wiederherstellung fehlschlägt, gibt NuGet den Fehler erst an, nachdem alle Quellen überprüft wurden. NuGet meldet einen Fehler nur für die letzte Quelle aus der Liste. Der Fehler impliziert, dass das Paket in keiner der Quellen vorhanden war, obwohl es die anderen Fehler nicht einzeln auflistet.

Weitere Informationen zur Verhaltensweise von NuGet finden Sie unter Konfigurieren des NuGet-Verhaltens.

Pakete wiederherstellen

Wenn die Paketreferenzen in Ihrer Projektdatei oder der packages.config-Datei korrekt sind, verwenden Sie Ihr bevorzugtes Werkzeug, um Pakete wiederherzustellen:

Nach erfolgreicher Wiederherstellung:

  • Bei Projekten, die <PackageReference> verwenden, befindet sich das Paket im lokalen Ordner für globale Pakete vorhanden, und die Projektdatei obj/project.assets.json wird neu erstellt.
  • Bei Projekten, die packages.config verwenden, wird das Paket im Ordner für Pakete des Projekts angezeigt.
  • Das Projekt sollte jetzt erfolgreich erstellt werden.

Wenn die Paketreferenzen in Ihrer Projektdatei oder Ihrer packages.config-Datei nicht korrekt sind und nicht dem gewünschten Zustand entsprechen, installieren oder aktualisieren Sie die richtigen Pakete, anstatt die Paketwiederherstellung zu verwenden.

Wenn nach der Ausführung der Paketwiederherstellung Pakete fehlen oder paketbezogene Fehler auftreten, wie z. B. Fehlersymbole im Lösungs-Explorer, befolgen Sie die Anweisungen unter Fehlerbehebung bei der Paketwiederherstellung, oder installieren oder aktualisieren Sie die Pakete neu. In Visual Studio bietet die Paketmanager-Konsole mehrere Optionen für die erneute Installation von Paketen. Weitere Informationen finden Sie unter Paket-Update verwenden.

Pakete in Visual Studio wiederherstellen

In Visual Studio unter Windows können Sie Pakete automatisch oder manuell wiederherstellen. Konfigurieren Sie zunächst die Paketwiederherstellung unter Tools>Options>NuGet Package Manager.

Visual Studio-Paketwiederherstellungsoptionen konfigurieren

Konfigurieren Sie die folgenden Optionen für die Paketwiederherstellung unter Tools>Options>NuGet Paket-Manager>Allgemein.

Screenshot that shows the NuGet Package Manager options.

Erlauben Sie NuGet, fehlende Pakete herunterzuladen

Wählen Sie NuGet zulassen, um fehlende Pakete herunterzuladen, um die Paketwiederherstellung und den Befehl NuGet-Pakete wiederherstellen zu aktivieren. Diese Auswahl setzt die packageRestore/enabled-Einstellung im Abschnitt packageRestore der globalen NuGet.Config-Datei unter %AppData%\Roaming\NuGet unter Windows oder ~/.nuget/NuGet/ unter Mac oder Linux auf True.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Hinweis

Die packageRestore/enabled-Einstellung kann global außer Kraft gesetzt werden, indem die Umgebungsvariable EnableNuGetPackageRestore auf True oder False festgelegt wird, bevor Sie Visual Studio öffnen oder einen Build starten.

Um die Paketwiederherstellung für alle Benutzer auf einem Computer zu aktivieren oder zu deaktivieren, können Sie die Konfigurationseinstellungen zur globalen NuGet.Config-Datei unter Windows unter %ProgramData%\NuGet\Config, manchmal unter einem bestimmten <IDE>\<Version>\<SKU> Visual Studio-Ordner, oder unter Mac/Linux bei ~/.local/share hinzufügen. Einzelne Benutzer können dann nach Bedarf die Wiederherstellung auf Projektebene aktivieren. Weitere Informationen zur Vorgehensweise von NuGet bei der Priorisierung mehrerer Konfigurationsdateien finden Sie unter Konfigurieren des NuGet-Verhaltens.

Wichtig

Wenn Sie die packageRestore-Einstellungen in NuGet.Config direkt bearbeiten, starten Sie Visual Studio neu, damit die Optionen die aktuellen Werte anzeigen.

Automatische Überprüfung auf fehlende Pakete während der Erstellung

Aktivieren Sie Automatische Überprüfung auf fehlende Pakete während während der Erstellung in Visual Studio, um alle fehlenden Pakete automatisch wiederherzustellen, wenn Sie einen Build aus Visual Studio ausführen. Diese Einstellung wirkt sich nicht auf Builds aus, die über die MSBuild-Befehlszeile ausgeführt werden. Diese Auswahl setzt die packageRestore/automatic-Einstellung im True-Abschnitt der NuGet.Config-Datei auf packageRestore.

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Bei Projekten, die nicht im SDK-Format vorliegen, müssen Sie in Visual Studio unter Optionen die Option Herunterladen fehlender Pakete durch NuGet zulassen sowie Automatische Überprüfung auf fehlende Pakete während der Erstellung auswählen, um die automatische Wiederherstellung zu aktivieren.

Auswählen des Standardformats für die Paketverwaltung

NuGet verfügt über zwei Paketverwaltungsformate, PackageReference und packages.config. Wählen Sie das Format aus, das Sie in der Dropdownliste unter Paketverwaltung verwenden möchten. Sie können auch auswählen, ob die Formatauswahl bei der ersten Paketinstallation zugelassen werden soll.

Hinweis

  • Wenn ein Projekt nicht beide Paketverwaltungsformate unterstützt, verwendet NuGet das Paketverwaltungsformat, das mit dem Projekt kompatibel ist, was möglicherweise nicht der Standard ist, den Sie in den Optionen festgelegt haben. NuGet fordert dann bei der ersten Installation nicht zur Auswahl auf, auch wenn Sie diese Option ausgewählt haben.

  • Wenn Sie die Paketverwaltungskonsole verwenden, um das erste Paket in einem Projekt zu installieren, werden Sie von NuGet nicht zur Auswahl des Formats aufgefordert, selbst wenn diese Option in den Optionen ausgewählt ist.

Pakete manuell oder automatisch wiederherstellen

Nachdem Sie die Paketwiederherstellung in Optionen aktiviert haben, können Sie in Projektmappen-Explorer mit der rechten Maustaste auf die Lösung klicken und NuGet-Pakete wiederherstellen, um Pakete jederzeit wiederherzustellen.

Wenn Sie die automatische Wiederherstellung in den Optionen aktiviert haben, erfolgt die Paketwiederherstellung automatisch, wenn Sie ein Projekt aus einer Vorlage oder ein Projekt erstellen. Die Wiederherstellung wird in NuGet 4.0 und höher auch automatisch durchgeführt, wenn Sie Änderungen an einem SDK-Projekt vornehmen.

Bei Projekten, die <PackageReference> verwenden, können Sie die Paketreferenzen in Visual Studio Projektmappen-Explorer unter Abhängigkeiten>Pakete anzeigen. Pakete, die nicht ordnungsgemäß installiert werden, wenn Sie einen Build manuell wiederherstellen oder ausführen, zeigen im Projektmappen-Explorer Fehlersymbole an. Rechtsklicken Sie auf das Projekt, wählen Sie NuGet-Pakete verwalten, und verwenden Sie den NuGet Package Manager, um die betroffenen Pakete zu deinstallieren und neu zu installieren. Weitere Informationen finden Sie unter Neuinstallieren und Aktualisieren von Paketen.

Wenn die Fehlermeldungen Dieses Projekt verweist auf mindestens ein NuGet-Paket, das auf diesem Computer fehlt oder Mindestens ein NuGet-Paket muss wiederhergestellt werden, dies wurde allerdings aufgrund der fehlenden Zustimmung verhindert angezeigt werden, stellen Sie sicher, dass Sie die automatische Wiederherstellung aktiviert haben. Weitere Informationen zu älteren Projekten finden Sie unter Migrieren zur automatischen Paketwiederherstellung. Sehen Sie auch Problembehandlung bei der Paketwiederherstellung.

Wiederherstellung mithilfe der dotnet-CLI

Der Dotnet-Wiederherstellungsbefehl stellt Pakete wieder her, die die Projektdatei mit <PackageReference> auflistet. Weitere Informationen finden Sie unter Paketverweis in Projektdateien.

Die Befehle dotnet build und dotnet run in .NET Core 2.0 und höher führen eine automatische Paketwiederherstellung durch. Ab NuGet 4.0 führt dotnet restore denselbe Code aus wie nuget restore.

Wiederherstellen eines Pakets mit dotnet restore:

  1. Öffnen Sie eine Befehlszeile, und wechseln Sie zu dem Verzeichnis, das Ihre Projektdatei enthält.
  2. Führen Sie dotnet restore aus.

Wichtig

Zum Hinzufügen eines fehlenden Paketverweises zur Projektdatei verwenden Sie dotnet add package. Dabei wird auch restore ausgeführt.

Wiederherstellung mithilfe der NuGet-CLI

Der NuGet CLI-Wiederherstellungsbefehl lädt alle fehlenden Pakete herunter und installiert sie. Der Befehl funktioniert für Projekte, die entweder PackageReference oder packages.config für Paketverweise verwenden.

Wie install, fügt der Befehl restore nur Pakete auf dem Datenträger hinzu, ändert aber nicht die Projektdatei oder packages.config. Verwenden Sie zum Hinzufügen von Projektabhängigkeiten die Visual Studio Paket-Manager UI oder Konsole.

Führen Sie den folgenden Befehl aus, um Pakete für Ihr Projekt wiederherzustellen:

nuget restore <projectPath>

Der Befehl restore verwendet eine Lösungsdatei oder eine package.config-Datei im angegebenen Projektpfad.

Um beispielsweise alle Pakete für MySolution.sln im aktuellen Verzeichnis wiederherzustellen, führen Sie Folgendes aus:

nuget restore MySolution.sln

Hinweis

Verwenden Sie für Projekte im Nicht-SDK-Stil, die PackageReference verwenden, msbuild -t:restore, um stattdessen Pakete wiederherzustellen.

Wiederherstellung mit MSBuild

Sie können msbuild -t:restore verwenden, um Pakete in NuGet 4.x+ und MSBuild 15.1+ wiederherzustellen, die in Visual Studio 2017 und höher enthalten sind.

Dieser Befehl stellt Pakete in Projekten wieder her, die PackageReference für Paketreferenzen verwenden. Ab MSBuild 16.5 und höher unterstützt der Befehl auch packages.config-Paketreferenzen, wenn er mit -p:RestorePackagesConfig=true verwendet wird.

Zur Verwendung von MSBuild Wiederherstellung:

  1. Öffnen Sie eine Developer-Eingabeaufforderung, indem Sie nach der Developer-Eingabeaufforderung suchen und die Eingabeaufforderung über das Windows-Startmenü starten, das alle erforderlichen Pfade für MSBuild konfiguriert.

  2. Wechseln Sie zum Projektordner, und geben Sie msbuild -t:restore ein.

  3. Nachdem die Wiederherstellung abgeschlossen ist, geben Sie msbuild ein, um das Projekt neu zu erstellen. Stellen Sie sicher, dass die MSBuild-Ausgabe angibt, dass der Build erfolgreich abgeschlossen wurde.

Hinweis

Sie können msbuild -restore verwenden, um restore auszuführen, das Projekt neu zu laden und zu erstellen, da die Erstellung das Standardziel ist. Weitere Informationen finden Sie unter Wiederherstellen und Erstellen mit einem MSBuild-Befehl.

Wiederherstellung mit Azure Pipelines oder Azure DevOps Server

Wenn Sie eine Builddefinition in Azure Pipelines erstellen, können Sie die NuGet CLI- oder die dotnet CLI-Wiederherstellungstask vor allen Build-Aufgaben in die Definition aufnehmen. Einige Buildvorlagen enthalten standardmäßig den Wiederherstellungstask.

In Azure DevOps Server und TFS 2013 und höher werden Pakete automatisch beim Build wiederhergestellt, wenn Sie eine Team Build-Vorlage für TFS 2013 oder höher verwenden. Sie können auch einen Buildschritt einbeziehen, der eine Befehlszeilenwiederherstellungsoption ausführt, oder Sie können optional die Buildvorlage zu einer späteren Version migrieren. Weitere Informationen finden Sie unter Einrichten der Paketwiederherstellung mit Team Foundation Build.

Paketversionen einschränken

NuGet stellt über eine beliebige Methode wieder her und berücksichtigt dabei alle Versionseinschränkungen, die Sie in packages.config oder der Projektdatei angeben.

  • In packages.config können Sie einen allowedVersions-Bereich in der Abhängigkeit angeben. Weitere Informationen finden Sie unter Beschränkungen für Upgrade-Versionen. Zum Beispiel:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • In einer Projektdatei können Sie den Versionsbereich in der Version-Eigenschaft der Abhängigkeit angeben. Zum Beispiel:

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

Verwenden Sie in beiden Fällen die unter Paketversionsverwaltung beschriebene Notation.

Erzwingen der Wiederherstellung aus entfernten Paketquellen

Standardmäßig werden für NuGet-Wiederherstellungsvorgänge Pakete aus den lokalen Ordnern global-packages und http-cache verwendet, wie unter Verwalten von globalen Pakete-, Cache- und temporären Ordnern beschrieben. Verwenden Sie die folgenden Optionen, um die Verwendung dieser lokalen Pakete zu vermeiden.

Um alle lokalen Caches zu löschen:

  • Wählen Sie in Visual Studio unter Tools>Optionen>NuGet Package Manager>Allgemein die Schaltfläche Alle NuGet-Cache(s) löschen.
  • Verwenden Sie dotnet nuget locals all --clear für die dotnet-CLI.
  • Verwenden Sie nuget locals all -clear für die NuGet-CLI.

Um die Verwendung der Pakete im Ordner global-packages zu vermeiden:

  • Leeren Sie den Ordner mit nuget locals global-packages -clear oder dotnet nuget locals global-packages --clear.
  • Legen Sie die Umgebungsvariable NUGET_PACKAGES vorübergehend auf einen anderen Ordner. fest.
  • Erstellen Sie eine NuGet.Config-Datei, die globalPackagesFolder für PackageReference oder repositoryPath für packages.config auf einen anderen Ordner festlegt. Weitere Informationen finden Sie unter nuget.config reference (nuget.config-Referenz).
  • Nur für MSBuild geben Sie einen anderen Ordner mit der Eigenschaft RestorePackagesPath an.

Um die Verwendung von Paketen im HTTP-Cache zu vermeiden:

  • Bereinigen Sie den Cache mit nuget locals http-cache -clear oder dotnet nuget locals http-cache --clear.
  • Legen Sie die Umgebungsvariable NUGET_HTTP_CACHE_PATH vorübergehend auf einen anderen Ordner fest.
  • Für nuget restore verwenden Sie die -NoHttpCache-Option und für dotnet restore verwenden Sie die --no-http-cache-Option. Diese Optionen haben keinen Einfluss auf die Wiederherstellungsvorgänge, die über die Visual Studio-Paket-Manager-Benutzeroberfläche oder -Konsole durchgeführt werden.

Migration zur automatischen Paketwiederherstellung

Frühere Versionen von NuGet unterstützten eine MSBuild-integrierte Paketwiederherstellung. Projekte, die die veraltete MSBuild-integrierte Paketwiederherstellung verwenden, sollten zur automatischen Paketwiederherstellung migrieren.

Diese Projekte enthalten in der Regel einen NuGet-Ordner mit drei Dateien: NuGet.config, nuget.exe und NuGet.targets. Die NuGet.targets-Datei bewirkt, dass NuGet den MSBuild-integrierten Ansatz verwendet, sodass sie entfernt werden muss.

So migrieren Sie zur automatischen Paketwiederherstellung:

  1. Aktivieren Sie die automatische Paketwiederherstellung.
  2. Schließen Sie Visual Studio.
  3. Löschen Sie .nuget/nuget.exe und .nuget/NuGet.targets.
  4. Entfernen Sie für jede Projektdatei das <RestorePackages>-Element und entfernen Sie alle Verweise auf NuGet.targets.

Um die automatische Wiederherstellung von Paketen zu testen:

  1. Entfernen Sie den Ordner packages aus der Projektmappe.
  2. Öffnen Sie die Projektmappe in Visual Studio, und starten Sie einen Buildvorgang. Durch die automatische Paketwiederherstellung wird jedes Abhängigkeitspaket heruntergeladen und installiert, ohne es der Quellcodeverwaltung hinzuzufügen.

Nächste Schritte