Odkazy na balíčky (PackageReference) v souborech projektuPackage references (PackageReference) in project files

Odkazy na balíčky, pomocí uzlu PackageReference, spravujte závislosti NuGet přímo v souborech projektu (na rozdíl od samostatného packages.config souboru).Package references, using the PackageReference node, manage NuGet dependencies directly within project files (as opposed to a separate packages.config file). Použití PackageReference, jak je voláno, nemá vliv na jiné aspekty NuGet; například nastavení v souborech NuGet.config (včetně zdrojů balíčků) jsou stále aplikována, jak je vysvětleno v tématu běžné konfigurace NuGet.Using PackageReference, as it's called, doesn't affect other aspects of NuGet; for example, settings in NuGet.config files (including package sources) are still applied as explained in Common NuGet configurations.

Pomocí PackageReference můžete také použít podmínky nástroje MSBuild pro výběr odkazů na balíčky na cílové rozhraní nebo jiná seskupení.With PackageReference, you can also use MSBuild conditions to choose package references per target framework, or other groupings. Umožňuje také jemně odstupňovanou kontrolu nad závislostmi a tokem obsahu.It also allows for fine-grained control over dependencies and content flow. (Další podrobnosti najdete v tématu Další informace o sadě NuGet Pack a obnovení jako cíle MSBuild.)(See For more details NuGet pack and restore as MSBuild targets.)

Podpora typu projektuProject type support

Ve výchozím nastavení se PackageReference používá pro projekty .NET Core, .NET Standard projekty a projekty UWP cílené na Windows 10 Build 15063 (Creators Update) a novější, s výjimkou C++ projektů UWP.By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. Projekty .NET Framework podporují PackageReference, ale aktuálně packages.config..NET Framework projects support PackageReference, but currently default to packages.config. Chcete-li použít PackageReference, migrujte závislosti z packages.config do souboru projektu a pak odeberte soubor Packages. config.To use PackageReference, migrate the dependencies from packages.config into your project file, then remove packages.config.

ASP.NET aplikace, které cílí na úplné .NET Framework, zahrnují jenom omezené podpory pro PackageReference.ASP.NET apps targeting the full .NET Framework include only limited support for PackageReference. C++a typy projektů JavaScriptu nejsou podporovány.C++ and JavaScript project types are unsupported.

Přidání PackageReferenceAdding a PackageReference

Přidejte závislost do souboru projektu pomocí následující syntaxe:Add a dependency in your project file using the following syntax:

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

Řízení verze závislostiControlling dependency version

Konvence pro určení verze balíčku je stejná jako při použití packages.config:The convention for specifying the version of a package is the same as when using packages.config:

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

V příkladu výše 3.6.0 označuje všechny verze, které jsou > = 3.6.0 s upřednostněním pro nejnižší verzi, jak je popsáno v tématu Správa verzí balíčků.In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on Package versioning.

Použití PackageReference pro projekt bez PackageReferencesUsing PackageReference for a project with no PackageReferences

Upřesnit: Pokud nemáte v projektu nainstalované žádné balíčky (žádné PackageReferences v souboru projektu a žádný soubor Packages. config), ale chcete, aby se projekt obnovil jako PackageReferenceový styl, můžete nastavit RestoreProjectStyle vlastností projektu na PackageReference. soubor projektu.Advanced: If you have no packages installed in a project (no PackageReferences in project file and no packages.config file), but want the project to be restored as PackageReference style, you can set a Project property RestoreProjectStyle to PackageReference in your project file.

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

To může být užitečné, pokud odkazujete na projekty, které jsou PackageReference styly (existující projekty csproj nebo sady SDK).This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). Tím umožníte, aby balíčky, na které tyto projekty odkazují, byly "transitně" odkazovány vaším projektem.This will enable packages that those projects refer to, to be "transitively" referenced by your project.

PackageReference a zdrojePackageReference and sources

V projektech PackageReference se v době obnovení vyřeší verze přenosných závislostí.In PackageReference projects, the transitive dependency versions are resolved at restore time. V takovém případě musí být v projektech PackageReference k dispozici všechny zdroje pro všechna obnovení.As such, in PackageReference projects all sources need to be available for all restores.

Plovoucí verzeFloating Versions

V PackageReferencejsou podporovány plovoucí verze :Floating versions are supported with 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ávislostiControlling dependency assets

Je možné, že použijete závislost čistě jako ve vývojovém prostředí a nechcete ji vystavit pro projekty, které budou spotřebovávat váš balíček.You might be using a dependency purely as a development harness and might not want to expose that to projects that will consume your package. V tomto scénáři můžete k řízení tohoto chování použít metadata PrivateAssets.In this scenario, you can use the PrivateAssets metadata to control this behavior.

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

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

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

Následující Tagy metadat řídí prostředky závislostí:The following metadata tags control dependency assets:

ZnačkaTag PopisDescription Výchozí hodnotaDefault Value
IncludeAssetsIncludeAssets Tyto prostředky budou spotřebovány.These assets will be consumed všeall
ExcludeAssetsExcludeAssets Tyto prostředky nebudou spotřebovány.These assets will not be consumed žádnánone
PrivateAssetsPrivateAssets Tyto prostředky budou spotřebovány, ale nebudou se přesměrovat do nadřazeného projektu.These assets will be consumed but won't flow to the parent project contentFiles; analyzátory; sestavitcontentfiles;analyzers;build

Přípustné hodnoty pro tyto značky jsou následující, s více hodnotami oddělenými středníkem s výjimkou all a none, které se musí objevit sami:Allowable values for these tags are as follows, with multiple values separated by a semicolon except with all and none which must appear by themselves:

HodnotaValue PopisDescription
kompilovatcompile Obsah složky lib a určuje, zda je projekt kompilován proti sestavením v rámci složkyContents of the lib folder and controls whether your project can compile against the assemblies within the folder
modul runtimeruntime Obsah lib a runtimes složky a určuje, zda budou tato sestavení zkopírována do výstupního adresáře sestaveníContents of the lib and runtimes folder and controls whether these assemblies will be copied out to the build output directory
contentFilescontentFiles Obsah složky contentfilesContents of the contentfiles folder
Sestaveníbuild .props a .targets ve složce build.props and .targets in the build folder
buildMultitargetingbuildMultitargeting (4,0) .props a .targets ve složce buildMultitargeting pro cílení na různé architektury(4.0) .props and .targets in the buildMultitargeting folder, for cross-framework targeting
buildTransitivebuildTransitive (5.0 +) .props a .targets ve složce buildTransitive pro prostředky, jejichž přenos do libovolného náročného projektu probíhá.(5.0+) .props and .targets in the buildTransitive folder, for assets that flow transitively to any consuming project. Podívejte se na stránku funkce .See the feature page.
analyzátoryanalyzers Analyzátory .NET.NET analyzers
nativnínative Obsah složky nativeContents of the native folder
žádnánone Žádná z výše uvedených verzí se nepoužívá.None of the above are used.
všeall Všechny výše uvedené (kromě none)All of the above (except none)

V následujícím příkladu je vše kromě souborů obsahu z balíčku spotřebováno projektem a vše kromě souborů obsahu a analyzátory by vedlo k nadřazenému projektu.In the following example, everything except the content files from the package would be consumed by the project and everything except content files and analyzers would flow to the parent project.

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

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets>
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>

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

Vzhledem k tomu, že build není zahrnuta v PrivateAssets, cíle a props budou tok do nadřazeného projektu.Note that because build is not included with PrivateAssets, targets and props will flow to the parent project. Vezměte v úvahu například, že odkaz výše se používá v projektu, který vytváří balíček NuGet s názvem AppLogger.Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger může využívat cíle a props z Contoso.Utility.UsefulStuff, jako mohou projekty, které využívají AppLogger.AppLogger can consume the targets and props from Contoso.Utility.UsefulStuff, as can projects that consume AppLogger.

Poznámka

Pokud je developmentDependency nastaveno na true v souboru .nuspec, tento balíček označí jako závislost jenom pro vývoj, což zabrání v zahrnutí balíčku jako závislosti v jiných balíčcích.When developmentDependency is set to true in a .nuspec file, this marks a package as a development-only dependency, which prevents the package from being included as a dependency in other packages. Pomocí PackageReference (NuGet 4,8 +) tento příznak také znamená, že vyloučí prostředky při kompilaci z kompilace.With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. Další informace najdete v tématu Podpora DevelopmentDependency pro PackageReference.For more information, see DevelopmentDependency support for PackageReference.

Přidání podmínky PackageReferenceAdding a PackageReference condition

Podmínku můžete použít k určení, zda je balíček zahrnut, kde podmínky mohou používat jakoukoli proměnnou MSBuild nebo proměnnou definovanou v souboru TARGETS nebo props.You can use a condition to control whether a package is included, where conditions can use any MSBuild variable or a variable defined in the targets or props file. V současné době je však podporována pouze proměnná TargetFramework.However, at presently, only the TargetFramework variable is supported.

Řekněme například, že cílíte netstandard1.4 a také net452, ale máte závislost, která je platná pouze pro net452.For example, say you're targeting netstandard1.4 as well as net452 but have a dependency that is applicable only for net452. V takovém případě nechcete, aby netstandard1.4 projekt, který váš balíček spotřebovává, přidal tuto nepotřebnou závislost.In this case you don't want a netstandard1.4 project that's consuming your package to add that unnecessary dependency. Tomu zabráníte zadáním podmínky v PackageReference následujícím způsobem:To prevent this, you specify a condition on the PackageReference as follows:

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

Balíček sestavený pomocí tohoto projektu zobrazí, že Newtonsoft. JSON je obsažen pouze jako závislost pro cíl net452:A package built using this project will show that Newtonsoft.Json is included as a dependency only for a net452 target:

Výsledek použití podmínky v PackageReference s VS2017

Podmínky lze také použít na úrovni ItemGroup a budou platit pro všechny podřízené PackageReference prvky:Conditions can also be applied at the ItemGroup level and will apply to all children PackageReference elements:

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

Uzamykání závislostíLocking dependencies

Tato funkce je k dispozici pro NuGet 4,9 nebo vyšší a pro Visual Studio 2017 15,9 nebo vyšší.This feature is available with NuGet 4.9 or above and with Visual Studio 2017 15.9 or above.

Vstup do obnovení NuGet je sada odkazů na balíčky ze souboru projektu (závislosti na nejvyšší úrovni nebo přímých závislostí) a výstup je plný uzávěr všech závislostí balíčku včetně přenosných závislostí.Input to NuGet restore is a set of Package References from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. V případě, že se vstupní seznam PackageReference nezměnil, nástroj NuGet se pokusí vždy vydávat stejný plný uzávěr závislostí balíčku.NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. Existují však situace, kdy to není možné.However, there are some scenarios where it is unable to do so. Příklad:For example:

  • Když použijete plovoucí verze, jako je <PackageReference Include="My.Sample.Lib" Version="4.*"/>.When you use floating versions like <PackageReference Include="My.Sample.Lib" Version="4.*"/>. I když tady je tento záměr na nejnovější verzi v každé obnovy balíčků, existují situace, kdy uživatelé potřebují, aby byl graf uzamčený na určitou nejnovější verzi a aby byl na novější verzi, pokud je k dispozici, po explicitním gestu.While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.

  • Je publikovaná novější verze balíčku, která odpovídá požadavkům verze PackageReference.A newer version of the package matching PackageReference version requirements is published. NapříkladE.g.

    • Den 1: Pokud jste zadali <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> ale verze, které jsou k dispozici v úložištích NuGet, byly 4.1.0, 4.2.0 a 4.3.0.Day 1: if you specified <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> but the versions available on the NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. V tomto případě se NuGet přeložil na 4.1.0 (nejbližší minimální verzi).In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)

    • Den 2: verze 4.0.0 se publikuje.Day 2: Version 4.0.0 gets published. NuGet teď najde přesnou shodu a začne řešit na 4.0.0NuGet will now find the exact match and start resolving to 4.0.0

  • Daná verze balíčku se odebere z úložiště.A given package version is removed from the repository. I když nuget.org nepovoluje odstraňování balíčků, ne všechna úložiště balíčků mají tato omezení.Though nuget.org does not allow package deletions, not all package repositories have this constraints. Výsledkem je, že NuGet najde nejlepší shodu, když ho nelze vyřešit na odstraněnou verzi.This results in NuGet finding the best match when it cannot resolve to the deleted version.

Povoluje se soubor zámku.Enabling lock file

Aby bylo možné zachovat úplný konec závislostí balíčku, můžete se přihlásit k funkci zámek souboru nastavením vlastnosti MSBuild RestorePackagesWithLockFile pro váš projekt:In order to persist the full closure of package dependencies you can opt-in to the lock file feature by setting the MSBuild property RestorePackagesWithLockFile for your project:

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

Pokud je tato vlastnost nastavená, obnovení NuGet vygeneruje soubor zámku File-packages.lock.json v kořenovém adresáři projektu, který obsahuje seznam všech závislostí balíčku.If this property is set, NuGet restore will generate a lock file - packages.lock.json file at the project root directory that lists all the package dependencies.

Poznámka

Jakmile má projekt packages.lock.json soubor ve svém kořenovém adresáři, soubor zámku se vždy používá s obnovením i v případě, že vlastnost RestorePackagesWithLockFile není nastavena.Once a project has packages.lock.json file in its root directory, the lock file is always used with restore even if the property RestorePackagesWithLockFile is not set. Další možností, jak se vyjádřit k této funkci, je vytvořit v kořenovém adresáři projektu fiktivní prázdný packages.lock.json soubor.So another way to opt-in to this feature is to create a dummy blank packages.lock.json file in the project's root directory.

chování restore se souborem zámkurestore behavior with lock file

Pokud je soubor zámku k dispozici pro projekt, NuGet použije tento soubor zámku ke spuštění restore.If a lock file is present for project, NuGet uses this lock file to run restore. NuGet provede rychlou kontrolu, jestli se v závislostech balíčku nezměnily žádné změny, jak je uvedeno v souboru projektu (nebo v souborech závislých projektů) a jestli nedošlo k žádným změnám, jenom obnoví balíčky uvedené v souboru zámku.NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. Nedošlo k opakovanému vyhodnocení závislostí balíčku.There is no re-evaluation of package dependencies.

Pokud NuGet detekuje změnu v definovaných závislostech, jak je uvedeno v souborech projektu, znovu vyhodnotí graf balíčku a aktualizuje soubor zámku tak, aby odrážel nový uzavření balíčku pro daný projekt.If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project.

V případě CI/CD a dalších scénářů, kde byste nechtěli změnit závislosti balíčku, můžete tak učinit nastavením lockedmode na true:For CI/CD and other scenarios, where you would not want to change the package dependencies on the fly, you can do so by setting the lockedmode to true:

Pro příkaz dotnet. exe spusťte:For dotnet.exe, run:

> dotnet.exe restore --locked-mode

Pro MSBuild. exe spusťte:For msbuild.exe, run:

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

Tuto vlastnost podmíněného MSBuild můžete nastavit také v souboru projektu:You may also set this conditional MSBuild property in your project file:

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

Pokud je trueuzamčený režim, obnovení obnoví buď přesné balíčky uvedené v souboru zámku, nebo selže, pokud jste aktualizovali definované závislosti balíčků pro projekt po vytvoření souboru zámku.If locked mode is true, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.

Nastavit zámek souboru jako součást zdrojového úložištěMake lock file part of your source repository

Pokud vytváříte aplikaci, spustitelný soubor a příslušný projekt jsou na začátku řetězu závislostí a pak proveďte vrácení souboru se zámkem do úložiště zdrojového kódu, aby jej mohla aplikace NuGet využít při obnovení.If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore.

Pokud je však projekt knihovnou projektu, který nedodáte nebo se jedná o běžný projekt kódu, na kterém jsou závislé další projekty, neměli byste soubory zámku vrátit se změnami jako součást zdrojového kódu.However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you should not check in the lock file as part of your source code. Neexistuje žádný škodný soubor zámku, ale nelze použít uzamčené závislosti balíčku pro běžný projekt kódu, jak je uvedeno v souboru zámku během obnovení nebo sestavení projektu, který je závislý na tomto projektu Common-Code.There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project.

Např.Eg.

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

Pokud má ProjectA závislost na PackageX verzi 2.0.0 a také odkazuje ProjectB, které jsou závislé na PackageX verze 1.0.0, pak soubor zámku pro ProjectB zobrazí závislost na PackageX verze 1.0.0.If ProjectA has a dependency on a PackageX version 2.0.0 and also references ProjectB that depends on PackageX version 1.0.0, then the lock file for ProjectB will list a dependency on PackageX version 1.0.0. Pokud je však ProjectA sestaven, jeho soubor zámku bude obsahovat závislost na PackageX verze 2.0.0 a 1.0.0, jak je uvedeno v souboru zámku pro ProjectB.However, when ProjectA is built, its lock file will contain a dependency on PackageX version 2.0.0 and not 1.0.0 as listed in the lock file for ProjectB. Proto soubor zámku pro běžný projekt kódu trochu říká, že balíčky byly vyřešeny pro projekty, které jsou na ní závislé.Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it.

Zamknout rozšíření souboruLock file extensibility

Můžete řídit různá chování při obnovení pomocí souboru zámku, jak je popsáno níže:You can control various behaviors of restore with lock file as described below:

MožnostOption Možnost ekvivalentu MSBuildMSBuild equivalent option PopisDescription
--use-lock-file RestorePackagesWithLockFileRestorePackagesWithLockFile Výslovný se na použití souboru zámku.Opts into the usage of a lock file.
--locked-mode RestoreLockedModeRestoreLockedMode Zapne uzamčený režim pro obnovení.Enables locked mode for restore. To je užitečné ve scénářích CI/CD, kde chcete opakovat sestavení.This is useful in CI/CD scenarios where you want repeatable builds.
--force-evaluate RestoreForceEvaluateRestoreForceEvaluate Tato možnost je užitečná pro balíčky s plovoucí verzí definovanou v projektu.This option is useful with packages with floating version defined in the project. Ve výchozím nastavení při obnovení NuGet nebude automaticky aktualizovat verzi balíčku pro každé obnovení, pokud u této možnosti nespustíte příkaz Restore.By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with this option.
--lock-file-path NuGetLockFilePathNuGetLockFilePath Definuje vlastní umístění souboru zámku pro projekt.Defines a custom lock file location for a project. Ve výchozím nastavení NuGet podporuje packages.lock.json v kořenovém adresáři.By default, NuGet supports packages.lock.json at the root directory. Pokud máte ve stejném adresáři více projektů, NuGet podporuje soubor zámku určený pro projekt packages.<project_name>.lock.jsonIf you have multiple projects in the same directory, NuGet supports project specific lock file packages.<project_name>.lock.json