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í:
| Značka | Popis | Výchozí hodnota |
|---|---|---|
| IncludeAssets | Tyto prostředky budou spotřebovány. | vše |
| ExcludeAssets | Tyto prostředky nebudou využity. | Žádná |
| PrivateAssets | Tyto prostředky budou spotřebovány, ale nebudou toky do nadřazeného projektu. | obsahové soubory; Analyzátory; Budovat |
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ě:
| Hodnota | Popis |
|---|---|
| kompilovat | lib Obsah složky a určuje, zda je možné projekt zkompilovat proti sestavením v rámci složky. |
| modul runtime | Obsah a lib složka a runtimes ovládací prvky, zda budou tato sestavení zkopírována do výstupního adresáře sestavení |
| contentFiles | contentfiles Obsah složky |
| build | .props a .targets ve build složce |
| sestaveníMultitargeting | (4.0).props a .targets ve buildMultitargeting složce pro cílení napříč architekturami |
| buildTransitive | (5.0+).props a .targets ve složce pro prostředky, které protékají tranzitivně do jakéhokoliv spotřebujícího buildTransitive projektu. Podívejte se na stránku funkce . |
| Analyzátory | Analyzátory .NET |
| nativní | native Obsah složky |
| Žádná | Nepoužívá se žádná z výše uvedených možností. |
| vše | 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 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.
Poznámka:
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. U PackageReference (NuGet 4.8+) tento příznak také znamená, že z kompilace vyloučí prostředky v době kompilace. Další informace naleznete v tématu DevelopmentDependency support for PackageReference.
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 chybyWarningsAsErrors, zacházet s konkrétními upozorněními jako s chybamiNoWarn, 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.
Poznámka:
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 se přihlásit k této funkci, je vytvořit fiktivní prázdný packages.lock.json soubor 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 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 ne1.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:
| možnost NuGet.exe | dotnet option | Ekvivalentní možnost nástroje MSBuild | Popis |
|---|---|---|---|
-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 | Definuje vlastní umístění souboru zámku 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 projekt. packages.<project_name>.lock.json |
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.
| Architektura projektu | AssetTargetFallback | Architektury balíčků | Výsledek |
|---|---|---|---|
| .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č 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).
Poznámka:
Pokud používáte projekt založený na sadě .NET SDK, nakonfigurují se odpovídající $(AssetTargetFallback) hodnoty a nemusíte je nastavovat ručně.
$(PackageTargetFallback)byla dřívější funkce, která se pokusila tento problém vyřešit, ale v zásadě je poškozena a neměla by být použita. Pokud chcete migrovat z $(PackageTargetFallback) do $(AssetTargetFallback), jednoduše změňte název vlastnosti.
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro