project.json からの .NET Core プロジェクトの移行Migrating .NET Core projects from project.json

このドキュメントでは、.NET Core プロジェクトの次の 3 つの移行シナリオについて説明します。This document covers the following three migration scenarios for .NET Core projects:

  1. 有効な最新スキーマの project.json から csproj への移行Migration from a valid latest schema of project.json to csproj
  2. DNX から csproj への移行Migration from DNX to csproj
  3. RC3 と以前の .NET Core csproj プロジェクトから最終形式への移行Migration from RC3 and previous .NET Core csproj projects to the final format

このドキュメントは、project.json を使っている、以前の .NET Core プロジェクトのみに適用されます。This document is only applicable to older .NET Core projects that use project.json. .NET Framework から .NET Core への移行には適用されません。It does not apply to migrating from .NET Framework to .NET Core.

project.json から csproj への移行Migration from project.json to csproj

project.json から .csproj への移行は、次のいずれかの方法で実行できます。Migration from project.json to .csproj can be done using one of the following methods:

いずれの方法も、同じ基本エンジンを使用してプロジェクトを移行するので、両方の結果は同じです。Both methods use the same underlying engine to migrate the projects, so the results will be the same for both. ほとんどの場合、2 つの方法のいずれかを使用して project.jsoncsproj に移行するだけで完了します。プロジェクト ファイルをさらに手動で編集する必要はありません。In most cases, using one of these two ways to migrate the project.json to csproj is the only thing that is needed, and no further manual editing of the project file is necessary. 結果の .csproj ファイルには、格納しているディレクトリ名と同じ名前が付けられます。The resulting .csproj file will be named the same as the containing directory name.

Visual StudioVisual Studio

Visual Studio 2017 または Visual Studio 2019 バージョン 16.2 以前で .xproj ファイル、または .xproj ファイルを参照するソリューション ファイルを開くと、 [一方向のアップグレード] ダイアログが表示されます。When you open an .xproj file or a solution file that references .xproj files in Visual Studio 2017 or Visual Studio 2019 version 16.2 and earlier, the One-way upgrade dialog appears. このダイアログには、移行されるプロジェクトが表示されます。The dialog displays the projects to be migrated. ソリューション ファイルを開くと、ソリューション ファイルに指定されているすべてのプロジェクトが表示されます。If you open a solution file, all the projects specified in the solution file are listed. 移行されるプロジェクトの一覧を確認し、 [OK] を選択します。Review the list of projects to be migrated and select OK.

移行されるプロジェクトの一覧が表示された [一方向のアップグレード] ダイアログ

選択したプロジェクトは、Visual Studio によって自動的に移行されます。Visual Studio migrates the selected projects automatically. すべてのプロジェクトを選択していない状態でソリューションを移行すると、同じダイアログが開き、そのソリューションの残りのプロジェクトをアップグレードすることを確認するメッセージが表示されます。When migrating a solution, if you don't choose all projects, the same dialog appears asking you to upgrade the remaining projects from that solution. プロジェクトが移行されたら、ソリューション エクスプローラー ウィンドウでプロジェクトを右クリックして、 [編集 <プロジェクト名.csproj] を選択し、そのコンテンツを表示して変更することができます。After the project is migrated, you can see and modify its contents by right-clicking the project in the Solution Explorer window and selecting Edit <project name>.csproj.

移行されたファイル (project.jsonglobal.json.xproj、およびソリューション ファイル) は Backup フォルダーに移動されます。Files that were migrated (project.json, global.json, .xproj, and solution file) are moved to a Backup folder. 移行されるソリューション ファイルは Visual Studio 2017 または Visual Studio 2019 にアップグレードされ、Visual Studio 2015 以前のバージョンではそのソリューション ファイルを開くことができなくなります。The migrated solution file is upgraded to Visual Studio 2017 or Visual Studio 2019 and you won't be able to open that solution file in Visual Studio 2015 or earlier versions. 移行レポートを含む UpgradeLog.htm というファイルも保存され、自動的に開かれます。A file named UpgradeLog.htm that contains a migration report is also saved and opened automatically.


Visual Studio 2019 バージョン 16.3 以降では、 .xproj ファイルの読み込みまたは移行はできません。In Visual Studio 2019 version 16.3 and later, you cannot load or migrate an .xproj file. また、Visual Studio 2015 では、 .xproj ファイルを移行する機能は提供されていません。Additionally, Visual Studio 2015 doesn't provide the ability to migrate an .xproj file. これらの Visual Studio バージョンのいずれかを使用している場合は、適切なバージョンの Visual Studio をインストールするか、次に説明するコマンド ライン移行ツールを使用します。If you're using one of these Visual Studio versions, either install a suitable version of Visual Studio, or use the command line migration tool that's described next.

dotnet migratedotnet migrate

コマンドラインのシナリオでは、dotnet migrate コマンドを使用できます。In the command-line scenario, you can use the dotnet migrate command. 検出されたものに応じて、プロジェクト、ソリューション、または一連のフォルダーの順に移行されます。It migrates a project, a solution, or a set of folders in that order, depending on which ones were found. プロジェクトを移行すると、プロジェクトとそのすべての依存ファイルが移行されます。When you migrate a project, the project and all its dependencies are migrated.

移行されたファイル (project.jsonglobal.json、および .xproj) は Backup フォルダーに移動されます。Files that were migrated (project.json, global.json, and .xproj) are moved to a backup folder.


Visual Studio Code を使用している場合、dotnet migrate コマンドを実行しても、tasks.json などの Visual Studio Code 固有のファイルは変更されません。If you are using Visual Studio Code, the dotnet migrate command does not modify Visual Studio Code-specific files such as tasks.json. これらのファイルは手動で変更する必要があります。These files need to be changed manually. これは、Visual Studio ではないエディターまたは統合開発環境 (IDE) を使用している場合にも該当します。This is also true if you are using an editor or Integrated Development Environment (IDE) other than Visual Studio.

project.json および .csproj 形式の比較については、「project.json プロパティと csproj プロパティの間のマッピング」を参照してください。See A mapping between project.json and csproj properties for a comparison of project.json and .csproj formats.

次のエラーが発生する場合:If you get an error:

No executable found matching command dotnet-migrate (コマンド dotnet-migrate と一致する実行可能ファイルが見つかりません)No executable found matching command dotnet-migrate

dotnet --version を実行して使用しているバージョンを確認します。Run dotnet --version to see which version you are using. dotnet migrate は、.NET Core SDK 1.0.0 で導入され、バージョン 3.0.100 で削除されました。dotnet migrate was introduced in .NET Core SDK 1.0.0 and removed in version 3.0.100. 現在のディレクトリまたは親ディレクトリに global.json ファイルがあり、それに指定されている sdk バージョンがこの範囲外である場合に、このエラーが発生します。You'll get this error if you have a global.json file in the current or parent directory, and the sdk version it specifies is outside this range.

DNX から csproj への移行Migration from DNX to csproj

.NET Core 開発にまだ DNX を使用している場合、移行プロセスは次の 2 段階で実行する必要があります。If you are still using DNX for .NET Core development, your migration process should be done in two stages:

  1. 既存の DNX 移行ガイダンスを使用して DNX から project-json 対応の CLI に移行します。Use the existing DNX migration guidance to migrate from DNX to project-json enabled CLI.
  2. 前のセクションの手順に従って、project.json から .csproj に移行します。Follow the steps from the previous section to migrate from project.json to .csproj.


Preview 1 リリースの .NET Core CLI で、DNX は公式に非推奨になりました。DNX has become officially deprecated during the Preview 1 release of the .NET Core CLI.

以前の .NET Core csproj 形式から RTM csproj への移行Migration from earlier .NET Core csproj formats to RTM csproj

.NET Core csproj 形式は、ツールの新しいプレリリース バージョンごとに変化し、進化しています。The .NET Core csproj format has been changing and evolving with each new pre-release version of the tooling. 以前のバージョンの csproj から最新バージョンにプロジェクト ファイルを移行するツールはないため、プロジェクト ファイルを手動で編集する必要があります。There is no tool that will migrate your project file from earlier versions of csproj to the latest, so you need to manually edit the project file. 実際の手順は、移行するプロジェクト ファイルのバージョンによって異なります。The actual steps depend on the version of the project file you are migrating. バージョン間で加えられた変更内容に基づいて、考慮する必要があるガイダンスの一部を次に示します。The following is some guidance to consider based on the changes that happened between versions:

  • <Project> 要素からツールのバージョン プロパティを削除します (存在する場合)。Remove the tools version property from the <Project> element, if it exists.
  • <Project> 要素から XML 名前空間 (xmlns) を削除します。Remove the XML namespace (xmlns) from the <Project> element.
  • 存在しない場合は、<Project> 要素に Sdk 属性を追加し、Microsoft.NET.Sdk または Microsoft.NET.Sdk.Web に設定します。If it doesn't exist, add the Sdk attribute to the <Project> element and set it to Microsoft.NET.Sdk or Microsoft.NET.Sdk.Web. この属性は、プロジェクトが SDK を使用することを指定するために使用します。This attribute specifies that the project uses the SDK to be used. Microsoft.NET.Sdk.Web は Web アプリに使用されます。Microsoft.NET.Sdk.Web is used for web apps.
  • プロジェクトの一番上と一番下から <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" /> および <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" /> ステートメントを削除します。Remove the <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" /> and <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" /> statements from the top and bottom of the project. これらの import ステートメントは SDK で暗黙的に指定されているので、プロジェクトに含める必要はありません。These import statements are implied by the SDK, so there is no need for them to be in the project.
  • プロジェクト内に Microsoft.NETCore.App または NETStandard.Library <PackageReference> アイテムがある場合は、削除することをお勧めします。If you have Microsoft.NETCore.App or NETStandard.Library <PackageReference> items in your project, you should remove them. これらのパッケージ参照は、SDK で暗黙的に指定されていますThese package references are implied by the SDK.
  • Microsoft.NET.Sdk <PackageReference> 要素がある場合は削除します。Remove the Microsoft.NET.Sdk <PackageReference> element, if it exists. SDK の参照は、<Project> 要素の Sdk 属性によって行われます。The SDK reference comes through the Sdk attribute on the <Project> element.
  • SDK で暗黙的に指定されている glob を削除します。Remove the globs that are implied by the SDK. プロジェクトにこれらの glob を残すと、コンパイル アイテムが重複するため、ビルド時にエラーが発生します。Leaving these globs in your project will cause an error on build because compile items will be duplicated.

これらの手順を実行すると、RTM .NET Core csproj 形式と完全に互換性のあるプロジェクトになります。After these steps your project should be fully compatible with the RTM .NET Core csproj format.

古い csproj 形式から新しい形式に移行する前と後の例については、.NET ブログの記事「Updating Visual Studio 2017 RC – .NET Core Tooling improvements」 (Visual Studio 2017 RC の更新 - .NET Core ツールの改善) を参照してください。For examples of before and after the migration from old csproj format to the new one, see the Updating Visual Studio 2017 RC – .NET Core Tooling improvements article on the .NET blog.

参照See also