Freigeben über

PackageReference in Projektdateien

  • Artikel

Paketbezüge, die <PackageReference>-MSBuild Elemente verwenden, geben NuGet Paketabhängigkeiten direkt in Projektdateien an, anstatt eine separate packages.config-Datei zu haben. Die Verwendung von PackageReference hat keine Auswirkungen auf andere Aspekte von NuGet. Einstellungen in Dateien vom Typ NuGet.Config (Paketquellen eingeschlossen) gelten beispielsweise weiterhin wie unter Gängige NuGet-Konfigurationen beschrieben.

Mit PackageReference können Sie auch MSBuild-Bedingungen für die Auswahl von Paketverweisen pro Zielframework oder anderen Gruppierungen verwenden. Zudem lässt er eine präzise Steuerung der Abhängigkeiten und des Inhaltsflusses zu. (Informationen dazu finden Sie unter NuGet pack and restore as MSBuild targets – restore target (Packen und Wiederherstellen von NuGet als MSBuild-Ziele: Paketwiederherstellung).)

Unterstützung für Projekttypen

Außer für C++ UWP-Projekte wird PackageReference standardmäßig nur in .NET Core-, .NET Standard- und UWP-Projekten für Windows 10 Build 15063 (Creators Update) und höher unterstützt. .NET Framework-Projekte unterstützen PackageReference. Standardmäßig wird jedoch packages.config verwendet. Um PackageReference zu verwenden, migrieren Sie die Abhängigkeiten von packages.config zu Ihrer Projektdatei. Entfernen Sie anschließend „packages.config“.

ASP.NET-Apps für das vollständige .NET Framework enthalten nur eingeschränkte Unterstützung für PackageReference. C++- und JavaScript-Projekttypen werden nicht unterstützt.

Hinzufügen einer PackageReference

Fügen Sie mit der folgenden Syntax eine Abhängigkeit in Ihrer Projektdatei hinzu:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Steuern die Abhängigkeitsversion

Die Konvention für die Angabe der Version eines Pakets entspricht der Verwendung von packages.config:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Im obigen Beispiel steht 3.6.0 für eine beliebige Version >= 3.6.0, wobei die niedrigste Version bevorzugt wird, wie unter Paketversionsverwaltung beschrieben.

Verwenden von PackageReference für ein Projekt ohne Paketabhängigkeiten

Erweitert: Wenn Sie keine Pakete in einem Projekt installiert haben (keine PackageReferences in der Projektdatei oder der packages.config-Datei), aber das Projekt mit dem Format von PackageReference wiederherstellen möchten, können Sie in der Projektdatei eine RestoreProjectStyle-Projekteigenschaft auf PackageReference festlegen.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>

Dies kann sich als nützlich erweisen, wenn Sie auf Projekte verweisen, die das Format von PackageReference aufweisen (vorhandene Projekte im CSPROJ- oder SDK-Format). Dadurch kann Ihr Projekt „transitiv“ auf die Pakete verweisen, auf die diese Projekte verweisen.

PackageReference und Quellen

In PackageReference-Projekten werden transitive Abhängigkeitsversionen zur Wiederherstellungszeit aufgelöst. Daher müssen in PackageReference-Projekten alle Quellen für alle Wiederherstellungen verfügbar sein.

Unverankerte Versionen

Unverankerte Versionen werden mit PackageReference unterstützt:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
    <!-- ... -->
</ItemGroup>

Steuern von Abhängigkeitsobjekten

Sie verwenden eine Abhängigkeit möglicherweise rein als Entwicklungsumgebung und möchten diese nicht für Projekte verfügbar machen, die Ihr Paket nutzen. In diesem Szenario können Sie dieses Verhalten über die PrivateAssets-Metadaten steuern.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Mit den folgenden Metadatentags werden Abhängigkeitsobjekte gesteuert:

Tag Beschreibung Standardwert
IncludeAssets Diese Objekte werden verbraucht all
ExcludeAssets Diese Objekte werden nicht verbraucht keine
PrivateAssets Diese Objekte werden verbraucht, aber nicht in das übergeordnete Projekt übertragen contentfiles;analyzers;build

Folgende Werte sind für diese Tags zulässig, wobei mehrere Werte durch ein Semikolon (;) getrennt sind; eine Ausnahme stellen all und none dar, die nur alleine dargestellt werden dürfen:

Wert Beschreibung
Compile Inhalt des Ordners lib und steuert, ob Ihr Projekt anhand der Assemblys im Ordner kompiliert werden kann
runtime Inhalt der Ordner lib und runtimes und steuert, ob diese Assemblys in das Buildausgabeverzeichnis kopiert werden
contentFiles Inhalte des Ordners contentfiles
build .props und .targets im Ordner build
buildMultitargeting (4.0) .props und .targets im Ordner buildMultitargeting für frameworkübergreifende Zielplattformen
buildTransitive (5.0 und höher) .props und .targets im Ordner buildTransitive für Ressourcen, die transitiv in beliebige verarbeitende Projekte eingefügt werden. Weitere Informationen finden Sie auf der Seite Feature.
analyzers .NET-Analystetools
Systemeigen Inhalte des Ordners native
keine Keiner der obigen Werte wird verwendet.
all Alle oben genannten Werte (mit Ausnahme von none) 
<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

Beachten Sie Folgendes: Da build nicht in PrivateAssets enthalten ist, werden Ziele und Eigenschaften an das übergeordnete Projekt übergeben. Angenommen, der obenstehende Verweis wird in einem Projekt verwendet, in dem ein NuGet-Paket mit dem Namen AppLogger erstellt wird. AppLogger kann die Ziele und Eigenschaften aus Contoso.Utility.UsefulStuff verarbeiten, wie Projekte, die AppLogger verarbeiten.

Hinweis

Wenn developmentDependency in einer .nuspec-Datei auf true festgelegt ist, kennzeichnet dies ein Paket mit einer Abhängigkeit, die nur für die Entwicklung gilt. Dadurch wird vermieden, dass das Paket als Abhängigkeit in andere Pakete eingefügt wird. Bei PackageReference (NuGet 4.8+) bedeutet dieses Flag auch, dass Objekte zur Kompilierzeit von der Kompilierung ausgeschlossen werden. Weitere Informationen finden Sie unter DevelopmentDependency support for PackageReference (DevelopmentDependency-Unterstützung für PackageReference).

Hinzufügen einer PackageReference-Bedingung

Sie können mithilfe einer Bedingung steuern, ob ein Paket eingeschlossen wird. Dabei kann in Bedingungen eine beliebige MSBuild-Variable oder eine in der Ziel- oder Eigenschaftendatei definierte Variable verwendet werden. Zum aktuellen Zeitpunkt wird jedoch nur die Variable TargetFramework unterstützt.

Angenommen, Ihre Zielgruppen lauten netstandard1.4 und net452, die vorhandene Abhängigkeit gilt jedoch nur für net452. In diesem Fall sollte diese unnötige Abhängigkeit nicht zu einem netstandard1.4-Projekt hinzugefügt werden, in dem Ihr Paket verwendet wird. Sie geben in der PackageReference eine Bedingung an, um dies zu verhindern, die wie folgt lautet:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Ein Paket, das in diesem Projekt erstellt wurde, zeigt an, dass die Datei „Newtonsoft.json“ nur als Abhängigkeit für ein net452-Ziel enthalten ist:

Das Ergebnis der Anwendung einer Bedingung auf die PackageReference mit VS2017

Bedingungen können auch auf der ItemGroup-Ebene angewendet werden und gelten dann für alle untergeordneten PackageReference-Elemente:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

Dieses Feature ist mit NuGet 5.0 oder höher und mit Visual Studio 2019 16.0 oder höher verfügbar.

Manchmal ist es wünschenswert, von einem MSBuild-Ziel aus auf Dateien in einem Paket zu verweisen. In packages.config-basierten Projekten werden die Pakete in einem Ordner mit Bezug zur Projektdatei installiert. Bei PackageReference werden die Pakete hingegen aus dem Ordner global-packages verwendet, der von Computer zu Computer variieren kann.

Um diese Lücke zu schließen, wurde in NuGet eine Eigenschaft eingeführt, die auf den Speicherort verweist, von dem aus das Paket verwendet wird.

Beispiel:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

Zusätzlich werden von NuGet automatisch Eigenschaften für Pakete generiert, die einen Tools-Ordner enthalten.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

MSBuild-Eigenschaften und Paketidentitäten haben nicht die gleichen Einschränkungen, sodass die Paketidentität in einen MSBuild-Anzeigenamen geändert werden muss, dem das Wort Pkg vorangestellt ist. Beachten Sie die generierte nuget.g.props-Datei, um den genauen Namen der generierten Eigenschaft zu überprüfen.

PackageReference-Aliasse

In einigen seltenen Fällen enthalten verschiedene Pakete Klassen im selben Namespace. Ab NuGet 5.7 und Visual Studio 2019 Update 7 unterstützt PackageReference ebenso wie ProjectReference Aliases. Standardmäßig stehen keine Aliasse zur Verfügung. Wenn ein Alias angegeben wird, muss mit dem Alias auf alle Assemblys verwiesen werden, die aus dem kommentierten Paket stammen.

Eine Beispielverwendung finden Sie unter NuGet\Samples.

In der Projektdatei können Sie die Aliasse folgendermaßen angeben:

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

Die Verwendung im Code erfolgt folgendermaßen:

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

NuGet-Warnungen und -Fehler

Dieses Feature ist mit NuGet 4.3 oder höher und mit Visual Studio 2017 15.3 oder höher verfügbar.

Für viele Pack- und Wiederherstellungsszenarios werden alle NuGet-Warnungen und -Fehler codiert, und sie beginnen mit NU****. Alle NuGet-Warnungen und -Fehler sind in der Referenz-Dokumentation aufgeführt.

NuGet beachtet die folgenden Warnungseigenschaften:

  • TreatWarningsAsErrors, alle Warnungen als Fehler behandeln
  • WarningsAsErrors, bestimmte Warnungen als Fehler behandeln
  • NoWarn, bestimmte Warnungen ausblenden, entweder projekt- oder paketweit.

Beispiele:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

Unterdrücken von NuGet-Warnungen

Es wird empfohlen, alle NuGet-Warnungen während der Pack- und Wiederherstellungsvorgänge aufzulösen; in bestimmten Situationen wird deren Auflösung verlangt. Für die projektweite Unterdrückung einer Warnung sollten Sie Folgendes in Erwägung ziehen:

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

Gelegentlich beziehen sich Warnungen nur auf ein bestimmtes Paket im Graph. Sie können eine solche Warnung selektiv unterdrücken, indem Sie im PackageReference-Element NoWarn hinzufügen.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Unterdrücken von Warnungen für NuGet-Pakete in Visual Studio

In Visual Studio ist das Unterdrücken von Warnungen auch über die IDE möglich.

Sperren von Abhängigkeiten

Dieses Feature ist mit NuGet 4.9 oder höher und mit Visual Studio 2017 15.9 oder höher verfügbar.

Die Eingabe für die NuGet-Wiederherstellung ist ein Satz von PackageReference-Elementen aus der Projektdatei (oberste Ebene oder direkte Abhängigkeiten). Die Ausgabe ist der vollständige Abschluss aller Paketabhängigkeiten einschließlich transitiver Abhängigkeiten. NuGet versucht immer, den gleichen vollständigen Abschluss von Paketabhängigkeiten zu erzeugen, wenn sich die PackageReference-Eingabeliste nicht geändert hat. Es gibt jedoch einige Szenarien, in denen dies nicht möglich ist. Zum Beispiel:

  • Beim Verwenden von unverankerten Versionen wie <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Während die Absicht hierbei darin liegt, bei jeder Wiederherstellung die neueste Version zu verwenden, gibt es Szenarien, in denen Benutzer anfordern, dass der Paketgraph auf eine bestimmte neueste Version festgelegt und zu einem späteren Zeitpunkt ggf. explizit eine höhere Version geändert werden kann.

  • Eine neuere Version des Pakets, die den Anforderungen an die PackageReference-Version entspricht, wird veröffentlicht. z. B.

    • Tag 1: Sie haben <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> angegeben, aber die in den NuGet-Repositorys verfügbaren Versionen waren 4.1.0, 4.2.0 und 4.3.0. In diesem Fall verwendet NuGet die Version 4.1.0 (die nächste verfügbare Mindestversion).

    • Tag 2: Version 4.0.0 wird veröffentlicht. NuGet findet jetzt die exakte Übereinstimmung und beginnt mit der Verwendung von 4.0.0.

  • Eine bestimmte Paketversion wird aus dem Repository entfernt. Auch wenn nuget.org das Löschen von Paketen nicht erlaubt, weisen nicht alle Paketrepositorys diese Einschränkung auf. Daher sucht NuGet nach der besten Übereinstimmung, wenn die gelöschte Version nicht verwendet werden kann.

Aktivieren der Sperrdatei

Um den vollständigen Abschluss von Paketabhängigkeiten beizubehalten, können Sie die Funktion einer Sperrdatei einrichten, indem Sie die MSBuild-Eigenschaft RestorePackagesWithLockFile für Ihr Projekt festlegen:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>

Wenn diese Eigenschaft festgelegt ist, generiert NuGet eine Sperrdatei – packages.lock.json-Datei – im Projektstammverzeichnis, die alle Paketabhängigkeiten auflistet.

Hinweis

Sobald ein Projekt eine packages.lock.json-Datei im Stammverzeichnis enthält, wird die Sperrdatei bei der Wiederherstellung immer verwendet, auch wenn die Eigenschaft RestorePackagesWithLockFile nicht festgelegt ist. Eine andere Möglichkeit zur Verwendung dieser Funktion besteht also darin, eine leere packages.lock.json-Dummydatei im Stammverzeichnis des Projekts zu erstellen.

restore-Verhalten mit Sperrdatei

Wenn für ein Projekt eine Sperrdatei vorhanden ist, verwendet NuGet diese Sperrdatei zum Ausführen von restore. NuGet überprüft, ob Änderungen an den Paketabhängigkeiten vorgenommen wurden, die in der Projektdatei (bzw. in Projektdateien von abhängigen Projekten) definiert wurden. Wenn keine Änderungen vorhanden sind, stellt NuGet einfach die in der Sperrdatei angegebenen Pakete wieder her. Es erfolgt keine erneute Auswertung der Paketabhängigkeiten.

Wenn NuGet eine Änderung bei den in den Projektdateien definierten Abhängigkeiten ermittelt, wird der Paketgraph erneut ausgewertet, und die Sperrdatei wird aktualisiert, um den neuen Paketabschluss für das Projekt widerzuspiegeln.

Für CI/CD- und andere Szenarien, in denen Paketabhängigkeiten nicht dynamisch geändert werden dürfen, können Sie dies erreichen, indem Sie lockedmode auf true festlegen:

Führen Sie für dotnet.exe folgenden Befehl aus:

> dotnet.exe restore --locked-mode

Führen Sie für msbuild.exe folgenden Befehl aus:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

Sie können diese bedingte MSBuild-Eigenschaft auch in Ihrer Projektdatei festlegen:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup>

Wenn der Sperrmodus true lautet, gilt Folgendes: Bei der Wiederherstellung werden entweder die Pakete genau so wiederhergestellt wie in der Sperrdatei aufgelistet, oder es tritt ein Fehler auf, wenn Sie die definierten Paketabhängigkeiten für das Projekt nach dem Erstellen der Sperrdatei aktualisiert haben.

Einbinden der Sperrdatei als Teil Ihres Quellrepositorys

Wenn Sie eine Anwendung oder eine ausführbare Datei erstellen und sich das fragliche Projekt am Anfang der Abhängigkeitskette befindet, checken Sie die Sperrdatei im Quellcoderepository ein, damit NuGet diese während der Wiederherstellung verwenden kann.

Wenn es sich bei Ihrem Projekt aber um ein nicht auszulieferndes Bibliotheksprojekt oder ein Projekt mit gemeinsamem Code handelt, von dem andere Projekte abhängig sind, sollten Sie die Sperrdatei nicht als Teil Ihres Quellcodes einchecken. Es schadet nicht, die Sperrdatei zu behalten, aber die gesperrten Paketabhängigkeiten für das Projekt mit gemeinsamem Code werden möglicherweise während der Wiederherstellung bzw. Erstellung eines Projekts, das von diesem Projekt mit gemeinsamem Code abhängig ist, nicht wie in der Sperrdatei aufgelistet verwendet.

Beispiel:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Wenn ProjectA eine Abhängigkeit von einer PackageX-Version 2.0.0 aufweist und auch auf ProjectB verweist, das von der PackageX-Version 1.0.0 abhängig ist, listet die Sperrdatei für ProjectB eine Abhängigkeit von der PackageX-Version 1.0.0 auf. Wenn ProjectA jedoch erstellt wird, enthält die Sperrdatei eine Abhängigkeit von der PackageX-Version 2.0.0 und nicht von 1.0.0, wie in der Sperrdatei für ProjectB aufgelistet. Daher hat die Sperrdatei eines Projekts mit gemeinsamem Code nur wenig Aussagekraft für die verwendeten Pakete für Projekte, die von diesem Projekt abhängig sind.

Erweiterbarkeit der Sperrdatei

Sie können mit einer Sperrdatei verschiedene Verhaltensweisen der Wiederherstellung steuern, wie im Folgenden beschrieben:

NuGet.exe-Option dotnet-Option Entsprechende MSBuild-Option Beschreibung
-UseLockFile --use-lock-file RestorePackagesWithLockFile Ermöglicht die Verwendung einer Sperrdatei.
-LockedMode --locked-mode RestoreLockedMode Ermöglicht den Sperrmodus für die Wiederherstellung. Dies ist nützlich in CI/CD-Szenarien, in denen Sie wiederholbare Builds wünschen.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Diese Option ist nützlich bei Paketen, bei denen im Projekt unverankerte Versionen definiert sind. Standardmäßig aktualisiert die NuGet-Wiederherstellung die Paketversion nicht automatisch bei jedem Wiederherstellungsvorgang, wenn Sie diesen Vorgang nicht mit dieser Option ausführen.
-LockFilePath --lock-file-path NuGetLockFilePath Definiert einen benutzerdefinierten Speicherort der Sperrdatei für ein Projekt. Standardmäßig unterstützt NuGet packages.lock.json im Stammverzeichnis. Wenn Sie über mehrere Projekte im gleichen Verzeichnis verfügen, unterstützt NuGet die projektspezifische Sperrdatei packages.<project_name>.lock.json.

NuGet-Abhängigkeitslöser

Der NuGet-Abhängigkeitslöser folgt den vier Regeln, wie im Dokument zur Abhängigkeitslösung beschrieben.

Um die Leistung und Skalierbarkeit des Wiederherstellungsvorgangs zu verbessern, wurde der Wiederherstellungsalgorithmus in der Version 6.12 umgeschrieben. Ab der Version 6.12 ist der neue Wiederherstellungsalgorithmus für alle PackageReference-Projekte standardmäßig aktiviert. Der neue Wiederherstellungsalgorithmus ist zwar funktionell gleichwertig mit dem vorherigen, aber wie bei jeder Software sind Fehler möglich. Wenn Sie zur vorherigen Implementierung zurückkehren möchten, stellen Sie die MSBuild-Eigenschaft RestoreUseLegacyDependencyResolver auf true.

Sollten Sie Wiederherstellungsfehler in 6.12, .NET 9 oder 17.12 feststellen, die in früheren Versionen nicht reproduzierbar waren, melden Sie bitte einen Fehler auf GitHub. Etwaige Unterschiede zwischen dem alten und dem neuen Algorithmus können sich unterschiedlich auswirken, z. B. bei der Kompilierung oder zur Laufzeit. Es besteht auch die Möglichkeit, dass Änderungen nicht zu Fehlern führen, sondern dass unterschiedliche Paketversionen wiederhergestellt werden. Wenn Sie glauben, dass Sie von den Änderungen betroffen sind, können Sie mit den folgenden Schritten überprüfen, ob die Änderungen am NuGet-Wiederherstellungsalgorithmus die Ursache dafür sind.

Stellen Sie die Ergebnisse im MSBuildProjectExtensionsPath-Verzeichnis wieder her, die mit den neuen und alten Algorithmen verglichen werden können, um Unterschiede zu finden. In der Regel ist dies der obj-Ordner Ihres Builds. Für die nächsten Schritte können Sie msbuild.exe oder dotnet.exe verwenden.

  1. Entfernen Sie den obj-Ordner für Ihr Projekt.
  2. Ausführen von msbuild -t:restore
  3. Speichern Sie den Inhalt von obj an einem Ort, der angibt, dass es sich um das Verhalten von new handelt.
  4. Ausführen von msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"
  5. Speichern Sie den Inhalt von obj an einem Ort, der angibt, dass es sich um das Verhalten von legacy handelt.
  6. Vergleichen Sie die Dateien in den beiden Verzeichnissen, insbesondere project.assets.json. Tools, die Unterschiede hervorheben können, sind hierfür besonders nützlich (z. B. Visual Studio Code, öffnen Sie beide Dateien und klicken Sie mit der rechten Maustaste auf „Zum Vergleich auswählen“ und „Mit ausgewähltem vergleichen“)

Wenn Sie der obigen Methode folgen, sollte genau 1 Unterschied zwischen den project.assets.json Dateien bestehen:

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

Wenn es weitere Unterschiede gibt, melden Sie bitte einen Fehler auf GitHub mit allen Details.

AssetTargetFallback

Mit der Eigenschaft AssetTargetFallback können Sie zusätzliche kompatible Frameworkversionen für Projekte angeben, auf die Ihr Projekt verweist, sowie Frameworkversionen für NuGet-Pakete angeben, die Ihr Projekt nutzt.

Wenn Sie mit PackageReference eine Paketabhängigkeit angeben, aber das entsprechende Paket keine Objekte enthält, die mit dem Zielframework Ihres Projekts kompatibel sind, kommt die Eigenschaft AssetTargetFallback ins Spiel. Die Kompatibilität des referenzierten Pakets wird erneut anhand jedes Zielframeworks überprüft, das in AssetTargetFallback angegeben ist. Wenn über AssetTargetFallback auf project oder package verwiesen wird, wird die Warnung NU1701 ausgelöst.

In der Tabelle unten finden Sie Beispiele, wie sich AssetTargetFallback auf die Kompatibilität auswirkt.

Projektframework AssetTargetFallback Paketframeworks Ergebnis
.NET Framework 4.7.2 .NET-Standard 2.0 .NET-Standard 2.0
.NET Core 3.1-App .NET Standard 2.0, .NET Framework 4.7.2 .NET-Standard 2.0
.NET Core 3.1-App .NET Framework 4.7.2 Inkompatibel: Bei NU1202 tritt ein Fehler auf.
.NET Core 3.1-App net472;net471 .NET Framework 4.7.2 .NET Framework 4.7.2 mit NU1701

Mithilfe von ; als Trennzeichen können mehrere Frameworks angegeben werden. Wenn Sie ein Fallbackframework hinzufügen möchten, haben Sie die folgende Möglichkeit:

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

Sie können $(AssetTargetFallback) auslassen, wenn Sie eine Überschreibung durchführen möchten, anstatt eine Hinzufügung zu den vorhandenen AssetTargetFallback-Werten vorzunehmen.

Hinweis

Wenn Sie ein auf dem .NET SDK basierendes Projekt verwenden, werden entsprechende $(AssetTargetFallback)-Werte konfiguriert. Sie müssen diese nicht manuell festlegen.

Bei $(PackageTargetFallback) handelt es sich um ein früheres Feature, das diese Herausforderung lösen sollte. Dieses Feature funktioniert jedoch nicht und sollte nicht verwendet werden. Wenn Sie von $(PackageTargetFallback) zu $(AssetTargetFallback) migrieren möchten, ändern Sie einfach den Eigenschaftenname.