PackageReference v souborech projektu

Odkazy na balíčky pomocí <PackageReference> položek NÁSTROJE MSBuild určují závislosti balíčků NuGet přímo v souborech projektu, nikoli 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ší podrobnosti najdete v tématuBalíček NuGet a obnovení jako cíle NÁSTROJE MSBuild.)

Podpora typů projektů

Ve výchozím nastavení se PackageReference používá pro projekty .NET Core, 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. Pokud chcete použít PackageReference, proveďte migraci závislostí do packages.config souboru projektu a pak 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í 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í verze 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é jsou ve stylu 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 s 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í PrivateAssets metadat.

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

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

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

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

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

<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 build , že není součástí PrivateAssets, cíle a props budou tokovat 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 props z Contoso.Utility.UsefulStuff, stejně jako projekty, které využívají AppLogger.

Přidání podmínky PackageReference

Podmínku můžete použít k řízení, zda je balíček zahrnutý, kde 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 netstandard1.4 , net452 ale máte závislost, která je použitelná pouze pro net452. V takovém případě nechcete netstandard1.4 , aby projekt, který váš balíček využívá, přidal tuto nepotřebnou závislost. Chcete-li tomu zabránit, zadejte podmínku následujícím PackageReference způsobem:

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

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

<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 packages.config projektech založených jsou balíčky nainstalovány ve složce vzhledem k souboru projektu. V PackageReference se však balíčky spotřebová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.

Příklad:

  <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 vygeneruje 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, která odpovídá ProjectReference, PackageReference podporuje Aliases. 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 balíčku s poznámkami odkazována s aliasem.

Ukázkové využití najdete na webu 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šechna upozornění a chyby NuGet jsou uvedeny v referenční dokumentaci.

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

• TreatWarningsAsErrors, považovat všechna upozornění za chyby
• WarningsAsErrors, zacházet s konkrétními upozorněními jako s chybami
• NoWarn, skryjte konkrétní upozornění, ať už pro celý projekt, nebo pro celý balíček.

Příklady:

<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

I když se doporučuje vyřešit všechna upozornění NuGet během operací balíčku a obnovení, v některých situacích je potlačení je zaručeno. Pokud chcete potlačit celou úroveň projektu upozornění, 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ůžeme potlačit selektivněji přidáním položky NoWarn PackageReference.

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

Potlačení upozornění balíčku NuGet v sadě Visual Studio

V sadě Visual Studio můžete také potlačit upozornění prostřednictvím integrovaného vývojového prostředí (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šší nebo přímé závislosti) a výstup 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. Příklad:

• Při použití plovoucích verzí, jako <PackageReference Include="My.Sample.Lib" Version="4.*"/>je . I když je zde 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é vyžadují, aby byl graf uzamčen na určitou nejnovější verzi, a pokud je k dispozici, při explicitním gestu se graf uzamkne na určitou nejnovější verzi a plovoucí 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 se NuGet vyřešil na verzi 4.1.0 (nejbližší minimální verze).

  • 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íčků, 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á, obnovení NuGet vygeneruje soubor zámku – packages.lock.json soubor v kořenovém adresáři projektu, který obsahuje všechny závislosti balíčku.

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 provede rychlou kontrolu, jestli nedošlo k nějakým změnám závislostí balíčku, jak je uvedeno v souboru projektu (nebo závislých souborech 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 to provést nastavením nalockedmode: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 trueuzamčený režim , obnovení buď obnoví přesné balíčky uvedené v souboru zámku, nebo selže, pokud jste po vytvoření souboru zámku aktualizovali definované závislosti balíčků pro projekt.

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í, pak soubor zámku v úložišti zdrojového kódu zkontrolujte, aby ho NuGet mohl během obnovení využít.

Pokud je ale projekt knihovny, který nedoručíte nebo běžný projekt kódu, na kterém závisí jiné projekty, neměli byste soubor zámku vrátit se změnami jako součást zdrojového kódu. Při zachování souboru zámku nedojde k žádné škodě, ale závislosti uzamčeného balíčku pro společný projekt kódu se nedají 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.

Např.

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 ProjectA je však sestaven, jeho soubor zámku bude obsahovat závislost na PackageX verzi 2.0.0 , a ne 1.0.0 tak, 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:

Překladač závislostí NuGet

Překladač závislostí NuGet se řídí 4 pravidly, jak je popsáno 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. obj Odeberte složku projektu.
2. Spusťte příkaz msbuild -t:restore.
3. Uložte obsah obj souboru do umístění, které označuje, že se jedná o new chování.
4. Spusťte příkaz msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true".
5. Uložte obsah obj souboru do umístění, které označuje, že se jedná 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 Visual Studio Code, otevřete oba soubory a použijte kliknutí pravým tlačítkem na výběr pro porovnání a porovnání s vybranými soubory).

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

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

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

AssetTargetFallback

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

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

Příklady, jak AssetTargetFallback ovlivňuje kompatibilitu, najdete v následující tabulce.

Jako oddělovač lze zadat ; více architektur. 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 místo k existujícím AssetTargetFallback hodnotám, můžete tuto možnost opustit$(AssetTargetFallback).