Neuinstallation und Aktualisierung von NuGet-Paketen in Visual Studio

  • Artikel

Manchmal können Paketreferenzen innerhalb eines Visual Studio-Projekts unterbrechen. Durch Deinstallation und Neuinstallation der gleichen Version des Pakets werden die Referenzen oft wieder in Ordnung gebracht. Die Aktualisierung eines Pakets, die eine aktualisierte Version installiert, kann auch das Problem beheben. In diesem Artikel wird beschrieben, wie NuGet-Pakete neu installiert und aktualisiert werden, um fehlerhafte Paketreferenzen und Projekte zu beheben.

Hinweis

Die Anleitung in diesem Artikel gilt nur für Projekte, die das Verwaltungsformat packages.config verwenden. Bei PackageReference-Projekten behebt ein Wiederherstellungsvorgang automatisch fehlerhafte Verweise.

Gängige Szenarios

Nachfolgend finden Sie einige häufige Szenarien, in denen fehlerhafte Paketreferenzen in Ihrem Visual Studio-Projekt auftreten können.

Szenario Beschreibung Lösung
Fehlerhafte Verweise nach der Paketwiederherstellung Sie öffnen Ihr Visual Studio-Projekt und stellen NuGet-Pakete wieder her, aber die fehlerhaften Paketreferenzen bleiben bestehen. Um die Verweise zu beheben, versuchen Sie, jedes Paket einzeln neu zu installieren.
Fehlerhaftes Projekt aufgrund von gelöschten Dateien Gelöschte (fehlende) Paketdateien führen dazu, dass Ihr Projekt abgebrochen wird. NuGet verhindert nicht das Löschen von Elementen, die Sie aus Paketen hinzufügen. Es kann leicht sein, versehentlich installierte Inhalte aus einem Paket zu ändern und Ihr Projekt zu unterbrechen. Um Ihr Projekt wiederherzustellen, versuchen Sie, die betroffenen Pakete neu zu installieren.
Fehlerhaftes Projekt nach Paketaktualisierung Eine Paketaktualisierung unterbricht Ihr Projekt. Aktualisierungen von Assistenten für ein Abhängigkeitspaket führen in der Regel zu diesem Fehlertyp. Um den Zustand der Abhängigkeit wiederherzustellen, versuchen Sie, das betreffende abhängige Paket neu zu installieren.
Fehlerhafte Verweise nach Projekt-Neuausrichtung oder Upgrade Ein Projekt-Ausrichtung- oder Upgrade-Prozess verursacht fehlerhafte Paketreferenzen. Nachdem Sie Ihr Projekt neu erstellt haben, zeigt NuGet einen Buildfehler an. Build-Warnungen listen Pakete auf, die möglicherweise neu installiert werden müssen. Oder NuGet zeigt nach dem Upgrade Ihres Projekts einen Fehler im Projekt-Upgrade-Protokoll an. Die Protokolldatei listet Pakete auf, die möglicherweise neu installiert werden müssen. Um Probleme aufgrund einer Änderung im Zielframework zu beheben, versuchen Sie, ein oder mehrere Pakete neu zu installieren.
Paketänderungen in der Entwicklung Paketautoren müssen häufig die gleiche Version eines Pakets, das sie gerade entwickeln, neu installieren, um ihre Änderungen zu testen. In Visual Studio bietet die Paket-Manager-Konsole zahlreiche flexible Optionen für die Aktualisierung und erneute Installation von Paketen. Um ein Paket unter der Entwicklung neu zu installieren, können Sie den Befehl Update-Package -reinstall verwenden.

Optionen für die Implementierung

Sie haben mehrere Möglichkeiten, um NuGet-Pakete zu aktualisieren und neu zu installieren. Gängige Methoden sind die NuGet Package Manager UI Optionen, die NuGet Package Manager Console und die NuGet-CLI (Befehlszeilenschnittstelle).

Benutzeroberfläche des Paket-Managers

Zusätzlich zur Konsolenschnittstelle bietet die Package Manager UI auch Menüoptionen zum Installieren, Aktualisieren und Deinstallieren von Paketen.

  • Um ein Paket zu aktualisieren, öffnen Sie die Registerkarte Aktualisierungen, wählen Sie ein oder mehrere Pakete aus, und wählen Sie dann Aktualisieren aus.

  • Um ein Paket erneut zu installieren, deinstallieren Sie zuerst das Paket und installieren Sie es dann erneut. Öffnen Sie die Registerkarte Installiert wählen Sie ein Paket aus, notieren Sie seinen Namen und wählen Sie dann Deinstallieren. Wechseln Sie zur Registerkarte Durchsuchenund suchen Sie nach dem Paketnamen, wählen Sie das Paket aus und klicken Sie dann Installieren.

Paket-Manager-Konsole

Sie haben Zugriff auf die Package Manger Console unter Extras>NuGet-Paket-Manager>Paket-Manager-Konsole.

  • Um ein Paket zu aktualisieren, bietet die Paketmanager-Konsole den Befehl Update-Package.

  • Um ein Paket neu zu installieren, können Sie denselben Befehl mit dem -reinstall-Parameter verwenden. Dieser Ansatz ist die einfachste Option, wenn er mit Ihrer Konfiguration kompatibel ist.

Weitere Informationen finden Sie in den Abschnitten Update-Package-Befehl und Überlegungen zur Neuinstallation von Paketen.

NuGet CLI

NuGet CLI, nuget.exe, ist das Befehlszeilen-Hilfsprogramm für Windows, das alle NuGet-Funktionen bereitstellt.

  • Um ein installiertes Paket zu aktualisieren, führen Sie den Befehl nuget update aus.

  • Um alle NuGet-Pakete neu zu installieren, löschen Sie den Paketordner und führen Sie dann den Befehl nuget install aus.

  • Um ein einzelnes Paket erneut zu installieren, löschen Sie den Paketordner, und führen Sie dann den Befehl nuget install <id> aus, wobei das <id>-Argument die ID des spezifischen Pakets ist.

Hinweis

Für die dotnet-CLI ist das entsprechende Verfahren nicht erforderlich. Wenn Sie den Befehl dotnet restore ausführen, verwendet die dotnet-CLI NuGet, um Abhängigkeiten zu ermitteln und alle erforderlichen NuGet-Pakete herunterzuladen. Weitere Informationen finden Sie unter Wiederherstellung von NuGet-Paketen mit der dotnet-CLI.

Einschränkungen für Upgrade-Versionen

Standardmäßig wird durch die Neuinstallation oder das Update eines Pakets immer die neueste verfügbare Version aus der Paketquelle installiert. Projekte, die das packages.config-Verwaltungsformat verwenden, können jedoch speziell den zulässigen NuGet-Paketversionsbereich einschränken.

Angenommen, Ihre Anwendung funktioniert nur mit Version 1.x eines Pakets, aber nicht mit Version 2.0 oder höher, weil die API des Pakets wesentlich geändert wurde. Um sicherzustellen, dass Ihre Anwendung wie erwartet funktioniert, möchten Sie nur NuGet-Paketupgrades auf Versionen 1.x beschränken. Die Einschränkung trägt dazu bei, versehentliche Aktualisierungen zu verhindern, die Ihre Anwendung möglicherweise unterbrechen.

Um eine Einschränkung festzulegen, öffnen Sie die packages.config-Konfigurationsdatei in einem Text-Editor. Suchen Sie die Abhängigkeit, die Sie einschränken möchten, und fügen Sie das allowedVersions-Attribut mit dem gewünschten Versionsbereich hinzu.

Das folgende Beispiel zeigt, wie Aktualisierungen auf die Version 1.x eingeschränkt werden können, indem das allowedVersions-Attribut auf [1,2) festgelegt wird:

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="ExamplePackage" version="1.1.0" allowedVersions="[1,2)" />

    <!-- ... -->
</packages>

Verwenden Sie in jedem Fall die unter Paketversionsverwaltung beschriebene Notation.

Update-Package-Befehl

Der Befehl Update-Paket in der Paket-Manager Konsole ist die einfachste Möglichkeit, ein Paket neu zu installieren und fehlerhafte Referenzen zu korrigieren. Dieser Ansatz kann jedoch nicht in allen Szenarien verwendet werden. Sie können den Befehl verwenden, um ein installiertes Paket zu aktualisieren, aber nicht um eine Erstinstallation durchzuführen. Wenn Sie versuchen, ein Paket zu aktualisieren oder neu zu installieren, das in der Konfiguration noch nicht installiert ist, gibt der Befehl einen Fehler zurück. Überprüfen Sie vor dem Arbeiten mit dem Befehl unbedingt den Abschnitt Überlegungen zur Neuinstallation von Paketen.

Mit einer Aktualisierung von Paketen in einem Projekt oder einer Projektmappe mithilfe von PackageReference, wird immer eine Aktualisierung auf die neueste Version des Pakets ausgeführt (Paketvorabversionen sind davon ausgeschlossen). Projekte, die das packages.config-Verwaltungsformat verwenden, können Upgrade-Versionen begrenzen, wie in Einschränkungen für Upgrade-Versionen beschrieben.

Die folgenden Abschnitte enthalten Beispiele für die Arbeit mit diesem Befehl.

Optionen zum Paket neu installieren

Hier ist eine grundlegende Verwendung des Befehls für eine Neuinstallation. Um ein bestimmtes NuGet-Paket zu identifizieren, können Sie den optionalen -Id-Parameter verwenden.

# Reinstall the package named <package_name>
Update-Package -Id <package_name> –reinstall

Die Verwendung des Update-Package-Befehls ist einfacher als das Entfernen eines Pakets und der anschließende Versuch, dasselbe Paket im NuGet-Katalog mit der gleichen Version zu finden.

Update-Package-Optionen

Wenn Sie den gleichen Befehl ohne den -reinstall-Parameter verwenden, wird ein Paket auf die neuere Version aktualisiert (falls zutreffend). Der Befehl gibt einen Fehler zurück, wenn das angegebene Paket nicht bereits in einem Projekt installiert ist.

# Update the package named <package_name>
Update-Package <package_name>

Projekt- und Projektmappenoptionen

Standardmäßig wirkt sich der Befehl Update-Package auf alle Projekte in einer Projektmappe aus. Verwenden Sie den -ProjectName-Parameter, um die Aktion auf ein bestimmtes Projekt zu beschränken. Geben Sie den Namen des Projekts an, wie er in Visual Studio Projektmappen-Explorer angezeigt wird.

Mit dem folgenden Befehl wird ein NuGet-Paket für ein bestimmtes Projekt in Ihrer Lösung neu installiert. Der Name des spezifischen NuGet-Pakets, das neu installiert werden soll, wird im <package_name>-Parameter angegeben.

# Reinstall the package named <package_name> in MyProject only
Update-Package <package_name> -ProjectName MyProject -reinstall

Wenn Sie alle Pakete in Ihrem Projekt erneut installieren möchten, verwenden Sie den -ProjectName-Parameter, indem Sie kein bestimmtes Paket angeben. Sie können diesem Ansatz folgen, um die Pakete in Ihrem Projekt zu aktualisieren, wie in diesem Beispiel gezeigt:

# Update all packages in MyProject only
Update-Package -ProjectName MyProject

Um alle Pakete in einer Lösung zu aktualisieren, verwenden Sie einfach den Befehl Update-Package ohne weitere Argumente oder Parameter.

Wichtig

Achten Sie darauf, die folgende Form des Befehls sorgfältig zu verwenden. Der Befehlsvorgang kann erhebliche Zeit in Anspruch nehmen, um alle Aktualisierungen auszuführen.

# Update all packages in all projects in the solution
Update-Package

Überlegungen zur Neuinstallation des Pakets

Wenn Sie den Befehl Update-Package verwenden möchten, um Pakete neu zu installieren, lesen Sie die folgenden Überlegungen, um die Kompatibilität mit Ihrem Konfigurationsszenario sicherzustellen.

  • Pakete und deren Abhängigkeiten unterstützen möglicherweise kein neu ausgerichtetes Projektzielframework.
  • Wenn das requireReinstallation-Attribut auf true festgelegt ist, gibt Visual Studio Buildwarnungen für betroffene Pakete aus.
  • Die Erneute Installation von Paket- und Versionsbeschränkungen kann Zu Kompatibilitätsprobleme mit Abhängigkeitsversionen führen.
  • Eine erneute Installation eines bestimmten Pakets kann dazu führen, dass abhängige Pakete nicht mehr funktionieren.

Das Paket unterstützt nicht das Projektzielframework

Wenn Sie Ihr Projektzielframework neu zuweisen, unterstützt möglicherweise mindestens ein Paket die neue Zielkonfiguration nicht.

In der Regel funktioniert das erneute Installieren eines Pakets mit dem Befehl Update-Package –reinstall <package_name>. Ein Paket, das für ein altes Zielframework installiert wurde, wird deinstalliert, und das gleiche Paket wird für das neue Zielframework des Projekts installiert.

In einigen Fällen kann es vorkommen, dass ein Paket das neue Zielframework nicht unterstützt. Hier sind einige der Probleme, die auftreten können:

  • Wenn ein Paket portable Klassenbibliotheken (Portable Class Libraries, PCLs) unterstützt, und Sie das Projekt auf eine Kombination von Plattformen neu ausrichten, die nicht mehr von dem Paket unterstützt werden, können nach der Neuinstallation Referenzen auf das Paket fehlen.

  • Dieses Problem kann bei Paketen auftreten, die Sie direkt verwenden, oder bei Paketen, die als Abhängigkeiten installiert sind. Jedes Paket, das Sie direkt verwenden, unterstützt möglicherweise das neue Zielframework, während dessen Abhängigkeiten dies nicht tun.

  • Wenn Sie Pakete nach der Neuzuweisung Ihrer Anwendungsergebnisse in Build- oder Runtime-Fehlern neu installieren, sollten Sie Ihr Zielframework wiederherstellen oder nach alternativen Paketen suchen, die Ihr neues Zielframework ordnungsgemäß unterstützen.

requireReinstallation-Attribut auf TRUE festgelegt

Nachdem Sie Ihr Projektzielframework neu erstellt oder NuGet-Pakete aktualisiert haben, kann NuGet das requireReinstallation-Attribut der packages.config-Datei für Ihr Projekt hinzufügen. Wenn NuGet während des Neuausrichtungsprozesses oder des Upgrades betroffene Pakete erkennt, fügt es der requireReinstallation="true"-Datei für alle betroffenen Paketreferenzen ein packages.config-Attribut hinzu. Daher werden bei jedem nachfolgenden Build Ihres Projekts in Visual Studio Build-Warnungen für diese Pakete ausgegeben. Die Warnungen dienen als Erinnerung daran, das betroffene Paket neu zu installieren.

Inkompatibilität der Paketabhängigkeitsversion

Der Befehl Update-Package –reinstall installiert die gleiche Version eines installierten Pakets und die neueste Version aller Abhängigkeiten neu. Um Versionsinkompatibilitätsprobleme zu beheben, können Sie Versionsbereichseinschränkungen festlegen, um die Konfiguration zu steuern. NuGet hält sich an die Einschränkungen und aktualisiert die Paketabhängigkeiten nur bei Bedarf, um ein Problem zu beheben.

  • Wenn Ihre Einschränkungseinstellungen dazu führen, dass eine Abhängigkeit bei der Neuinstallation eines Pakets zu einer früheren Version zurückkehrt, können Sie das Problem mit dem Befehl Update-Package <dependency_name> beheben. Dieser Befehl installiert die angegebene Abhängigkeit neu, ohne das abhängige Paket zu verändern.

  • Sie können auch den Befehl Update-Package –reinstall <packageName> -ignoreDependencies verwenden. Mit dieser Option wird die gleiche Version des ursprünglichen Pakets neu installiert, jedoch nicht die Abhängigkeiten. Verwenden Sie diesen Ansatz, wenn die Aktualisierung von Paketabhängigkeiten zu einem fehlerhaften Konfigurationsstatus führen könnte.

Fehlerhaftes abhängiges Paket

Wenn Sie ein bestimmtes Paket erneut installieren, werden alle installierten Pakete, die vom neu installierten Paket abhängen, nicht aktualisiert. Die Versionen dieser anderen installierten Pakete bleiben gleich. Daher kann das erneute Installieren einer Abhängigkeit ein abhängiges Paket unterbrechen.