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 は開発:参照してくださいPackageReference の GitHub 問題します。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.
  • 移行は、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.

既知の問題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

注意

Visual Studio ができるようにするには、プロジェクトのバックアップを作成する移行を開始する前にpackages.config へのロールバック必要な場合。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. Migrator は、プロジェクトの 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 パックパッケージを作成します。Once the migration is complete, we recommend that you add a reference to the nuget.build.tasks.pack nuget package, and then use msbuild pack to create the package. 一部のシナリオで使用できますがdotnet.exe packの代わりにmsbuild packをお勧めしません。Although in some scenarios you could use dotnet.exe pack instead of msbuild pack, it is not recommended.

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

Packages.config でサポートされていた一部の側面は、PackageReference のサポートされていません。Some aspects that were supported in packages.config are not supported in PackageReference. Migrator は、分析し、このような問題を検出します。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"資産は、移行後、パッケージがインストールされている場合は使用できません。"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 PackageReference では、XDT 変換はサポートされていないと.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.