Dela via

PackageReference i projektfiler

Paketreferenser, med hjälp av <PackageReference> MSBuild-objekt, anger NuGet-paketberoenden direkt i projektfiler, i stället för att ha en separat packages.config fil. Användning av PackageReference påverkar inte andra aspekter av NuGet. Till exempel tillämpas inställningar i NuGet.Config filer (inklusive paketkällor) fortfarande enligt beskrivningen i Vanliga NuGet-konfigurationer.

Med PackageReference kan du också använda MSBuild-villkor för att välja paketreferenser per målramverk eller andra grupperingar. Det ger också detaljerad kontroll över beroenden och innehållsflöde. (Mer information finns i NuGet-paketet och återställa som MSBuild-mål.)

Stöd för projekttyp

Som standard används PackageReference för .NET-projekt, .NET Standard-projekt och UWP-projekt för Windows 10 Build 15063 (Creators Update) och senare, med undantag för C++ UWP-projekt. .NET Framework-projekt stöder PackageReference, men för närvarande är standardvärdet packages.config. Om du vill använda PackageReference i ett .NET Framework-projekt migrerar du beroendena från packages.config till projektfilen och tar sedan bort packages.config.

ASP.NET appar som riktar sig till hela .NET Framework innehåller endast begränsat stöd för PackageReference. C++ och JavaScript-projekttyper stöds inte.

Lägga till en PackageReference

Lägg till ett beroende i projektfilen med hjälp av följande syntax:

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

Kontrollera beroendeversion

Konventionen för att ange versionen av ett paket är densamma som när du använder packages.config:

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

I exemplet ovan innebär 3.6.0 alla versioner som är >=3.6.0 med inställningar för den lägsta versionen, enligt beskrivningen i Paketversionshantering.

Använda PackageReference för ett projekt utan paketberoenden

Avancerat: Om du inte har några paket installerade i ett projekt (inga PackageReferences i projektfilen och ingen packages.config fil), men vill att projektet ska återställas som PackageReference-format, kan du ange en Project-egenskap RestoreProjectStyle till PackageReference i projektfilen.

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

Detta kan vara användbart om du refererar till projekt som är PackageReference-formaterade (befintliga csproj- eller SDK-projekt). Detta gör det möjligt för paket som dessa projekt refererar till att 'transitivt' refereras av ditt projekt.

PackageReference och källor

I PackageReference-projekt löses de transitiva beroendeversionerna vid återställningstillfället. Därför måste alla källor vara tillgängliga för alla återställningar i PackageReference-projekt.

Flytande versioner

Flytande versioner stöds med PackageReference:

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

Kontrollera beroendetillgångar

Du kanske använder ett beroende enbart som ett utvecklingsverktyg och inte vill exponera det för projekt som kommer att använda ditt paket. I det här scenariot kan du använda PrivateAssets metadata för att styra det här beteendet.

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

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

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

Följande metadatataggar styr beroendetillgångar:

Tag Description Standardvärde
IncludeAssets Dessa tillgångar kommer att förbrukas all
ExcludeAssets Dessa tillgångar kommer inte att förbrukas none
PrivateAssets Dessa tillgångar förbrukas men flödar inte till det överordnade projektet contentfiles;analyzers;build

Tillåtna värden för dessa taggar är följande, med flera värden avgränsade med ett semikolon förutom all och none, som måste visas på egen hand:

Value Description
compile Innehållet i lib mappen och styr om projektet kan kompileras mot sammansättningarna i mappen
runtime Innehållet i lib mappen och runtimes styr om dessa sammansättningar ska kopieras ut till utdatakatalogen för bygget
contentFiles Innehållet i contentfiles mappen
build .props och .targets i build mappen
buildMultitargeting (4.0).props och .targets i buildMultitargeting mappen för mål för flera ramverk
buildTransitive (5.0+).props och .targets i buildTransitive mappen för tillgångar som flödar transitivt till alla förbrukande projekt. Se funktionssidan .
analyzers .NET-analysverktyg
native Innehållet i native mappen
none Inget av ovanstående används.
all Alla ovanstående (utom 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>

Observera att eftersom build inte ingår i PrivateAssetskommer mål och rekvisita att flöda till det överordnade projektet. Tänk till exempel på att referensen ovan används i ett projekt som skapar ett NuGet-paket med namnet AppLogger. AppLogger kan använda mål och egenskaper från Contoso.Utility.UsefulStuff, liksom projekt som använder AppLogger.

Note

När developmentDependency är inställt på true i en .nuspec fil markerar detta ett paket som ett utvecklingsberoende, vilket förhindrar att paketet inkluderas som ett beroende i andra paket. Med PackageReference (NuGet 4.8+) innebär den här flaggan också att den undantar kompileringstidstillgångar från kompilering. Mer information finns i Support för DevelopmentDependency för PackageReference.

Lägga till ett PackageReference-villkor

Du kan använda ett villkor för att styra om ett paket ingår. Villkor kan använda valfri MSBuild-variabel eller en variabel som definierats i mål- eller props-filen. För närvarande stöds dock endast variabeln TargetFramework .

Anta till exempel att du riktar in netstandard1.4 dig på och net452 men har ett beroende som endast gäller för net452. I det här fallet vill du inte att ett netstandard1.4 projekt som använder paketet ska lägga till det onödiga beroendet. För att förhindra detta anger du ett villkor på följande PackageReference sätt:

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

Ett paket som skapats med det här projektet visar att Newtonsoft.Json endast ingår som ett beroende för ett net452 mål:

Resultatet av att tillämpa ett villkor på PackageReference med VS2017

Villkor kan också tillämpas på ItemGroup-nivån och gäller för alla underordnade PackageReference-element:

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

GeneratePathProperty

Den här funktionen är tillgänglig med NuGet 5.0 eller senare och med Visual Studio 2019 16.0 eller senare.

Ibland är det önskvärt att referera till filer i ett paket från ett MSBuild-mål. I packages.config baserade projekt installeras paketen i en mapp i förhållande till projektfilen. Men i PackageReference används paketen från mappen global-packages , som kan variera från dator till dator.

För att överbrygga det gapet introducerade NuGet en egenskap som pekar på den plats som paketet ska förbrukas från.

Example:

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

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

Dessutom genererar NuGet automatiskt egenskaper för paket som innehåller en verktygsmapp.

  <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-egenskaper och paketidentiteter har inte samma begränsningar, så paketidentiteten måste ändras till ett eget MSBuild-namn, prefixet med ordet Pkg. Om du vill verifiera det exakta namnet på den genererade egenskapen tittar du på den genererade nuget.g.props-filen .

PackageReference-alias

I vissa sällsynta fall innehåller olika paket klasser i samma namnområde. Från och med NuGet 5.7 och Visual Studio 2019 Update 7 stöder PackageReference, motsvarande ProjectReference, Aliases. Som standard tillhandahålls inga alias. När ett alias har angetts måste alla sammansättningar som kommer från det kommenterade paketet refereras till med ett alias.

Du kan titta på exempelanvändningen i NuGet\Samples.

I projektfilen anger du aliasen enligt följande:

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

Och i koden använder du den på följande sätt:

extern alias ExampleAlias;

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

NuGet-varningar och -fel

Den här funktionen är tillgänglig med NuGet 4.3 eller senare och med Visual Studio 2017 15.3 eller senare.

För många paket- och återställningsscenarier kodas alla NuGet-varningar och -fel och börjar med NU****. Alla NuGet-varningar och -fel visas i referensdokumentationen .

NuGet observerar följande varningsegenskaper:

  • TreatWarningsAsErrors, behandla alla varningar som fel.
  • WarningsAsErrors, behandla specifika varningar som fel.
  • NoWarn, dölj specifika varningar, antingen projektomfattande eller paketomfattande.

Examples:

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

Ignorera NuGet-varningar

Vi rekommenderar att du löser alla NuGet-varningar under paket- och återställningsåtgärderna, men i vissa situationer är det motiverat att förhindra dem. Överväg att göra följande för att förhindra ett varningsprojekt i stort:

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

Ibland gäller varningar endast för ett visst paket i diagrammet. Du kan välja att ignorera den varningen mer selektivt genom att lägga till en NoWarn på PackageReference-objektet.

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

Ignorera NuGet-paketvarningar i Visual Studio

När du är i Visual Studio kan du också ignorera varningar via IDE.

Låsa beroenden

Den här funktionen är tillgänglig med NuGet 4.9 eller senare och med Visual Studio 2017 15.9 eller senare.

Indata till NuGet-återställning är en uppsättning PackageReference objekt från projektfilen (högsta eller direkta beroenden) och utdata är en fullständig stängning av alla paketberoenden, inklusive transitiva beroenden. NuGet försöker alltid skapa samma fullständiga stängning av paketberoenden om indatalistan PackageReference inte har ändrats. Det finns dock vissa scenarier där det inte går att göra det. Till exempel:

  • När du använder flytande versioner som <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Avsikten här är att flytta till den senaste versionen för varje återställning av paket, men det finns scenarier där användarna kräver att grafen låses till en viss senaste version och flyter till en senare version, om den är tillgänglig, på en explicit gest.

  • En nyare version av paketet som uppfyller versionkraven för PackageReference har publicerats. Till exempel:

    • Dag 1: om du angav <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> men de versioner som är tillgängliga på NuGet-lagringsplatserna var 4.1.0, 4.2.0 och 4.3.0. I det här fallet skulle NuGet ha matchat till 4.1.0 (närmaste lägsta version).

    • Dag 2: Version 4.0.0 publiceras. NuGet hittar nu den exakta matchningen och börjar matcha till 4.0.0.

  • En viss paketversion tas bort från lagringsplatsen. Även om nuget.org inte tillåter paketborttagning har inte alla paketlagringsplatser den här begränsningen. Detta resulterar i att NuGet hittar den bästa matchningen när den inte kan matcha den borttagna versionen.

Aktivera låsfilen

För att bevara den fullständiga stängningen av paketberoenden kan du välja att använda funktionen låsfil genom att ange egenskapen RestorePackagesWithLockFile MSBuild för projektet:

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

Om den här egenskapen har angetts genererar NuGet-återställning en låsfil (packages.lock.json) i projektrotkatalogen som visar alla paketberoenden.

Note

När ett projekt har packages.lock.json en fil i rotkatalogen används låsfilen alltid med återställning även om egenskapen RestorePackagesWithLockFile inte har angetts. Ett annat sätt att välja den här funktionen är därför att skapa en tom packages.lock.json dummyfil i projektets rotkatalog.

restore beteende med låsfil

Om det finns en låsfil för ett projekt använder NuGet den här låsfilen för att köra restore. NuGet gör en snabbkontroll för att se om det fanns några ändringar i paketberoendena som nämns i projektfilen (eller beroende projektfiler), och om det inte fanns några ändringar återställs bara paketen som nämns i låsfilen. Det finns ingen omvärdering av paketberoenden.

Om NuGet identifierar en ändring i de definierade beroendena enligt beskrivningen i projektfilerna utvärderas paketdiagrammet igen och låsfilen uppdateras så att den återspeglar den nya paketstängningen för projektet.

För CI/CD och andra scenarier, där du inte vill ändra paketberoenden i farten, kan du göra det genom att ange lockedmode till true:

Utför för dotnet.exe:

> dotnet.exe restore --locked-mode

För msbuild.exe, kör:

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

Du kan också ange den här villkorliga MSBuild-egenskapen i projektfilen:

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

Om låst läge är trueåterställer återställningen antingen de exakta paketen enligt listan i låsfilen eller misslyckas om du uppdaterade de definierade paketberoendena för projektet efter att låsfilen har skapats.

Lås filer och PrunePackageReference

PrunePackageReference ändrar beroendena för ett projekt genom att ta bort onödiga transitiva paket. När du tar bort dessa paket bör det inte påverka körningen, men det påverkar låsfilerna. Om du aktiverar beskärning för ett befintligt projekt kan det leda till färre paket än innan du rensar när låsfilen återskapas. Den uppdaterade kontrollen av låsfilen som aktiverar låst läge är beskärningsmedveten, vilket innebär att om du har aktiverat beskärning i ett projekt, kommer kontrollen att ta hänsyn till paket som beskärs. Nästa gång låsfilen återskapas undantas dock de beskärda paketen, så du kan se en diff som är större än vanligt.

Gör låsfil till en del av källlagringsplatsen

Om du skapar ett program, en körbar fil och projektet i fråga är i början av beroendekedjan, kontrollerar du låsfilen till källkodslagringsplatsen så att NuGet kan använda den under återställningen.

Men om projektet är ett biblioteksprojekt som du inte skickar eller ett vanligt kodprojekt som andra projekt är beroende av , bör du inte checka in låsfilen som en del av källkoden. Det är ingen skada att behålla låsfilen, men de låsta paketberoendena för det vanliga kodprojektet kan inte användas, som anges i låsfilen, under återställningen/bygget av ett projekt som är beroende av det här common code-projektet.

Example:

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

Om ProjectA har ett beroende av en PackageX version 2.0.0 och även refererar till ProjectB som är beroende av PackageX version 1.0.0, kommer låsningsfilen för ProjectB att visa ett beroende av PackageX version 1.0.0. När ProjectA skapas innehåller låsfilen dock ett beroende av PackageX version 2.0.0 och inte1.0.0 som anges i låsfilen för ProjectB. Låsfilen för ett vanligt kodprojekt har alltså lite att säga till om för de paket som har lösts för projekt som är beroende av det.

Lås utökningsbarhet för filer

Du kan styra olika funktioner för återställning med låsfil enligt beskrivningen nedan:

NuGet.exe alternativ dotnet-alternativ Alternativ motsvarande MSBuild Description
-UseLockFile --use-lock-file RestorePackagesWithLockFile Väljer att använda en låsfil.
-LockedMode --locked-mode RestoreLockedMode Aktiverar låst läge för återställning. Detta är användbart i CI/CD-scenarier där du vill ha repeterbara versioner.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Det här alternativet är användbart med paket med flytande version definierad i projektet. Som standard uppdaterar Inte NuGet-återställning paketversionen automatiskt vid varje återställning om du inte kör återställningen med det här alternativet.
-LockFilePath --lock-file-path NuGetLockFilePath Definierar en anpassad låsfilplats för ett projekt. Som standard stöder NuGet packages.lock.json i rotkatalogen. Om du har flera projekt i samma katalog stöder NuGet projektspecifik låsfil packages.<project_name>.lock.json

NuGet-beroendelösare

NuGet-beroendematcharen följer de fyra reglerna enligt beskrivningen i dokumentet om beroendematchning.

För att förbättra prestanda och skalbarhet för återställningsåtgärden skrevs återställningsalgoritmen om i 6.12-versionen. Från och med 6.12-versionen är den nya återställningsalgoritmen aktiverad som standard för alla PackageReference-projekt. Även om den nya återställningsalgoritmen är funktionellt likvärdig med den tidigare, som med alla program, är buggar möjliga. Om du vill återgå till den tidigare implementeringen anger du egenskapen RestoreUseLegacyDependencyResolver MSBuild till true.

Om du stöter på återställningsfel i 6.12, .NET 9 eller 17.12, som inte återskapas i tidigare versioner, kan du skapa ett problem på GitHub. Eventuella skillnader mellan de gamla och nya algoritmerna kan ha olika effekter, till exempel under kompilering eller vid körning. Det finns också en risk att ändringar inte leder till fel, utan att olika paketversioner återställs. Om du tror att du kan påverkas av ändringar kan du göra följande för att kontrollera om ändringarna i NuGet-återställningsalgoritmen är rotorsaken.

Restore skriver sina resultat i MSBuildProjectExtensionsPath katalogen, vilket kan jämföras med nya och gamla algoritmer för att hitta skillnader. Vanligtvis är detta obj-mappen för ditt build. Du kan använda msbuild.exe eller dotnet.exe för nästa steg.

  1. obj Ta bort mappen för projektet.

  2. Kör msbuild -t:restore

  3. Spara innehållet i obj till en plats som visar att det är new-beteendet.

  4. Kör msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true".

  5. Spara innehållet i obj till en plats som visar att det är legacy-beteendet.

  6. Jämför filerna i de två katalogerna, särskilt project.assets.json.

    Verktyg som kan markera skillnader är särskilt användbara för detta (till exempel i Visual Studio Code öppnar du båda filerna och använder högerklicka på "välj för jämförelse" och "jämför med valt").

Om du följer metoden ovan bör det finnas exakt 1 skillnad mellan project.assets.json filerna:

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

Om det finns fler skillnader kan du ange ett problem på GitHub med all information.

AssetTargetFallback

Med AssetTargetFallback egenskapen kan du ange ytterligare kompatibla ramverksversioner för projekt som ditt projekt refererar till och NuGet-paket som ditt projekt använder.

Om du anger ett paketberoende som använder PackageReference men paketet inte innehåller tillgångar som är kompatibla med dina projekts målramverk, AssetTargetFallback spelar egenskapen in. Kompatibiliteten för det refererade paketet kontrolleras igen med varje målplattform som anges i AssetTargetFallback. När en project eller en package refereras via AssetTargetFallbackgenereras NU1701-varningen .

Se tabellen nedan för exempel på hur AssetTargetFallback påverkar kompatibiliteten.

Projektramverk AssetTargetFallback Paketramverk Result
.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 Inkompatibel, misslyckas med NU1202
.NET Core App 3.1 net472;net471 .NET Framework 4.7.2 .NET Framework 4.7.2 med NU1701

Flera ramverk kan anges med ; som avgränsare. Om du vill lägga till ett reservramverk kan du göra följande:

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

Du kan låta bli $(AssetTargetFallback) om du vill skriva över i stället för att lägga till befintliga AssetTargetFallback värden.

Note

Om du använder ett .NET SDK-baserat projekt konfigureras lämpliga $(AssetTargetFallback) värden och du behöver inte ange dem manuellt.

$(PackageTargetFallback) var en tidigare funktion som försökte hantera den här utmaningen, men den är i grunden bruten och bör inte användas. Om du vill migrera från $(PackageTargetFallback) till $(AssetTargetFallback)ändrar du bara egenskapsnamnet.

PrunePackageReference

.NET Runtime utvecklas ständigt, med prestandaförbättringar och nya API:er varje version. Nya funktioner som läggs till i .NET tillhandahålls ibland också som paket, så att utvecklare som använder äldre målramverk kan använda biblioteket, till exempel System.Text.Json. Detta kan ofta leda till en System.Text.Json 8.0.0 i ett projekt som riktar sig till .NET 9 eller .NET 8. Det här beroendet är onödigt och lösningen på byggkonflikten skulle inte använda sammansättningen som kommer från paketet eftersom den redan är tillgänglig i .NET Runtime. Från och med NuGet version 6.13 och .NET SDK 9.0.200, PrunePackageReference möjliggör beskärning av dessa paket vid återställningstid för .NET SDK-baserade projekt. Den första iterationen av rensningen påverkade endast transitiva paket, men från och med .NET SDK 10 påverkar paketrensning även direktpaket.

Paketrensning är tillgänglig som en opt-in-funktion med .NET 9 SDK och är aktiverad som standard för alla ramverk i ett projekt som är mål >= .NET 10.0 för .NET 10 SDK.

Paketrensning är endast tillgängligt med standardberoendelösaren som släpptes i version 6.12.

PrunePackageReference-specifikation

Listan över paket som ska beskäras definieras med PrunePackageReference objektet.

Attributes Description
Version Anger den maximala version som ska beskäras. 1.0.0 innebär att alla paket upp till och med 1.0.0 kommer att beskäras. För 1.0.0, 0.9.0 och 1.0.0 kommer att beskäras, men 1.0.1 kommer inte att.

Följande egenskaper kan användas för att ändra beskärningsbeteendet.

PropertyName Description
RestoreEnablePackagePruning Aktiverar paketrensning för de paket som anges med PrunePackageReference. Den här egenskapen är per målramverk och giltiga värden är true och false. Standardvärdena kan variera beroende på .NET SDK enligt definitionen ovan.

.NET SDK fördefinierade listan över paket som ska beskäras åt dig.

Så här fungerar PrunePackageReference

När ett paket anges som ska beskäras under återställningen tas det bort från beroendediagrammet. När ett paket rensas visas ett meddelande med detaljerad information som anger att paketet har tagits bort för det angivna målramverket.

För transitiva paket, vilket innebär beroenden för andra paket eller projekt, laddas paketen inte ned och visas inte i någon av utdata från NuGet.

För de direkta paketen tillämpas PrivateAssets='all' och IncludeAssets='none' implicit.

  • IncludeAssets='none' säkerställer att sammansättningarna från det här paketet inte används under bygget. Innan beskärningen fanns säkerställde konfliktlösning under byggprocessen att plattformsammansättningar föredrogs framför dem som kom från paketen.
  • PrivateAssets='all' säkerställer att paketen inte inkluderas i andra paket eller via projektreferenser.

Example:

Ett projekt som nedan:

  <PropertyGroup>
    <TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="9.0.4" />
  </ItemGroup>

kommer att ha en nuspec med följande beroenden:

<dependencies>
    <group targetFramework=".NETFramework4.7.2">
        <dependency id="System.Text.Json" version="9.0.4" />
    </group>
    <group targetFramework="net9.0">
    </group>
</dependencies>

När en direkt PackageReference kan tas bort helt från projektet och ett av projektramverken är .NET 10 eller senare, genereras NU1510 och du uppmanas att ta bort paketet. Om du följer det här förslaget minskas komplexiteten i projektdiagrammet.

I följande tabell sammanfattas alla beteenden för paketrensning.

Beroendeborttagning Behavior
Matchar ID:t för ett transitivt paket som kommer via ett annat paket Prune
Matchar ID:t för ett transitivt paket som kommer via ett annat projekt Prune
Matchar ID:t för en direkt PackageReference Använd PrivateAssets='all' och IncludeAssets='none' höj nu1510-varningen när paketet kan tas bort från alla ramverk och projektet riktar sig mot .NET 10.
Matchar ID:t för en ProjectReference Rensa inte och höj inte NU1511-varningen när projektet riktar in sig på .NET 10

PrunePackageReference-program

Fördelarna med paketrensning är tvådelat:

  • Prestandafördelar genom att minska antalet paket i ett beroendediagram
  • Minskning av falska positiva resultat från komponentskannrar, till exempel NuGetAudit

Beskärning är särskilt värdefullt när du granskar paket med NuGetAuditMode inställt på all. Om du använder .NET 9 rekommenderar vi att du provar att rensa genom att ställa in RestoreEnablePackagePruning på true.

  • Last updated on