packages.config から PackageReference への移行Migrate from packages.config to PackageReference

Visual Studio 2017 バージョン 15.7 以降では、packages.config 管理形式から PackageReference 形式へのプロジェクトの移行がサポートされています。Visual Studio 2017 Version 15.7 and later supports migrating a project from the packages.config management format to the PackageReference format.

PackageReference を使用する利点Benefits of using PackageReference

  • すべてのプロジェクトの依存関係を 1 か所で管理:プロジェクト間参照やアセンブリ参照と同様に、NuGet パッケージ参照 (PackageReference ノードを使用) は、個別の packages.config ファイルを使用するのではなく、プロジェクト ファイル内で直接管理されます。Manage all project dependencies in one place: Just like project to project references and assembly references, NuGet package references (using the PackageReference node) are managed directly within project files rather than using a separate packages.config file.
  • 最上位の依存関係のすっきりしたビュー:packages.config とは異なり、PackageReference では、プロジェクトに直接インストールした NuGet パッケージのみが一覧表示されます。Uncluttered view of top-level dependencies: Unlike packages.config, PackageReference lists only those NuGet packages you directly installed in the project. その結果、NuGet パッケージ マネージャー UI とプロジェクト ファイルが下位レベルの依存関係によって乱雑になることはありません。As a result, the NuGet Package Manager UI and the project file aren't cluttered with down-level dependencies.
  • パフォーマンスの向上:PackageReference を使用する場合、(「グローバル パッケージとキャッシュ フォルダーの管理」で説明されているように) パッケージはソリューション内の packages フォルダーではなく "グローバル パッケージ" フォルダー内で管理されます。Performance improvements: When using PackageReference, packages are maintained in the global-packages folder (as described on Managing the global packages and cache folders rather than in a packages folder within the solution. その結果、PackageReference のパフォーマンスが向上し、使用するディスク領域も少なくなります。As a result, PackageReference performs faster and consumes less disk space.
  • 依存関係とコンテンツ フローのきめ細かな制御:MSBuild の既存の機能を使用して、NuGet パッケージを条件付きで参照し、ターゲット フレームワーク、構成、プラットフォーム、またはその他のピボットごとにパッケージ参照を選択できます。Fine control over dependencies and content flow: Using the existing features of MSBuild allows you to conditionally reference a NuGet package and choose package references per target framework, configuration, platform, or other pivots.
  • PackageReference はアクティブに開発中:GitHub 上の PackageReference の問題に関するページをご覧ください。PackageReference is under active development: See PackageReference issues on GitHub. packages.config の開発は現在継続されていません。packages.config is no longer under active development.

制限事項Limitations

  • NuGet PackageReference は、Visual Studio 2015 以前では使用できません。NuGet PackageReference is not available in Visual Studio 2015 and earlier. 移行されたプロジェクトは、Visual Studio 2017 以降でのみ開くことができます。Migrated projects can be opened only in Visual Studio 2017 and later.
  • C++ プロジェクトと ASP.NET プロジェクトについては、現在のところ、移行を利用できません。Migration is not currently available for C++ and ASP.NET projects.
  • 一部のパッケージは、PackageReference と完全に互換ではない場合があります。Some packages may not be fully compatible with PackageReference. 詳しくは、「パッケージの互換性の問題」をご覧ください。For more information, see package compatibility issues.

また、PackageReferences のしくみには、packages.config と比べていくつかの違いがあります。たとえば、アップグレード バージョンを制限することは、PackageReference ではサポートされていませんが、浮動小数点バージョンのサポートが追加されています。In addition, there are some differences in how PackageReferences work compared to packages.config. For example - constraining upgrade versions is not supprted by PackageReference but add support for Floating Versions.

既知の問題Known Issues

  1. 右クリックのコンテキスト メニューで Migrate packages.config to PackageReference... オプションを使用できないThe Migrate packages.config to PackageReference... option is not available in the right-click context menu

懸案事項Issue

プロジェクトを最初に開いたとき、NuGet 操作を行うまで NuGet が初期化されていない場合があります。When a project is first opened, NuGet may not have initialized until a NuGet operation is performed. これにより、packages.config または References 上の右クリックのコンテキスト メニューで、移行オプションが表示されません。This causes the migration option to not show up in the right-click context menu on packages.config or References.

回避策Workaround

次の NuGet アクションのいずれかを実行します。Perform any one of the following NuGet actions:

  • パッケージ マネージャー UI を開く - References を右クリックし、Manage NuGet Packages... を選択するOpen the Package Manager UI - Right-click on References and select Manage NuGet Packages...
  • パッケージ マネージャー コンソールを開く - Tools > NuGet Package Manager から、Package Manager Console を選択するOpen the Package Manager Console - From Tools > NuGet Package Manager, select Package Manager Console
  • NuGet 復元を実行する - ソリューション エクスプローラーのソリューション ノードを右クリックし、Restore NuGet Packages を選択するRun NuGet restore - Right-click on the solution node in the Solution Explorer and select Restore NuGet Packages
  • NuGet 復元もトリガーするプロジェクトをビルドするBuild the project which also triggers NuGet restore

これで、移行オプションを表示できるようになりました。You should now be able to see the migration option. このオプションは ASP.NET と C++ のプロジェクト タイプではサポートされておらず、表示されません。Note that this option is not supported and will not show up for ASP.NET and C++ project types.

移行の手順Migration steps

注意

移行を開始する前に、必要に応じて packages.config にロールバックできるように Visual Studio によってプロジェクトのバックアップが作成されます。Before migration begins, Visual Studio creates a backup of the project to allow you to roll back to packages.config if necessary.

  1. packages.config を使用してプロジェクトを含むソリューションを開きます。Open a solution containing project using packages.config.

  2. ソリューション エクスプローラーで、 [参照] ノードまたは packages.config ファイルを右クリックし、 [packages.config を PackageReference に移行する...] を選択します。In Solution Explorer, right-click on the References node or the packages.config file and select Migrate packages.config to PackageReference....

  3. 移行プログラムによってプロジェクトの NuGet パッケージ参照が分析され、最上位の依存関係 (直接インストールした NuGet パッケージ) と推移的依存関係 (最上位のパッケージの依存関係としてインストールされたパッケージ) への分類が試行されます。The migrator analyzes the project's NuGet package references and attempts to categorize them into Top-level dependencies (NuGet packages that you installed directly) and Transitive dependencies (packages that were installed as dependencies of top-level packages).

    注意

    PackageReference では推移的なパッケージの復元がサポートされ、依存関係が動的に解決されます。つまり、推移的依存関係を明示的にインストールする必要はありません。PackageReference supports transitive package restore and resolves dependencies dynamically, meaning that transitive dependencies need not be installed explicitly.

  4. (省略可能) パッケージに対して [最上位] オプションを選択することで、推移的依存関係として分類された NuGet パッケージを最上位の依存関係として扱うことを選択できます。(Optional) You may choose to treat a NuGet package classified as a transitive dependency as a top-level dependency by selecting the Top-Level option for the package. このオプションは、推移的にフローしないアセットを含む (buildbuildCrossTargetingcontentFiles、または analyzers フォルダー内にある) パッケージと、開発の依存関係 (developmentDependency = "true") としてマークされているパッケージに対して自動的に設定されます。This option is automatically set for packages containing assets that do not flow transitively (those in the build, buildCrossTargeting, contentFiles, or analyzers folders) and those marked as a development dependency (developmentDependency = "true").

  5. パッケージの互換性の問題」をご確認ください。Review any package compatibility issues.

  6. [OK] を選択して移行を開始します。Select OK to begin the migration.

  7. 移行の最後に、Visual Studio によって、バックアップのパス、インストールされているパッケージの一覧 (最上位の依存関係)、推移的依存関係として参照されるパッケージの一覧、移行の開始時に識別される互換性の問題の一覧に関するレポートが提供されます。At the end of the migration, Visual Studio provides a report with a path to the backup, the list of installed packages (top-level dependencies), a list of packages referenced as transitive dependencies, and a list of compatibility issues identified at the start of migration. レポートがバックアップ フォルダーに保存されます。The report is saved to the backup folder.

  8. ソリューションがビルドされ、実行されることを確認します。Validate that the solution builds and runs. 問題が発生した場合は、問題を GitHub に報告します。If you encounter problems, file an issue on GitHub.

packages.config にロールバックする方法How to roll back to packages.config

  1. 移行されたプロジェクトを閉じます。Close the migrated project.

  2. プロジェクト ファイルと packages.config をバックアップ (通常は <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) からプロジェクト フォルダーにコピーします。Copy the project file and packages.config from the backup (typically <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) to the project folder. obj フォルダーがプロジェクトのルート ディレクトリに存在する場合は、これを削除します。Delete the obj folder if it exists in the project root directory.

  3. プロジェクトを開きます。Open the project.

  4. [ツール] > [NuGet パッケージ マネージャー] > [パッケージ マネージャー コンソール] メニュー コマンドを使用して [パッケージ マネージャー コンソール] を開きます。Open the Package Manager Console using the Tools > NuGet Package Manager > Package Manager Console menu command.

  5. コンソール内で、次のコマンドを実行します。Run the following command in the Console:

    update-package -reinstall
    

移行後にパッケージを作成するCreate a package after migration

移行が完了したら nuget.build.tasks.pack nuget パッケージへの参照を追加し、msbuild -t:pack を使用してパッケージを作成することをお勧めします。Once the migration is complete, we recommend that you add a reference to the nuget.build.tasks.pack nuget package, and then use msbuild -t:pack to create the package. msbuild -t:pack の代わりに dotnet.exe pack を使用できるシナリオもありますが、推奨されません。Although in some scenarios you could use dotnet.exe pack instead of msbuild -t:pack, it is not recommended.

パッケージの互換性の問題Package compatibility issues

packages.config でサポートされていたいくつかの機能は、PackageReference ではサポートされていません。Some aspects that were supported in packages.config are not supported in PackageReference. 移行プログラムでは、このような問題が分析および検出されます。The migrator analyzes and detects such issues. 以下の問題が 1 つ以上あるパッケージは、移行後に期待どおりに動作しない可能性があります。Any package that has one or more of the following issues may not behave as expected after the migration.

移行後にパッケージをインストールするときに、"install. ps1" スクリプトが無視される"install.ps1" scripts are ignored when the package is installed after the migration

説明Description PackageReference では、パッケージをインストールまたはアンインストールするときに、install.ps1 および uninstall.ps1 PowerShell スクリプトは実行されません。With PackageReference, install.ps1 and uninstall.ps1 PowerShell scripts are not executed while installing or uninstalling a package.
潜在的な影響Potential impact これらのスクリプトに依存して移行先プロジェクト内の一部の動作を構成するパッケージは、期待どおりに動作しないことがあります。Packages that depend on these scripts to configure some behavior in the destination project might not work as expected.

移行後にパッケージをインストールするときに、"コンテンツ" アセットを使用できない"content" assets are not available when the package is installed after the migration

説明Description パッケージの content フォルダー内のアセットは、PackageReference ではサポートされず、無視されます。Assets in a package's content folder are not supported with PackageReference and are ignored. PackageReference では、推移的なサポートと共有コンテンツを向上させるために contentFiles のサポートが追加されています。PackageReference adds support for contentFiles to have better transitive support and shared content.
潜在的な影響Potential impact content 内のアセットはプロジェクトにコピーされず、これらのアセットの存在に依存するプロジェクト コードにはリファクタリングが必要です。Assets in content are not copied into the project and project code that depends on the presence of those assets requires refactoring.

アップグレード後にパッケージをインストールするときに XDT 変換が適用されないXDT transforms are not applied when the package is installed after the upgrade

説明Description XDT 変換は PackageReference ではサポートされず、パッケージをインストールまたはアンインストールするときに .xdt ファイルは無視されます。XDT transforms are not supported with PackageReference and .xdt files are ignored when installing or uninstalling a package.
潜在的な影響Potential impact XDT 変換は、プロジェクトの XML ファイル (通常は web.config.install.xdtweb.config.uninstall.xdt) には適用されません。つまり、パッケージをインストールまたはアンインストールしても、プロジェクトの web.config ファイルは更新されません。XDT transforms are not applied to any project XML files, most commonly, web.config.install.xdt and web.config.uninstall.xdt, which means the project'sweb.config file is not updated when the package is installed or uninstalled.

移行後にパッケージをインストールするときに、lib ルート内のアセンブリが無視されるAssemblies in the lib root are ignored when the package is installed after the migration

説明Description PackageReference では、ターゲット フレームワーク固有のサブフォルダーがない lib フォルダーのルートにあるアセンブリは無視されます。With PackageReference, assemblies present at the root of lib folder without a target framework specific sub-folder are ignored. NuGet では、プロジェクトのターゲット フレームワークに対応するターゲット フレームワーク モニカー (TFM) に一致するサブフォルダーが検索され、一致するアセンブリがプロジェクトにインストールされます。NuGet looks for a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework and installs the matching assemblies into the project.
潜在的な影響Potential impact プロジェクトのターゲット フレームワークに対応するターゲット フレームワーク モニカー (TFM) と一致するサブフォルダーがないパッケージは、移行後に期待どおりに動作しない場合や、移行中にインストールが失敗する場合がありますPackages that do not have a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework may not behave as expected after the transition or fail installation during the migration

見つかった問題のFound an issue? 報告Report it!

移行のエクスペリエンスに問題が発生した場合は、NuGet GitHub リポジトリに問題を報告してください。If you run into a problem with the migration experience, please file an issue on the NuGet GitHub repository.