Sdílet prostřednictvím

PackageReference v souborech projektu

Odkazy na balíčky, které využívají <PackageReference> položky MSBuild, určují závislosti balíčků NuGet přímo v souborech projektu, na rozdíl od samostatného packages.config souboru. Použití PackageReference nemá vliv na další aspekty NuGetu; například nastavení v NuGet.Config souborech (včetně zdrojů balíčků) se stále používá, jak je vysvětleno v běžných konfiguracích NuGet.

Pomocí PackageReference můžete také pomocí podmínek nástroje MSBuild zvolit odkazy na balíčky pro každou cílovou architekturu nebo jiné seskupení. Umožňuje také jemně odstupňovanou kontrolu nad závislostmi a tokem obsahu. (Další informace najdete v aktivacích a obnovení NuGet jako cílech MSBuild.)

Podpora typů projektů

Ve výchozím nastavení se PackageReference používá pro projekty .NET, projekty .NET Standard a projekty UPW určené pro Windows 10 Build 15063 (Creators Update) a novější s výjimkou projektů UPW jazyka C++. Projekty rozhraní .NET Framework podporují PackageReference, ale aktuálně je výchozí hodnota packages.config. Chcete-li použít PackageReference v projektu rozhraní .NET Framework, migrujte závislosti ze packages.config souboru projektu a potom odeberte packages.config.

ASP.NET aplikace, které cílí na úplné rozhraní .NET Framework, zahrnují pouze omezenou podporu PackageReference. Typy projektů C++ a JavaScript nejsou podporovány.

Přidání položky PackageReference

Do souboru projektu přidejte závislost pomocí následující syntaxe:

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

Řízení verzí závislostí

Konvence pro určení verze balíčku je stejná jako při použití packages.config:

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

V předchozím příkladu znamená verze 3.6.0 libovolnou verzi = >3.6.0 s předvolbou pro nejnižší verzi, jak je popsáno ve správě verzí balíčků.

Použití PackageReference pro projekt bez závislostí balíčků

Upřesnit: Pokud nemáte v projektu nainstalované žádné balíčky (žádné PackageReferences v souboru projektu a žádný soubor packages.config), ale chcete projekt obnovit jako styl PackageReference, můžete nastavit vlastnost Project RestoreProjectStyle na PackageReference v souboru projektu.

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

To může být užitečné, pokud odkazujete na projekty, které mají styl PackageReference (existující projekty ve stylu csproj nebo SDK). To umožní balíčky, na které tyto projekty odkazují, být "tranzitivně" odkazovány vaším projektem.

PackageReference a zdroje

V projektech PackageReference jsou přechodné verze závislostí vyřešeny v době obnovení. V projektech PackageReference musí být všechny zdroje dostupné pro všechna obnovení.

Plovoucí verze

Plovoucí verze jsou podporovány při použití PackageReference:

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

Řízení prostředků závislostí

Závislost můžete používat čistě jako vývojový nástroj a nechcete ji vystavit projektům, které budou váš balíček využívat. V tomto scénáři můžete toto chování řídit pomocí metadat PrivateAssets.

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

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

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

Následující značky metadat řídí komponenty závislostí:

Tag Description Výchozí hodnota
IncludeAssets Tyto prostředky budou spotřebovány. all
ExcludeAssets Tyto prostředky nebudou využity. none
PrivateAssets Tyto prostředky budou spotřebovány, ale nebudou převedeny do nadřazeného projektu. contentfiles;analyzers;build

Povolené hodnoty pro tyto značky jsou následující: hodnoty jsou oddělené středníkem, s výjimkou all a none, které se musí objevit samostatně.

Value Description
kompilovat Obsah složky lib a určuje, zda váš projekt může být zkompilován proti sestavením ve složce.
modul runtime Obsah složek lib a runtimes a určuje, zda budou tato sestavení zkopírována do výstupního adresáře sestavení.
contentFiles Obsah složky contentfiles
build .props a .targets ve build složce
buildMultitargeting (4.0).props a .targets ve složce buildMultitargeting pro cílení napříč platformami
buildTransitive (5.0+).props a .targets ve buildTransitive složce pro prostředky, které přechodně proudí do jakýkoli spotřebitelský projekt. Podívejte se na stránku funkce .
analyzers Analyzátory .NET
nativní Obsah složky native
none Nepoužívá se žádná z výše uvedených možností.
all Všechny výše uvedené (s výjimkou 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>

Mějte na paměti, že vzhledem k tomu, že build není součástí PrivateAssets, cíle a vlastnosti budou předány do nadřazeného projektu. Představte si například, že výše uvedený odkaz se používá v projektu, který sestaví balíček NuGet s názvem AppLogger. AppLogger může využívat cíle a vlastnosti z Contoso.Utility.UsefulStuff, stejně jako projekty, které využívají AppLogger.

Note

Pokud developmentDependency je v souboru nastavená .nuspectrue hodnota, označí se balíček jako závislost jen pro vývoj, která brání zahrnutí balíčku jako závislosti v jiných balíčcích. S PackageReference (NuGet 4.8+) tento příznak také znamená, že z kompilace vyloučí prostředky sestavení. Další informace naleznete v tématu DevelopmentDependency support for PackageReference.

Cílení na více rámců

SDK-styl projekty podporují více cílení tím, že vypisují více hodnot ve vlastnosti TargetFrameworks. Když projekt cílí na více architektur, obnovení NuGet vytvoří samostatný graf závislostí pro každou architekturu a dotnet pack vytvoří balíček s prostředky specifickými pro architekturu pro každý cíl.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>
</Project>

Podrobný průvodce nastavením více cílených projektů najdete v tématu Podpora více rozhraní .NET Framework v souboru projektu.

Jak fungují hodnoty TargetFramework

Vlastnost TargetFramework v souboru projektu je popisný název – alias – který se přeloží do kanonické identity architektury. Sada .NET SDK provádí tento překlad nastavením TargetFrameworkMoniker (TFM) a v případě potřeby TargetPlatformMoniker vlastnosti.

NuGet pro kontroly kompatibility balíčků používá tyto vlastnosti monikeru, nikoli TargetFramework řetězec. To znamená, že TargetFramework samotná hodnota může být libovolný řetězec, pokud jsou vlastnosti monikeru nastaveny správně.

Další podrobnosti o mechanismu aliasingu najdete v tématu Hodnoty TargetFramework jsou aliasy.

Přidání podmínky PackageReference

Podmínku můžete použít k řízení, jestli je balíček součástí. Podmínky mohou používat libovolnou proměnnou MSBuild nebo proměnnou definovanou v souboru cílů nebo props. V současné době je však podporována pouze TargetFramework proměnná.

Řekněme například, že cílíte na netstandard1.4 i na net452, ale máte závislost, která je použitelná pouze pro net452. V takovém případě nechcete netstandard1.4 , aby projekt, který využívá váš balíček, přidal tuto nepotřebnou závislost. Chcete-li tomu zabránit, zadejte podmínku na PackageReference.

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

Balíček vytvořený pomocí tohoto projektu zobrazí, že Newtonsoft.Json je součástí závislosti pouze pro net452 cíl:

Výsledek použití podmínky u PackageReference ve VS2017

Podmínky lze také aplikovat na úrovni ItemGroup a budou platit pro všechny podřízené prvky PackageReference:

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

GeneratePathProperty

Tato funkce je dostupná s NuGetem 5.0 nebo novějším a se sadou Visual Studio 2019 16.0 nebo vyšší.

Někdy je žádoucí odkazovat na soubory v balíčku z cíle MSBuild. V projektech založených na packages.config jsou balíčky nainstalovány ve složce relativně k souboru projektu. V PackageReference se však balíčky používají ze složky global-packages, která se může lišit od počítače po počítač.

Pro přemění této mezery NuGet zavedl vlastnost, která odkazuje na umístění, ze kterého bude balíček spotřebová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>

NuGet navíc automaticky generuje vlastnosti pro balíčky obsahující složku nástrojů.

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

Vlastnosti nástroje MSBuild a identity balíčků nemají stejná omezení, takže identita balíčku musí být změněna na popisný název nástroje MSBuild s předponou slova Pkg. Pokud chcete ověřit přesný název vygenerované vlastnosti, podívejte se na vygenerovaný soubor nuget.g.props.

Aliasy PackageReference

V některých výjimečných případech budou různé balíčky obsahovat třídy ve stejném oboru názvů. Počínaje NuGetem 5.7 a sadou Visual Studio 2019 Update 7, PackageReference podporuje Aliases, což odpovídá funkci ProjectReference. Ve výchozím nastavení nejsou k dispozici žádné aliasy. Při zadání aliasu musí být všechna sestavení pocházející z anotovaného balíčku odkazována s aliasem.

Můžete se podívat na ukázkové využití na NuGet\Samples.

V souboru projektu zadejte aliasy následujícím způsobem:

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

A v kódu ho použijte takto:

extern alias ExampleAlias;

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

Upozornění a chyby NuGetu

Tato funkce je dostupná s NuGetem 4.3 nebo novějším a se sadou Visual Studio 2017 15.3 nebo vyšší.

Pro mnoho scénářů balíčků a obnovení jsou všechna upozornění a chyby NuGet kódovány a začínají na NU****. Všechny upozornění a chyby NuGet jsou uvedeny v dokumentaci odkazující na reference.

NuGet sleduje následující vlastnosti upozornění:

  • TreatWarningsAsErrors, považovat všechna upozornění za chyby.
  • WarningsAsErrors, zacházejte s konkrétními upozorněními jako s chybami.
  • NoWarn, skryjte konkrétní upozornění, buď pro projekt, nebo pro balíček.

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>

Potlačení upozornění NuGetu

Ačkoli se doporučuje vyřešit všechna upozornění NuGet během operací balení a obnovení, v některých situacích může být jejich potlačení odůvodněné. Chcete-li potlačit varování v rámci celého projektu, zvažte následující:

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

V některých případech se upozornění vztahují pouze na určitý balíček v grafu. Toto upozornění můžete potlačit selektivněji přidáním NoWarn položky PackageReference.

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

Potlačení varování balíčků NuGet ve Visual Studiu

Ve Visual Studiu můžete také potlačit upozornění prostřednictvím IDE.

Uzamykání závislostí

Tato funkce je dostupná s NuGetem 4.9 nebo novějším a se sadou Visual Studio 2017 15.9 nebo vyšší.

Vstup do obnovení NuGet je sada PackageReference položek ze souboru projektu (nejvyšší úrovně nebo přímé závislosti) a výstupem je úplné uzavření všech závislostí balíčku, včetně tranzitivních závislostí. NuGet se pokusí vždy vytvořit stejné úplné uzavření závislostí balíčku, pokud se vstupní seznam PackageReference nezměnil. Existují však některé scénáře, kdy to nejde provést. Například:

  • Při použití plovoucích verzí, jako <PackageReference Include="My.Sample.Lib" Version="4.*"/>je . I když je záměrem při každém obnovení balíčků přejít na nejnovější verzi, existují scénáře, kdy uživatelé požadují, aby byl graf uzamčen na určitou nejnovější verzi a aby se, pokud je to možné při explicitním pokynu, aktualizoval na novější verzi.

  • Publikuje se novější verze balíčku odpovídající požadavkům na verzi PackageReference. Například:

    • Den 1: Pokud jste zadali <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> , ale verze dostupné v úložištích NuGet byly 4.1.0, 4.2.0 a 4.3.0. V tomto případě by NuGet určil verzi 4.1.0 (nejbližší nižší verzi).

    • Den 2: Verze 4.0.0 se publikuje. NuGet teď najde přesnou shodu a začne přeložit na verzi 4.0.0.

  • Z úložiště se odebere daná verze balíčku. I když nuget.org nepovoluje odstranění balíčků, ne všechna úložiště balíčků mají toto omezení. Výsledkem je, že NuGet najde nejlepší shodu, když se nedá přeložit na odstraněnou verzi.

Povolení zamykacího souboru

Pokud chcete zachovat úplné uzavření závislostí balíčku, můžete se přihlásit k funkci uzamčení souboru nastavením vlastnosti RestorePackagesWithLockFile MSBuild pro váš projekt:

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

Pokud je tato vlastnost nastavená, vygeneruje obnovení NuGet soubor zámku (packages.lock.json) v kořenovém adresáři projektu, který obsahuje všechny závislosti balíčku.

Formát packages.lock.json je verzovaný. Verze formátu závisí na funkcích, které používáte, jako je tranzitivní uzamčení centrální správy balíčků nebo duplikování efektivních cílových rámců.

Note

Jakmile má projekt packages.lock.json soubor v kořenovém adresáři, soubor zámku se vždy použije s obnovením, i když vlastnost RestorePackagesWithLockFile není nastavena. Další způsob, jak zapnout tuto funkci, je vytvořit fiktivní prázdný soubor packages.lock.json v kořenovém adresáři projektu.

restore chování se zamykacím souborem

Pokud soubor zámku existuje pro projekt, NuGet použije tento soubor zámku ke spuštění restore. NuGet rychle zkontroluje, jestli nedošlo k nějakým změnám závislostí balíčku, jak je uvedeno v souboru projektu (nebo v souborech závislých projektů), a pokud nedošlo k žádným změnám, pouze obnoví balíčky uvedené v souboru zámku. Neexistuje žádné opakované vyhodnocení závislostí balíčků.

Pokud NuGet zjistí změnu definovaných závislostí, jak je uvedeno v souborech projektu, znovu vyhodnotí graf balíčku a aktualizuje soubor zámku tak, aby odrážel uzavření nového balíčku projektu.

V případě CI/CD a dalších scénářů, kdy nechcete měnit závislosti balíčků za běhu, můžete toho dosáhnout nastavením lockedmode na true.

Pro dotnet.exe spusťte:

> dotnet.exe restore --locked-mode

Pro msbuild.exe spusťte:

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

Tuto podmíněnou vlastnost MSBuild můžete také nastavit v souboru projektu:

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

Pokud je uzamčený režim aktivován, obnovení buď obnoví přesné balíčky uvedené v uzamčeném souboru, nebo selže, pokud jste po vytvoření uzamčeného souboru aktualizovali definované závislosti balíčků pro projekt.

Zamknout soubory a PrunePackageReference

Funkce PrunePackageReference mění závislosti projektu odebráním nepotřebných tranzitivních balíčků. Při odebírání těchto balíčků by nemělo mít za běhu vliv, ale ovlivní uzamčené soubory. Pokud povolíte vyřezávání pro existující projekt, může pokaždé, když se soubor zámku znovu vygeneruje, vést k menšímu počtu balíčků než před vyřazením. Kontrola aktuálnosti zamčeného souboru, která pohání režim uzamčení, je si vědoma odstřihávání. To znamená, že pokud jste povolili odstřihávání v projektu, kontrola zohlední balíčky, které byly odstraněny. Při příštím vygenerování zámkového souboru se však vyloučí odstraněné balíčky, takže se může vyskytnout rozdíl, který je větší než obvykle.

Nastavení zamykacího souboru jako součásti zdrojového úložiště

Pokud vytváříte aplikaci, spustitelný soubor a daný projekt je na začátku řetězu závislostí, zkontrolujte soubor zámku do úložiště zdrojového kódu, aby ho NuGet mohl během obnovení využít.

Pokud je však váš projekt knihovny, který neposkytujete, nebo běžný kódový projekt, na kterém závisí jiné projekty, neměli byste soubory uzamčení přidávat do verzovacího systému jako součást zdrojového kódu. Při zachování souboru zámku nedošlo k žádným škodám, ale závislosti uzamčeného balíčku pro běžný projekt kódu nelze použít, jak je uvedeno v souboru zámku během obnovení nebo sestavení projektu, který závisí na tomto společném projektu kódu.

Example:

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

Pokud ProjectA je závislost na PackageX verzi 2.0.0 a odkazuje také na ProjectB odkazy, které závisí na PackageX verzi 1.0.0, pak zámek souboru zobrazí ProjectB seznam závislostí na PackageX verzi 1.0.0. Pokud je ale ProjectA sestaven, jeho soubor zámku bude obsahovat závislost na PackageX verzi 2.0.0 a nikoli1.0.0, jak je uvedeno v souboru zámku pro ProjectB. Soubor zámku běžného projektu kódu tedy nemá příliš velké informace o balíčcích vyřešených pro projekty, které na něm závisejí.

Rozšiřitelnost uzamčení souborů

Pomocí souboru zámku můžete řídit různé chování obnovení, jak je popsáno níže:

možnost NuGet.exe dotnet možnost Ekvivalentní možnost nástroje MSBuild Description
-UseLockFile --use-lock-file RestorePackagesWithLockFile Přihlásí se k používání zamykacího souboru.
-LockedMode --locked-mode RestoreLockedMode Povolí uzamčený režim pro obnovení. To je užitečné ve scénářích CI/CD, ve kterých chcete opakovatelné buildy.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Tato možnost je užitečná u balíčků s plovoucí verzí definovanou v projektu. Obnovení NuGet ve výchozím nastavení neaktualizuje verzi balíčku automaticky při každém obnovení, pokud s touto možností nespustíte obnovení.
-LockFilePath --lock-file-path NuGetLockFilePath Určuje vlastní umístění zámkového souboru pro projekt. Ve výchozím nastavení NuGet podporuje packages.lock.json v kořenovém adresáři. Pokud máte ve stejném adresáři více projektů, NuGet podporuje soubor zámku specifický pro jednotlivé projekty.

Překladač závislostí NuGet

Překladač závislostí NuGet se řídí čtyřmi pravidly popsanými v dokumentu o řešení závislostí.

Kvůli zlepšení výkonu a škálovatelnosti operace obnovení se algoritmus obnovení přepsal ve verzi 6.12. Od verze 6.12 je nový algoritmus obnovení ve výchozím nastavení povolený pro všechny projekty PackageReference. I když je nový algoritmus obnovení funkčně ekvivalentní předchozímu algoritmu, stejně jako u jakéhokoli softwaru, jsou možné chyby. Chcete-li se vrátit k předchozí implementaci, nastavte MSBuild vlastnost RestoreUseLegacyDependencyResolver na true.

Pokud dojde k selhání obnovení ve verzi 6.12, .NET 9 nebo 17.12, které se v dřívějších verzích nezprodukovaly, zapište problém na GitHubu. Jakékoli rozdíly mezi starými a novými algoritmy můžou mít různé dopady, například během kompilace nebo za běhu. Existuje také šance, že změny nevedou k selháním, ale obnovení různých verzí balíčků. Pokud si myslíte, že na vás můžou mít vliv jakékoli změny, tady jsou kroky, které můžete provést, abyste ověřili, jestli jsou změny v algoritmu obnovení NuGet původní příčinou.

Obnovení zapíše výsledky v MSBuildProjectExtensionsPath adresáři, který je možné porovnat s novými a starými algoritmy a najít rozdíly. Obvykle se jedná o obj složku sestavení. Můžete použít msbuild.exe nebo dotnet.exe pro další kroky.

  1. Odeberte složku obj pro váš projekt.

  2. Spustit msbuild -t:restore

  3. Uložte obsah obj do umístění naznačujícího, že jde o new chování.

  4. Spusťte msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true".

  5. Uložte obsah obj do umístění naznačujícího, že jde o legacy chování.

  6. Porovnejte soubory ve dvou adresářích, zejména project.assets.json.

    Nástroje, které můžou zvýraznit rozdíly, jsou pro tento účel zvláště užitečné (například v editoru Visual Studio Code otevřete oba soubory a klikněte pravým tlačítkem myši na výběr pro porovnání a "porovnat s vybraným").

Pokud postupujete podle výše uvedené metody, měl by být mezi soubory project.assets.json přesně jeden rozdíl.

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

Pokud existují nějaké další rozdíly, zapište problém na GitHubu se všemi podrobnostmi.

AssetTargetFallback

Vlastnost AssetTargetFallback umožňuje zadat další kompatibilní verze frameworku pro projekty, které váš projekt odkazuje, a balíčky NuGet, které váš projekt využívá.

Pokud zadáte závislost balíčku pomocí PackageReference, ale tento balíček neobsahuje prostředky, které jsou kompatibilní s cílovou architekturou vašich projektů, vlastnost AssetTargetFallback přichází do hry. Kompatibilita odkazovaného balíčku se znovu zkontroluje pro každý cílový framework, který je zadaný v AssetTargetFallback. Pokud je project nebo package reference přes AssetTargetFallback, bude vyvoláno upozornění NU1701.

Příklady toho, jak AssetTargetFallback ovlivňuje kompatibilitu, najdete v tabulce níže.

Architektura projektu AssetTargetFallback Architektury balíčků Result
.NET Framework 4.7.2 .NET Standard 2.0 .NET Standard 2.0
Aplikace .NET Core 3.1 .NET Standard 2.0, .NET Framework 4.7.2 .NET Standard 2.0
Aplikace .NET Core 3.1 .NET Framework 4.7.2 Nekompatibilní, selhání s chybou NU1202
Aplikace .NET Core 3.1 net472;net471 .NET Framework 4.7.2 .NET Framework 4.7.2 s NU1701

Jako oddělovač můžete použít ; pro zadání více frameworků. Pokud chcete přidat náhradní architekturu, můžete provést následující:

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

Pokud chcete přepsat namísto přidání k existujícím $(AssetTargetFallback) hodnotám, můžete tuto možnost AssetTargetFallback vynechat.

Note

Pokud používáte .NET SDK projekt, odpovídající hodnoty se automaticky nakonfigurují a není třeba je nastavovat ručně.

byla to dřívější funkce, která se pokusila tento problém vyřešit, ale je v zásadě nefunkční a neměla by se používat. Pokud chcete migrovat z $(PackageTargetFallback) do $(AssetTargetFallback), jednoduše změňte název vlastnosti.

Cílení na více verzí s duplicitními architekturami

Tato funkce vyžaduje NuGet 7.6 / .NET SDK 10.0.300 nebo novější.

Vzhledem k tomu, že TargetFramework hodnoty jsou aliasy, může několik aliasů odkazovat na stejný efektivní rámec. Od NuGetu 7.6 / .NET SDK 10.0.300, NuGet a sady .NET SDK podporují tento scénář.

To umožňuje případy použití, například:

  • Sestavení s více identifikátory RID: Vytvářejte sestavení specifická pro platformu z jednoho projektu.

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0;linux;ios</TargetFrameworks>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework)' == 'linux' OR '$(TargetFramework)' == 'ios' OR '$(TargetFramework)' == 'net10.0'">
    <TargetFrameworkIdentifier>.NETCoreApp</TargetFrameworkIdentifier>
    <TargetFrameworkVersion>v10.0</TargetFrameworkVersion>
    <TargetFrameworkMoniker>.NETCoreApp,Version=v10.0</TargetFrameworkMoniker>
  </PropertyGroup>
</Project>

  • Srovnávací testy různých verzí balíčku

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>benchmark7.0;benchmark8.0</TargetFrameworks>
  </PropertyGroup>

  <!-- Frameworks omitted for brevity-->

  <ItemGroup>
    <PackageReference Include="BenchmarkDotNet" Version="0.13.9" />
    <PackageReference Include="Contoso.FastLibrary" Version="7.0" Condition="'$(TargetFramework)' == 'benchmark7.0' "/>
    <PackageReference Include="Contoso.FastLibrary" Version="8.0" Condition="'$(TargetFramework)' == 'benchmark8.0' "/>
  </ItemGroup>
</Project>

Balení

Balíček NuGet může obsahovat pouze jednu sadu výstupu sestavení a jednu skupinu závislostí pro každý efektivní framework. Když zabalíte projekt s duplicitními efektivními frameworky, musíte sdělit NuGetu, který alias přispívá k těmto prostředkům, jinak balík vyvolá NU5051. Postup řešení a příklady najdete v nu5051 .

Odkazy na projekt

Když projekt odkazuje na jiný projekt, který má více aliasů, které se řeší na stejnou platformu, NuGet použije název aliasu jako rozhodovací kritérium. Pokud má odkazující projekt alias se stejným názvem jako v odkazovaném projektu, je tento alias upřednostňovaný. Pokud neexistuje žádný odpovídající název a existuje více kandidátů, NuGet hlásí chybu.

Omezení

  • Pouze projekty ve stylu sady SDK podporují duplicitní efektivní architektury.
  • Aliasy, které obsahují znaky oddělovače cest (/ nebo \) jsou blokované.
  • Uživatelské rozhraní Správce balíčků sady Visual Studio nemá zvláštní podporu pro duplicitní architektury, ale balíčky můžete spravovat úpravou souboru projektu přímo nebo pomocí rozhraní příkazového dotnet řádku.

PrunePackageReference

Modul runtime .NET se neustále vyvíjí, přičemž každá vydaná verze vylepšuje výkon a nová rozhraní API. Nové funkce přidané do .NET se také někdy poskytují jako balíčky, aby vývojáři, kteří používají starší cílové architektury, mohli knihovnu používat, například System.Text.Json. To může často vést k System.Text.Json 8.0.0 v projektu zaměřeném na .NET 9 nebo .NET 8. Tato závislost není nutná a při řešení konfliktů během stavby by nebylo použito sestavení pocházející z balíčku, protože je již k dispozici v .NET Runtime. Počínaje verzí NuGet 6.13 a .NET SDK 9.0.200 PrunePackageReference umožňuje vyřízání těchto balíčků v době obnovení pro projekty založené na sadě .NET SDK. První iterace prořezávání ovlivnila pouze tranzitivní balíčky, ale počínaje sadou .NET SDK 10 ovlivňuje prořezávání i přímé balíčky.

Vyřazení balíčků je k dispozici jako volitelná funkce se sadou .NET 9 SDK a je ve výchozím nastavení povolené ve všech projektových rozhraních, která ve verzi .NET 10 SDK cílí na >= .NET 10.0.

Ořezávání balíčků je k dispozici pouze s výchozím řešitelem závislostí, jakmile bylo vydáno ve verzi 6.12.

Specifikace PrunePackageReference

Seznam balíčků, které se mají odstranit, je definován položkou PrunePackageReference.

Attributes Description
Version Určuje maximální verzi, která se má odstranit. 1.0.0 znamená, že všechny balíčky až do verze 1.0.0 budou vyřazeny. Pro 1.0.0budou 0.9.0 a 1.0.0 vyřazeny, ale 1.0.1 by ne.

Následující vlastnosti lze použít k úpravě chování prořezávání.

PropertyName Description
RestoreEnablePackagePruning Umožňuje odstranění nepotřebných balíčků pro balíčky specifikované pomocí PrunePackageReference. Tato vlastnost je pro cílové prostředí, a platné hodnoty jsou true a false. Výchozí hodnoty se můžou lišit v závislosti na sadě .NET SDK, jak je definováno výše.

Sada .NET SDK předdefinuje seznam balíčků, které se mají vyříznout za vás. Tento seznam je založený na sdílených architekturách zadaných v projektu. Zvažují se pouze přímé odkazy na rámce a pro rámce, které se přenesou prostřednictvím balíčků, nebudou data ořezávání přidána.

Jak funguje PrunePackageReference

Pokud je zadaný balíček, který se má během obnovení vyřadit, odebere se z grafu závislostí. Při vyřazení balíčku se zobrazí zpráva s podrobnou úrovní podrobností, která indikuje, že balíček byl odebrán pro dané cílové rozhraní.

U tranzitivních balíčků, což znamená závislosti jiných balíčků nebo projektů, se balíčky nestáhnou a nezobrazí se ve výstupech NuGetu.

Pro přímé balíčky, implicitně se použijí PrivateAssets='all' a IncludeAssets='none'.

  • IncludeAssets='none' zajišťuje, aby se sestavení z tohoto balíčku během sestavování nepoužívala. Před vyřazením existovalo řešení konfliktů během sestavení zajistilo, že sestavení platformy byla upřednostňovaná před sestaveními pocházejícími z balíčků.
  • PrivateAssets='all' zajišťuje, že balíčky nejsou zahrnuté v jiných balíčcích ani skrze odkazy na projekty.

Example:

Projekt podobný následujícímu:

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

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

bude mít soubor "nuspec" s následujícími závislostmi:

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

Pokud je možné z projektu zcela odebrat přímý balíček PackageReference a jedna z architektur projektů je .NET 10 nebo novější, bude vyvolána NU1510 s žádostí o odebrání balíčku. Po provedení tohoto návrhu se sníží složitost grafu projektu.

Následující tabulka shrnuje všechna chování ohledně prořezávání balíčků.

Dispozice závislostí Behavior
Odpovídá ID tranzitivního balíčku přicházejícího prostřednictvím jiného balíčku. Prune
Odpovídá ID tranzitivního balíčku přicházejícího přes jiný projekt. Prune
Odpovídá přímé ID PackageReference Použít PrivateAssets='all' a IncludeAssets='none' a vyvolat upozornění NU1510, když je možné balíček odebrat ze všech frameworků a projekt cílí na .NET 10.
Odpovídá ID objektu ProjectReference Neřezejte ani nevyvolávejte upozornění NU1511, když se projekt zaměřuje na .NET 10

Aplikace PrunePackageReference

Výhody ořezávání balíků jsou dvojaké:

  • Výhody výkonu díky snížení počtu balíčků v grafu závislostí
  • Snížení počtu falešně pozitivních výsledků u komponentových skenerů, jako je NuGetAudit

Vyřezávání je obzvláště cenné při auditování balíčků s nastaveným NuGetAuditMode nastavením all. Pokud používáte .NET 9, doporučujeme vyzkoušet vyřezávání nastavením RestoreEnablePackagePruning na true.

  • Last updated on