Delen via


PackageReference in projectbestanden

Pakketverwijzingen, met behulp van <PackageReference> MSBuild-items, geven nuGet-pakketafhankelijkheden rechtstreeks in projectbestanden op, in tegenstelling tot een afzonderlijk packages.config bestand. Het gebruik van PackageReference heeft geen invloed op andere aspecten van NuGet; Instellingen in NuGet.Config bestanden (inclusief pakketbronnen) worden bijvoorbeeld nog steeds toegepast, zoals wordt uitgelegd in algemene NuGet-configuraties.

Met PackageReference kunt u ook MSBuild-voorwaarden gebruiken om pakketverwijzingen per doelframework of andere groeperingen te kiezen. Het biedt ook nauwkeurige controle over afhankelijkheden en inhoudsstromen. (Zie voor meer informatie NuGet pack en herstel als MSBuild doelen.)

Ondersteuning voor projecttypen

PackageReference wordt standaard gebruikt voor .NET Core-projecten, .NET Standard-projecten en UWP-projecten die gericht zijn op Windows 10 Build 15063 (Creators Update) en hoger, met uitzondering van C++ UWP-projecten. .NET Framework-projecten ondersteunen PackageReference, maar zijn momenteel standaard ingesteld op packages.config. Als u PackageReference wilt gebruiken, migreert u de afhankelijkheden van packages.config naar het projectbestand en verwijdert u packages.config.

ASP.NET apps die gericht zijn op het volledige .NET Framework, bevatten alleen beperkte ondersteuning voor PackageReference. C++ en JavaScript-projecttypen worden niet ondersteund.

Een PackageReference toevoegen

Voeg een afhankelijkheid toe aan uw projectbestand met behulp van de volgende syntaxis:

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

Afhankelijkheidsversie beheren

De conventie voor het opgeven van de versie van een pakket is hetzelfde als bij het gebruik van packages.config:

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

In het bovenstaande voorbeeld betekent 3.6.0 elke versie die =3.6.0 is >met voorkeur voor de laagste versie, zoals beschreven in pakketversiebeheer.

PackageReference gebruiken voor een project zonder pakketafhankelijkheden

Geavanceerd: Als er geen pakketten zijn geïnstalleerd in een project (geen PackageReferences in projectbestand en geen packages.config bestand), maar het project moet worden hersteld als PackageReference-stijl, kunt u een Project-eigenschap RestoreProjectStyle instellen op PackageReference in uw projectbestand.

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

Dit kan handig zijn als u verwijst naar projecten met PackageReference styled (bestaande csproj- of SDK-stijlprojecten). Hierdoor kunnen pakketten waarnaar deze projecten verwijzen, 'transitief' worden verwezen door uw project.

PackageReference en bronnen

In PackageReference-projecten worden de transitieve afhankelijkheidsversies opgelost tijdens het herstellen. Als zodanig moeten in PackageReference-projecten alle bronnen beschikbaar zijn voor alle herstelbewerkingen.

Zwevende versies

Zwevende versies worden ondersteund met PackageReference:

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

Afhankelijkheidsassets beheren

Mogelijk gebruikt u een afhankelijkheid uitsluitend als ontwikkelingsharnas en wilt u deze mogelijk niet beschikbaar maken voor projecten die uw pakket gaan gebruiken. In dit scenario kunt u de PrivateAssets metagegevens gebruiken om dit gedrag te beheren.

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

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

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

Met de volgende metagegevenstags worden afhankelijkheidsassets beheerd:

Etiket Beschrijving Standaardwaarde
InclusiefMiddelen Deze assets worden verbruikt alle
ActivaUitsluiten Deze assets worden niet verbruikt Geen
PrivateAssets Deze assets worden verbruikt, maar worden niet overgedragen aan het bovenliggende project. inhoudsbestanden; Analyzers; bouwen

Toegestane waarden voor deze tags zijn als volgt, met meerdere waarden gescheiden door een puntkomma, behalve met all en none die door zichzelf moeten worden weergegeven:

Waarde Beschrijving
compileren Inhoud van de lib map en bepaalt of uw project kan worden gecompileerd op basis van de assembly's in de map
uitvoeringstijd Inhoud van de map lib en de map runtimes en bepaalt of deze assembly's naar de uitvoermap van de build worden gekopieerd
contentFiles Inhoud van de contentfiles map
bouwen .props en .targets in de build map
bouwMultiTargeting (4.0).props en .targets in de buildMultitargeting map voor cross-framework-targeting
buildTransitive (5,0+).props en .targets in de buildTransitive map, voor assets die transitief naar elk verbruikend project stromen. Zie de pagina met functies.
Analysatoren .NET Analyzers
inheems Inhoud van de native map
Geen Geen van de bovenstaande gegevens wordt gebruikt.
alle Alle bovenstaande (behalve 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>

Houd er rekening mee dat omdat build niet is opgenomen met PrivateAssets, doelen en props naar het bovenliggende project zullen doorstromen. Denk bijvoorbeeld aan het gebruik van de bovenstaande verwijzing in een project waarmee een NuGet-pakket met de naam AppLogger wordt gebouwd. AppLogger kan de doelen en props van Contoso.Utility.UsefulStuff gebruiken, net zoals projecten die AppLogger gebruiken.

Notitie

Wanneer developmentDependency op true wordt ingesteld in een .nuspec-bestand, markeert dit een pakket als een afhankelijkheid die uitsluitend voor ontwikkeling geldt, waardoor het pakket zal worden uitgesloten als afhankelijkheid in andere pakketten. Met PackageReference (NuGet 4.8+) betekent deze vlag ook dat compilatie-tijd-assets worden uitgesloten bij de compilatie. Zie DevelopmentDependency-ondersteuning voor PackageReference voor meer informatie.

Een PackageReference-voorwaarde toevoegen

U kunt een voorwaarde gebruiken om te bepalen of een pakket is opgenomen, waarbij voorwaarden elke MSBuild-variabele of een variabele kunnen gebruiken die is gedefinieerd in het doel- of props-bestand. Momenteel wordt echter alleen de TargetFramework variabele ondersteund.

Stel dat u zich zowel op netstandard1.4 als op net452 richt, maar dat u een afhankelijkheid hebt die alleen van toepassing is op net452. In dit geval wilt u niet dat een netstandard1.4 project dat uw pakket verbruikt, die onnodige afhankelijkheid toevoegt. U kunt dit voorkomen door als volgt een voorwaarde op PackageReference te geven:

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

Een pakket dat met dit project is gebouwd, laat zien dat Newtonsoft.Json alleen is opgenomen als een afhankelijkheid voor een net452 doel:

Het resultaat van het toepassen van een voorwaarde op PackageReference met VS2017

Voorwaarden kunnen ook op het ItemGroup-niveau worden toegepast en zijn van toepassing op alle onderliggende PackageReference-elementen.

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

GeneratePathProperty

Deze functie is beschikbaar met NuGet 5.0 of hoger en met Visual Studio 2019 16.0 of hoger.

Soms is het wenselijk om te verwijzen naar bestanden in een pakket van een MSBuild-doel. In packages.config op basisprojecten worden de pakketten geïnstalleerd in een map ten opzichte van het projectbestand. In PackageReference worden de pakketten echter gebruikt uit de map global-packages , die van machine tot machine kunnen verschillen.

Om deze kloof te overbruggen, heeft NuGet een eigenschap geïntroduceerd die verwijst naar de locatie van waaruit het pakket wordt verbruikt.

Voorbeeld:

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

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

Daarnaast genereert NuGet automatisch eigenschappen voor pakketten die een map hulpprogramma's bevatten.

  <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-eigenschappen en pakketidentiteiten hebben niet dezelfde beperkingen, dus de pakketidentiteit moet worden gewijzigd in een beschrijvende MSBuild-naam, voorafgegaan door het woord Pkg. Als u de exacte naam van de gegenereerde eigenschap wilt controleren, bekijkt u het gegenereerde nuget.g.props-bestand .

PackageReference-aliassen

In sommige zeldzame gevallen bevatten verschillende pakketten klassen in dezelfde naamruimte. Vanaf NuGet 5.7 en Visual Studio 2019 Update 7 ondersteunt PackageReference Aliases, vergelijkbaar met ProjectReference. Standaard worden er geen aliassen opgegeven. Wanneer een alias is opgegeven, moeten alle assembly's die afkomstig zijn van het geannoteerde pakket, worden verwezen met een alias.

U kunt het voorbeeldgebruik bekijken op NuGet\Samples

Geef in het projectbestand de aliassen als volgt op:

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

en in de code wordt deze als volgt gebruikt:

extern alias ExampleAlias;

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

NuGet-waarschuwingen en -fouten

Deze functie is beschikbaar met NuGet 4.3 of hoger en met Visual Studio 2017 15.3 of hoger.

Voor veel scenario's voor inpakken en herstellen worden alle NuGet-waarschuwingen en -fouten gecodeerd en beginnen met NU****. Alle NuGet-waarschuwingen en -fouten worden vermeld in de referentiedocumentatie .

NuGet bekijkt de volgende waarschuwingseigenschappen:

  • TreatWarningsAsErrors, alle waarschuwingen behandelen als fouten
  • WarningsAsErrors, specifieke waarschuwingen behandelen als fouten
  • NoWarn, specifieke waarschuwingen verbergen voor het hele project of voor het hele pakket.

Voorbeelden:

<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>

NuGet-waarschuwingen onderdrukken

Hoewel het wordt aanbevolen om alle NuGet-waarschuwingen tijdens uw pack- en herstelbewerkingen op te lossen, is het in bepaalde situaties gerechtvaardigd om ze te onderdrukken. Als u een waarschuwingsproject breed wilt onderdrukken, kunt u het volgende doen:

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

Soms zijn waarschuwingen alleen van toepassing op een bepaald pakket in de grafiek. We kunnen ervoor kiezen om deze waarschuwing selectiever te onderdrukken door een NoWarn toe te voegen aan het PackageReference-item.

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

NuGet-pakketwaarschuwingen onderdrukken in Visual Studio

In Visual Studio kunt u ook waarschuwingen onderdrukken via de IDE.

Afhankelijkheden vergrendelen

Deze functie is beschikbaar met NuGet 4.9 of hoger en met Visual Studio 2017 15.9 of hoger.

Invoer voor NuGet-herstel is een set PackageReference items uit het projectbestand (afhankelijkheden op het hoogste niveau of directe afhankelijkheden) en de uitvoer is een volledige sluiting van alle pakketafhankelijkheden, inclusief transitieve afhankelijkheden. NuGet probeert altijd dezelfde volledige sluiting van pakketafhankelijkheden te produceren als de invoerlijst PackageReference niet is gewijzigd. Er zijn echter enkele scenario's waarin dit niet mogelijk is. Voorbeeld:

  • Wanneer u zwevende versies gebruikt, zoals <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Hoewel het hier de bedoeling is om bij elk herstel van pakketten naar de nieuwste versie over te schakelen, zijn er scenario's waarin gebruikers vereisen dat de grafiek wordt vergrendeld op een specifieke nieuwste versie en overschakelt naar een latere versie, indien beschikbaar, als een expliciete actie wordt uitgevoerd.

  • Er wordt een nieuwere versie van het pakket dat overeenkomt met de versievereisten voor PackageReference gepubliceerd. Bijvoorbeeld

    • Dag 1: als u hebt opgegeven <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> , maar de versies die beschikbaar zijn op de NuGet-opslagplaatsen, waren 4.1.0, 4.2.0 en 4.3.0. In dit geval zou NuGet hebben gekozen voor 4.1.0 (dichtstbijzijnde minimale versie)

    • Dag 2: Versie 4.0.0 wordt gepubliceerd. NuGet vindt nu de exacte overeenkomst en begint te werken met 4.0.0

  • Een bepaalde pakketversie wordt verwijderd uit de opslagplaats. Hoewel nuget.org geen pakketverwijderingen toestaat, hebben niet alle pakketopslagplaatsen deze beperking. Dit zorgt ervoor dat NuGet de beste overeenkomst vindt wanneer het niet kan worden teruggebracht naar de verwijderde versie.

Het lock-bestand inschakelen

Als u de volledige sluiting van pakketafhankelijkheden wilt behouden, kunt u zich aanmelden voor de vergrendelingsbestandsfunctie door de MSBuild-eigenschap RestorePackagesWithLockFile voor uw project in te stellen:

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

Als deze eigenschap is ingesteld, genereert NuGet-herstel een vergrendelingsbestand - packages.lock.json bestand in de hoofdmap van het project waarin alle pakketafhankelijkheden worden vermeld.

Notitie

Zodra een project het bestand packages.lock.json in zijn hoofdmap heeft, wordt het vergrendelingsbestand altijd voor het herstellen gebruikt, zelfs als de eigenschap RestorePackagesWithLockFile niet is ingesteld. U kunt zich dus ook aanmelden voor deze functie door een leeg packages.lock.json dummybestand te maken in de hoofdmap van het project.

restore gedrag met vergrendelbestand

Als er een vergrendelingsbestand aanwezig is voor project, gebruikt NuGet dit vergrendelingsbestand om uit te voeren restore. NuGet controleert snel of er wijzigingen zijn aangebracht in de pakketafhankelijkheden zoals vermeld in het projectbestand (of de bestanden van afhankelijke projecten) en als er geen wijzigingen zijn aangebracht, worden alleen de pakketten die in het vergrendelingsbestand worden genoemd, hersteld. Er is geen herevaluatie van pakketafhankelijkheden.

Als NuGet een wijziging detecteert in de gedefinieerde afhankelijkheden zoals vermeld in de projectbestanden, evalueert het de pakketgrafiek opnieuw en wordt het vergrendelingsbestand bijgewerkt om de nieuwe pakketsluiting voor het project weer te geven.

Voor CI/CD en andere scenario's, waarbij u de pakketafhankelijkheden niet direct wilt wijzigen, kunt u dit doen door het lockedmode volgende in te truestellen:

Voer voor dotnet.exehet volgende uit:

> dotnet.exe restore --locked-mode

Voer voor msbuild.exehet volgende uit:

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

U kunt deze voorwaardelijke MSBuild-eigenschap ook instellen in uw projectbestand:

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

Als de vergrendelingsmodus true is, zal het herstel ofwel de exacte pakketten herstellen zoals vermeld in het lockbestand, of mislukken als u de gedefinieerde pakketafhankelijkheden voor het project hebt bijgewerkt nadat het lockbestand was gecreëerd.

Maak het vergrendelingsbestand onderdeel van uw bronrepo.

Als u een toepassing bouwt, bevindt een uitvoerbaar bestand en het betreffende project zich aan het begin van de afhankelijkheidsketen, controleert u het vergrendelingsbestand in de opslagplaats met broncode, zodat NuGet er tijdens het herstellen gebruik van kan maken.

Als uw project echter een bibliotheekproject is dat u niet verzendt of een algemeen codeproject waarvan andere projecten afhankelijk zijn, moet u het vergrendelingsbestand niet inchecken als onderdeel van uw broncode. Er is geen kwaad om het vergrendelingsbestand te behouden, maar de afhankelijkheden van het vergrendelde pakket voor het algemene codeproject worden mogelijk niet gebruikt, zoals vermeld in het vergrendelingsbestand, tijdens het herstellen/bouwen van een project dat afhankelijk is van dit algemene codeproject.

Bijvoorbeeld

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

Als ProjectA een afhankelijkheid heeft van een PackageX versie 2.0.0 en ook verwijst naar ProjectB dat afhankelijk is van PackageX versie 1.0.0, dan wordt in het vergrendelingsbestand voor ProjectB een afhankelijkheid van PackageX versie 1.0.0 vermeld. Echter, wanneer het vergrendelingsbestand van ProjectA is gebouwd, bevat het een afhankelijkheid van PackageX versie 2.0.0 en niet1.0.0 zoals vermeld in het vergrendelingsbestand voor ProjectB. Het vergrendelingsbestand van een gemeenschappelijk codeproject heeft dus weinig te zeggen over de pakketten die zijn opgelost voor projecten die ervan afhankelijk zijn.

Uitbreidbaarheid van vergrendelingsbestanden

U kunt verschillende gedragingen van herstel beheren met een vergrendelingsbestand, zoals hieronder wordt beschreven:

NuGet.exe optie dotnet-optie Equivalente MSBuild-optie Beschrijving
-UseLockFile --use-lock-file RestorePackagesWithLockFile Hiermee kiest u voor het gebruik van een lock-bestand.
-LockedMode --locked-mode RestoreLockedMode Hiermee schakelt u de vergrendelde modus in voor herstel. Dit is handig in CI/CD-scenario's waarin u herhaalbare builds wilt.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Deze optie is handig voor pakketten met zwevende versie die in het project is gedefinieerd. Standaard werkt NuGet-herstel de pakketversie niet automatisch bij bij elke herstelbewerking, tenzij u herstel uitvoert met deze optie.
-LockFilePath --lock-file-path NuGetLockFilePath Hiermee definieert u een aangepaste vergrendelingsbestandslocatie voor een project. NuGet ondersteunt packages.lock.json standaard in de hoofdmap. Als u meerdere projecten in dezelfde map hebt, ondersteunt NuGet projectspecifiek vergrendelingsbestand packages.<project_name>.lock.json

NuGet Afhankelijkheidsoplosser

De NuGet-afhankelijkheidsomzettingsoplossing volgt de vier regels, zoals beschreven in het document voor afhankelijkheidsoplossing.

Om de prestaties en schaalbaarheid van de herstelbewerking te verbeteren, is het herstelalgoritmen opnieuw geschreven in de versie 6.12. Vanaf de release 6.12 is het nieuwe herstelalgoritmen standaard ingeschakeld voor alle PackageReference-projecten. Hoewel het nieuwe herstelalgoritmen functioneel gelijk zijn aan de vorige, zoals bij elke software, zijn er fouten mogelijk. Als u wilt terugkeren naar de vorige implementatie, stelt u de eigenschap RestoreUseLegacyDependencyResolver MSBuild in op true.

Als u te maken hebt met herstelfouten in 6.12, .NET 9 of 17.12, die niet werden gereproduceerde in eerdere versies, kunt u een probleem indienen op GitHub. Eventuele verschillen tussen de oude en nieuwe algoritmen kunnen verschillende gevolgen hebben, zoals tijdens de compilatie of tijdens runtime. Er is ook een kans dat wijzigingen niet leiden tot fouten, maar dat verschillende pakketversies worden hersteld. Als u denkt dat eventuele wijzigingen u mogelijk treffen, volgt u deze stappen om te verifiëren of de wijzigingen in het NuGet-herstelalgoritme de oorzaak zijn.

Herstel schrijft de resultaten in de MSBuildProjectExtensionsPath map, die kan worden vergeleken met de nieuwe en oude algoritmen om verschillen te vinden. Meestal is dit de obj map van uw build. U kunt msbuild.exe of dotnet.exe gebruiken voor de volgende stappen.

  1. Verwijder de obj map voor uw project.
  2. Voer msbuild -t:restore uit
  3. Sla de inhoud van de obj op naar een locatie die aangeeft dat het gedrag new is.
  4. Voer msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true" uit
  5. Sla de inhoud van de obj locatie op die aangeeft dat het het legacy gedrag is.
  6. Vergelijk de bestanden in de twee mappen, met name project.assets.json. Hulpprogramma's die verschillen kunnen markeren, zijn vooral handig voor dit (bijvoorbeeld Visual Studio Code, beide bestanden openen en met de rechtermuisknop klikken op 'selecteren voor vergelijken' en 'vergelijken met geselecteerd')

Als u de bovenstaande methode volgt, moet er precies 1 verschil zijn tussen de project.assets.json bestanden:

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

Als er meer verschillen zijn, kunt u een probleem indienen op GitHub met alle details.

AssetTargetFallback

Met de AssetTargetFallback eigenschap kunt u aanvullende compatibele frameworkversies opgeven voor projecten waarnaar uw project verwijst en NuGet-pakketten die door uw project worden gebruikt.

Als u een pakketafhankelijkheid opgeeft met PackageReference en dat pakket geen assets bevat die compatibel zijn met het doelframework van uw projecten, wordt de AssetTargetFallback eigenschap van belang. De compatibiliteit van het pakket waarnaar wordt verwezen, wordt opnieuw gecontroleerd met elk doelframework dat is opgegeven in AssetTargetFallback. Wanneer er via AssetTargetFallback naar een project of een package wordt verwezen, wordt de NU1701-waarschuwing gegenereerd.

Raadpleeg de onderstaande tabel voor voorbeelden van hoe AssetTargetFallback dit van invloed is op de compatibiliteit.

Project framework AssetTargetFallback Pakketframeworks Resultaat
.NET Framework 4.7.2 .NET Standard 2.0 .NET Standard 2.0
.NET Core-app 3.1 .NET Standard 2.0, .NET Framework 4.7.2 .NET Standard 2.0
.NET Core-app 3.1 .NET Framework 4.7.2 Incompatibel, mislukt met NU1202
.NET Core-app 3.1 net472; net471 .NET Framework 4.7.2 .NET Framework 4.7.2 met NU1701

Meerdere frameworks kunnen worden opgegeven met ; als scheidingsteken. Als u een terugvalframework wilt toevoegen, kunt u het volgende doen:

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

U kunt $(AssetTargetFallback) weglaten als u wilt overschrijven in plaats van de bestaande AssetTargetFallback waarden toe te voegen.

Notitie

Als u een op .NET SDK gebaseerd project gebruikt, worden de juiste $(AssetTargetFallback) waarden geconfigureerd en hoeft u ze niet handmatig in te stellen.

$(PackageTargetFallback) was een eerdere functie die deze uitdaging probeerde aan te pakken, maar het is fundamenteel verbroken en mag niet worden gebruikt. Als u wilt migreren van $(PackageTargetFallback) naar $(AssetTargetFallback), wijzigt u gewoon de naam van de eigenschap.

PrunePackageReference

De .NET Runtime ontwikkelt zich voortdurend, met prestatieverbeteringen en nieuwe API's elke release. Er is veel functionaliteit beschikbaar in de runtime, maar ook als pakketten, zoals System.Text.Json. Dit kan vaak leiden tot een System.Text.Json 8.0.0 in een project gericht op .NET 9 of .NET 8. Deze afhankelijkheid is niet nodig en de oplossing voor buildconflicten zou de assembly die afkomstig is uit het pakket niet gebruiken, aangezien deze al beschikbaar is in de .NET Runtime. Vanaf NuGet versie 6.13 en .NET SDK 9.0.200 PrunePackageReference kunt u deze pakketten bijsnijden tijdens het herstellen voor op .NET SDK gebaseerde projecten.

Pakketsnoei is beschikbaar als opt-in-functie met de .NET 9 SDK en wordt standaard ingeschakeld voor alle .NET frameworks en >= .NET Standard 2.0 te beginnen met .NET 10 SDK.

Pakketsnoeien is alleen beschikbaar met de standaard afhankelijkheidsoplosser, zoals uitgebracht in 6.12.

PrunePackageReference-specificatie

De lijst met pakketten die moeten worden verwijderd, wordt gedefinieerd met het PrunePackageReference item.

Kenmerken Beschrijving
Versie Hiermee geeft u de maximale versie die moet worden verwijderd. 1.0.0 betekent dat alle pakketten tot en met 1.0.0 worden verwijderd. Voor 1.0.0, 0.9.0 en 1.0.0 zullen gesnoeid worden, maar 1.0.1 zal dat niet.

De volgende eigenschappen kunnen worden gebruikt om het snoeigedrag te wijzigen.

Eigenschapsnaam Beschrijving
HerstelInschakelenPakketSnoeien Hiermee schakelt u het verwijderen van pakketten in voor de pakketten die zijn opgegeven met PrunePackageReference. Deze eigenschap is per doelframework en de geldige waarden zijn true en false. De standaardinstellingen kunnen verschillen op basis van de .NET SDK zoals hierboven is gedefinieerd.

De .NET SDK definieert de lijst met pakketten die voor u moeten worden verwijderd.

Hoe PrunePackageReference werkt

Wanneer een pakket wordt opgegeven om te worden verwijderd tijdens het herstellen, wordt het verwijderd uit de afhankelijkheidsgrafiek. Dit pakket wordt niet gedownload en wordt niet weergegeven in een van de uitvoer van NuGet. Wanneer een pakket wordt verwijderd, is er een gedetailleerd uitgebreid bericht dat aangeeft dat het pakket is verwijderd voor het opgegeven doelframework.

Het snoeien wordt alleen ondersteund voor transitieve pakketten, wat betekent dat er naar pakketten wordt verwezen door andere pakketten of projecten. In de volgende tabel ziet u verschillende gedrag bij het verwijderen van pakketten.

Verwijdering van afhankelijkheden Gedrag
Komt overeen met de id van een transitief pakket dat via een ander pakket komt Snoeien
Komt overeen met de id van een transitief pakket dat via een ander project komt Snoeien
Komt overeen met de ID van een directe PackageReference De NU1510-waarschuwing verhogen en niet snoeien
Komt overeen met de id van een ProjectReference De NU1511-waarschuwing verhogen en niet snoeien

PrunePackageReference-toepassingen

De voordelen van pakketsnoeien zijn tweevoudig:

  • Prestatievoordelen, door het aantal pakketten in een afhankelijkheidsgrafiek te verminderen
  • Reductie van fout-positieven door componentenscanners zoals NuGetAudit

Het snoeien is met name waardevol wanneer controlepakketten zijn NuGetAuditMode ingesteld op all. Als u .NET 9 gebruikt, raden we u aan om te snoeien door in te stellen RestoreEnablePackagePruning op true.