プロジェクト ファイルのパッケージ参照 (PackageReference)Package references (PackageReference) in project files

PackageReference ノードを使用するパッケージ参照では、(個別の packages.config ファイルとは異なり) NuGet の依存関係をプロジェクト ファイル内で直接管理します。Package references, using the PackageReference node, manage NuGet dependencies directly within project files (as opposed to a separate packages.config file). PackageReference を使用する場合、呼び出されても、NuGet の他の側面には影響を与えません。たとえば、(パッケージ ソースを含む) NuGet.config ファイルの設定が、「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.

PackageReference の場合、MSBuild 条件を使用し、ターゲット フレームワーク、構成、プラットフォーム、その他のグループ化ごとにパッケージ参照を選択することもできます。With PackageReference, you can also use MSBuild conditions to choose package references per target framework, configuration, platform, or other groupings. 依存関係とコンテンツ フローを細かく制御することもできます。It also allows for fine-grained control over dependencies and content flow. (詳細については、「NuGet pack and restore as MSBuild targets」(MSBuild ターゲットとしての NuGet のパックと復元) を参照してください)。(See For more details NuGet pack and restore as MSBuild targets.)

プロジェクトの種類のサポートProject type support

既定では、PackageReference は、Windows 10 Build 15063 (Creators Update) 以降を対象とする .NET Core プロジェクト、.NET Standard プロジェクト、および UWP プロジェクトに使用されます。ただし、C++ 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. .NET Framework プロジェクトは PackageReference をサポートしていますが、現在の既定は packages.config です。.NET Framework projects support PackageReference, but currently default to packages.config. PackageReference を使用するには、依存関係を packages.config からプロジェクト ファイルに "移行" してから、packages.config を削除します。To use PackageReference, migrate the dependencies from packages.config into your project file, then remove packages.config.

完全な .NET Framework を対象とする ASP.NET アプリには、PackageReference の制限されたサポートしか追加されません。ASP.NET apps targeting the full .NET Framework include only limited support for PackageReference. C++ および JavaScript のプロジェクト タイプはサポートされていません。C++ and JavaScript project types are unsupported.

PackageReference を追加するAdding a PackageReference

次の構文を使用し、プロジェクト ファイルに依存関係を追加します。Add a dependency in your project file using the following syntax:

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

依存関係のバージョンを制御するControlling dependency version

パッケージのバージョンを指定するための規則は、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>

上記の例では、3.6.0 は 3.6.0 以上のあらゆるバージョンを意味し、最も下のバージョンが優先されます。詳細は、「Package versioning」 (パッケージ バージョン) にあります。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.

PackageReference のないプロジェクトに PackageReference を使用するUsing PackageReference for a project with no PackageReferences

詳細:プロジェクトにパッケージをインストールしていない (プロジェクト ファイルに PackageReferences がなく、packages.config ファイルがない) が、プロジェクトを PackageReference スタイルで復元したい場合は、プロジェクト ファイルで Project プロパティ RestoreProjectStyle を PackageReference に設定できます。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>    

PackageReference スタイル (既存の csproj または SDK スタイルのプロジェクト) のプロジェクトを参照するとき、この設定が便利になることがあります。This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). そのようなプロジェクトが参照するパッケージを他のプロジェクトで "推移的に" 参照できます。This will enable packages that those projects refer to, to be "transitively" referenced by your project.

最新バージョンFloating Versions

最新バージョンPackageReference でサポートされています。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>

依存関係アセットを制御するControlling dependency assets

開発ハーネスとしてのみ依存関係を使用するとき、それはパッケージを使用するプロジェクトに公開しないほうが好ましい場合があります。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. このシナリオでは、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>

次のメタデータ タグは依存関係アセットを制御します。The following metadata tags control dependency assets:

タグTag 説明Description 既定値Default Value
IncludeAssetsIncludeAssets これらのアセットは使用されますThese assets will be consumed allall
ExcludeAssetsExcludeAssets これらのアセットは使用されませんThese assets will not be consumed nonenone
PrivateAssetsPrivateAssets これらのアセットは使用されますが、親プロジェクトに流れませんThese assets will be consumed but won't flow to the parent project contentfiles;analyzers;buildcontentfiles;analyzers;build

これらのタグに使用できる値は次のようになります。単独で表示する allnone を除き、複数の値はセミコロンで区切られます。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:

[値]Value 説明Description
compilecompile lib フォルダーの内容と、プロジェクトをフォルダー内のアセンブリに対してコンパイルできるかどうかのコントロールContents of the lib folder and controls whether your project can compile against the assemblies within the folder
runtimeruntime libruntimes フォルダーの内容と、これらのアセンブリがコピーされて出力ディレクトリをビルドするかどうかのコントロールContents of the lib and runtimes folder and controls whether these assemblies will be copied out to the build output directory
contentFilescontentFiles contentfiles フォルダーの内容Contents of the contentfiles folder
buildbuild build フォルダー内の .props.targets.props and .targets in the build folder
buildMultitargetingbuildMultitargeting (4.0) buildMultitargeting フォルダー内の .props.targets (フレームワーク間でのターゲット設定用)(4.0) .props and .targets in the buildMultitargeting folder, for cross-framework targeting
buildTransitivebuildTransitive (5.0 以降) buildTransitive フォルダー内の .props.targets (使用するプロジェクトに推移的にフローするアセット用)。(5.0+) .props and .targets in the buildTransitive folder, for assets that flow transitively to any consuming project. 機能に関するページをご覧ください。See the feature page.
analyzersanalyzers .NET アナライザー.NET analyzers
nativenative native フォルダーの内容Contents of the native folder
nonenone 上記のいずれも該当しない。None of the above are used.
allall 上記のすべて (none を除く)All of the above (except none)

次の例では、パッケージからのコンテンツ ファイルを除くすべてがプロジェクトによって使用され、コンテンツ ファイルとアナライザーを除くすべてが親プロジェクトに流れます。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>

buildPrivateAssets で含まれないため、targets と props は親プロジェクトに流れることに注目してください。Note that because build is not included with PrivateAssets, targets and props will flow to the parent project. たとえば、上記の参照は、AppLogger という名前の NuGet パッケージをビルドするプロジェクトで使用されます。Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger は、AppLogger を使用するプロジェクトと同様に、Contoso.Utility.UsefulStuff から targets と props を使用できます。AppLogger can consume the targets and props from Contoso.Utility.UsefulStuff, as can projects that consume AppLogger.

注意

.nuspec ファイル内で developmentDependencytrue に設定されている場合、パッケージが開発専用の依存関係としてマークされます。これにより、そのパッケージは他のパッケージに依存関係として含まれなくなります。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. PackageReference (NuGet 4.8 以降) では、このフラグは、コンパイルからコンパイル時アセットを除外することも意味します。With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. 詳しくは、「DevelopmentDependency support for PackageReference (PackageReference に対する DevelopmentDependency のサポート)」をご覧ください。For more information, see DevelopmentDependency support for PackageReference.

PackageReference 条件を追加するAdding a PackageReference condition

条件を使用し、パッケージを含めるかどうかを制御できます。条件では、あらゆる MSBuild 変数や、targets または 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. ただし、現在のところ TargetFramework 変数のみに対応しています。However, at presently, only the TargetFramework variable is supported.

たとえば、net452 と共に netstandard1.4 を対象とするが、net452 にのみ該当する依存関係があるとします。For example, say you're targeting netstandard1.4 as well as net452 but have a dependency that is applicable only for net452. その場合、パッケージを使用する netstandard1.4 プロジェクトでは、その不要な依存関係を追加することが望まれません。In this case you don't want a netstandard1.4 project that's consuming your package to add that unnecessary dependency. それを回避するために、次のように PackageReference で条件を指定します。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>

このプロジェクトでビルドされたパッケージには、net452 ターゲットのみの依存関係として Newtonsoft.json が追加されることが示されます。A package built using this project will show that Newtonsoft.Json is included as a dependency only for a net452 target:

VS2017 で PackageReference に条件を適用した結果

条件は ItemGroup レベルでも適用できます。また、条件はすべての子 PackageReference 要素に適用されます。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>

依存関係のロックLocking dependencies

"この機能を使用できるのは、NuGet 4.9 以降で、かつ Visual Studio 2017 15.9 以降を使用している場合です。 "This feature is available with NuGet 4.9 or above and with Visual Studio 2017 15.9 or above.

NuGet の復元への入力は、プロジェクト ファイルのパッケージ参照のセット (最上位レベルまたは直接の依存関係) であり、出力は推移的依存関係を含むパッケージのすべての依存関係の完全なクロージャーです。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. 入力の PackageReference リストが変更されていない場合、NuGet では常に同じパッケージの依存関係の完全なクロージャーを生成しようとします。NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. ただし、このようにすることができないシナリオがいくつかあります。However, there are some scenarios where it is unable to do so. 次に例を示します。For example:

  • <PackageReference Include="My.Sample.Lib" Version="4.*"/> などの浮動バージョンを使用する場合。When you use floating versions like <PackageReference Include="My.Sample.Lib" Version="4.*"/>. ここでの意図はパッケージの復元ごとに最新バージョンに浮動することですが、グラフを特定の最新バージョンにロックして、利用可能な場合は明示的なジェスチャに基づいて後続のバージョンに浮動させることをユーザーが求めるシナリオがあります。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.

  • PackageReference のバージョン要件と一致する新しいパッケージのバージョンが公開されている場合。A newer version of the package matching PackageReference version requirements is published. たとえば、E.g.

    • 1 日目: <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> を指定したが、NuGet リポジトリで利用可能なバージョンが 4.1.0、4.2.0 および 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. この場合、NuGet は 4.1.0 (最小に最も近いバージョン) に解決されています。In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)

    • 2 日目:バージョン 4.0.0 が公開されます。Day 2: Version 4.0.0 gets published. NuGet では完全一致が検索され、4.0.0 への解決が始められます。NuGet will now find the exact match and start resolving to 4.0.0

  • 指定したパッケージ バージョンがリポジトリから削除される場合。A given package version is removed from the repository. nuget.org ではパッケージの削除が許可されていませんが、すべてのパッケージ リポジトリがこの制約を持っているわけではありません。Though nuget.org does not allow package deletions, not all package repositories have this constraints. これにより、削除されたバージョンに解決できない場合、NuGet では最適な一致が検索されます。This results in NuGet finding the best match when it cannot resolve to the deleted version.

ロック ファイルの有効化Enabling lock file

パッケージの依存関係の完全なクロージャーを保持するために、プロジェクトに対して MSBuild プロパティ RestorePackagesWithLockFile を設定して、ロック ファイル機能にオプトインすることができます。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>    

このプロパティが設定されている場合、NuGet の復元でロック ファイル (すべてのパッケージの依存関係を一覧表示する packages.lock.json ファイル) が生成されます。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.

注意

プロジェクトのルート ディレクトリに packages.lock.json ファイルが含まれている場合、プロパティ RestorePackagesWithLockFile が設定されていない場合でも、常に復元でロック ファイルが使用されます。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. そのため、この機能にオプトインする別の方法は、プロジェクトのルート ディレクトリに空の packages.lock.json ファイルをダミーとして作成することです。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.

ロック ファイルでの restore の動作restore behavior with lock file

プロジェクトにロック ファイルが存在する場合、NuGet では restore を実行するためにこのロック ファイルが使用されます。If a lock file is present for project, NuGet uses this lock file to run restore. プロジェクト ファイル (または依存プロジェクトのファイル) で言及されたパッケージの依存関係に変更があったかどうか確認するために、NuGet で簡単なチェックが行われます。変更がなかった場合は、ロック ファイルで言及されたパッケージを単純に復元します。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. パッケージの依存関係を再評価することはありません。There is no re-evaluation of package dependencies.

NuGet によって、プロジェクト ファイルで言及したような定義された依存関係の変更が検出された場合、パッケージ グラフが再評価され、プロジェクトの新しいパッケージ クロージャを反映するためにロック ファイルが更新されます。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.

実行中にパッケージの依存関係を変更したくない CI/CD やその他のシナリオでは、lockedmodetrue に設定することでこれを実行できます。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:

dotnet.exe の場合は、次を実行します。For dotnet.exe, run:

> dotnet.exe restore --locked-mode

msbuild.exe の場合は、次を実行します。For msbuild.exe, run:

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

自分のプロジェクト ファイルにもこの条件付き MSBuild プロパティを設定できます。You may also set this conditional MSBuild property in your project file:

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

ロック モードが true である場合、復元ではロック ファイルに記載されている正確なパッケージが復元されるか、または、ロック ファイルの作成後にプロジェクトの定義されたパッケージの依存関係を更新した場合は、失敗します。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.

ロック ファイルをソース リポジトリの一部にするMake lock file part of your source repository

アプリケーションを作成する場合、目的の実行可能ファイルとプロジェクトは依存関係チェーンの最初に位置します。NuGet が復元中にこれを使用できるように、ロック ファイルをソース コード リポジトリにチェックインします。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.

ただし、当該プロジェクトが出荷しないライブラリ プロジェクトである場合や、他のプロジェクトが依存する共通コード プロジェクトである場合は、ソース コードの一部としてロック ファイルをチェックインしないでください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. ロック ファイルを保持しても問題はありませんが、共通コード プロジェクトのロックされているパッケージの依存関係は、ロック ファイル内で記載されているように、この共通コード プロジェクトに依存するプロジェクトの復元/ビルド中に使用されない場合があります。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.

例:Eg.

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

ProjectAPackageX のバージョン 2.0.0 に依存し、PackageX のバージョン 1.0.0 に依存する ProjectB も参照している場合、ProjectB のロック ファイルでは PackageX のバージョン 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. ただし、ProjectA をビルドすると、そのロック ファイルには PackageX のバージョン 2.0.0 に対する依存関係が含まれます。ProjectB のロック ファイルに記載されている 1.0.0 ではありません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. したがって、共通コード プロジェクトのロックファイルは、それが依存するプロジェクトのために解決されるパッケージに対して強い力を持っていません。Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it.

ロック ファイルの拡張機能Lock file extensibility

以下で説明するように、ロック ファイルを使用して復元のさまざまな動作を制御できます。You can control various behaviors of restore with lock file as described below:

オプションOption 対応する MSBuild オプションMSBuild equivalent option 説明Description
--use-lock-file RestorePackagesWithLockFileRestorePackagesWithLockFile ロック ファイルの使用をオプトインします。Opts into the usage of a lock file.
--locked-mode RestoreLockedModeRestoreLockedMode 復元のロック モードを有効にします。Enables locked mode for restore. これは、繰り返し可能なビルドを必要とする CI/CD のシナリオで役立ちます。This is useful in CI/CD scenarios where you want repeatable builds.
--force-evaluate RestoreForceEvaluateRestoreForceEvaluate このオプションは、プロジェクトで定義する浮動バージョンを使用するパッケージで役立ちます。This option is useful with packages with floating version defined in the project. 既定では、NuGet の復元では、このオプションを指定して復元を実行しない限り、復元ごとのパッケージ バージョンの自動更新は行われません。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 プロジェクトのカスタム ロック ファイルの場所を定義します。Defines a custom lock file location for a project. 既定では、NuGet はルート ディレクトリでの packages.lock.json をサポートします。By default, NuGet supports packages.lock.json at the root directory. 同じディレクトリ内に複数のプロジェクトがある場合、NuGet はプロジェクト固有のロック ファイル packages.<project_name>.lock.json をサポートします。If you have multiple projects in the same directory, NuGet supports project specific lock file packages.<project_name>.lock.json