DNX から .NET Core CLI への移行 (project.json)Migrating from DNX to .NET Core CLI (project.json)

概要Overview

NET Core と ASP.NET Core 1.0 の RC1 リリースでは、DNX ツールが導入されました。The RC1 release of .NET Core and ASP.NET Core 1.0 introduced DNX tooling. NET Core と ASP.NET Core 1.0 の RC2 リリースでは、DNX から .NET Core CLI に移行しました。The RC2 release of .NET Core and ASP.NET Core 1.0 moved from DNX to the .NET Core CLI.

補足情報として、DNX とは何であったのかを要約します。As a slight refresher, let's recap what DNX was about. DNX は、ランタイムであると共に、.NET Core (具体的には ASP.NET Core 1.0 アプリケーション) を構築するために使用するツールセットでした。DNX was a runtime and a toolset used to build .NET Core and, more specifically, ASP.NET Core 1.0 applications. おもに次の 3 つの部分で構成されていました。It consisted of 3 main pieces:

  1. DNVM - DNX を取得するためのインストール スクリプトDNVM - an install script for obtaining DNX
  2. DNX (Dotnet 実行ランタイム) - コードを実行するランタイムDNX (Dotnet Execution Runtime) - the runtime that executes your code
  3. DNU (Dotnet 開発者ユーティリティ) - 依存関係の管理、アプリケーションの構築および発行のためのツールDNU (Dotnet Developer Utility) - tooling for managing dependencies, building and publishing your applications

CLI の導入により、上記のすべてが単一のツールセットに含められました。With the introduction of the CLI, all of the above are now part of a single toolset. ただし、RC1 タイム フレームでは DNX が提供されていたので、ご使用のプロジェクトは DNX を使用して構築されている可能性があります。その場合は、新しい CLI ツールに移行する必要があります。However, since DNX was available in RC1 timeframe, you might have projects that were built using it that you would want to move off to the new CLI tooling.

この移行ガイドでは、DNX からと .NET Core CLI にプロジェクトを移行する方法の要点を説明します。This migration guide will cover the essentials on how to migrate projects off of DNX and onto .NET Core CLI. プロジェクトを一から .NET Core で始める場合は、このドキュメントは自由にスキップできます。If you are just starting a project on .NET Core from scratch, you can freely skip this document.

ツールの主な変更Main changes in the tooling

まずツールの全般的な変更点をいくつか説明しておく必要があります。There are some general changes in the tooling that should be outlined first.

DNVM の終了No more DNVM

DNVM (DotNet Version Manager の略) は、コンピューターに DNX をインストールするための bash/PowerShell スクリプトでした。DNVM, short for DotNet Version Manager was a bash/PowerShell script used to install a DNX on your machine. DNVM を使用することにより、ユーザーは自分で指定したフィード (または既定のフィード) から必要な DNX を容易に取得することができ、さらに、特定のセッションで $PATH にプッシュされるように特定の DNX に "アクティブ" マークを付けることができました。It helped users get the DNX they need from the feed they specified (or default ones) as well as mark a certain DNX "active", which would put it on the $PATH for the given session. これがあれば、さまざまなツールを使用できます。This would allow you to use the various tools.

DNVM の機能セットは .NET Core CLI ツールで実施された変更内容と重複することから、DNVM は使用中止になりました。DNVM was discontinued because its feature set was made redundant by changes coming in the .NET Core CLI tools.

CLI ツールは、主に次の 2 つの方法でパッケージ化されています。The CLI tools come packaged in two main ways:

  1. 特定のプラットフォームのネイティブ インストーラーNative installers for a given platform
  2. その他の状況 (CI サーバーなど) に対応するインストール スクリプトInstall script for other situations (like CI servers)

そのため、DNVM の機能のインストールは必要ありません。Given this, the DNVM install features are not needed. しかし、ランタイム選択機能はどうでしょうか?But what about the runtime selection features?

project.json 内でランタイムを参照するには、特定のバージョンのパッケージを依存関係に追加します。You reference a runtime in your project.json by adding a package of a certain version to your dependencies. この変更により、アプリケーションは新しいランタイム コンポーネントを使用できるようになります。With this change, your application will be able to use the new runtime bits. これらのコンポーネントをコンピューターに組み込む方法は、CLI の場合と同じです。サポートされているネイティブ インストーラーのいずれか、またはインストール スクリプトを使用してランタイムをインストールします。Getting these bits to your machine is the same as with the CLI: you install the runtime via one of the native installers it supports or via its install script.

種々のコマンドDifferent commands

DNX の場合、一部のコマンドについては 3 つのパート (DNX、DNU、DNVM) のいずれかから使用していました。If you were using DNX, you used some commands from one of its three parts (DNX, DNU or DNVM). CLI になって、これらのコマンドの一部は変更され、一部は使用できなくなり、一部は同じであるがセマンティクスが若干異なる状況となりました。With the CLI, some of these commands change, some are not available and some are the same but have slightly different semantics.

次の表では、DNX/DNU コマンドと、対応する CLI コマンドのマッピングを示します。The table below shows the mapping between the DNX/DNU commands and their CLI counterparts.

DNX コマンドDNX command CLI コマンドCLI command 説明Description
dnx rundnx run dotnet rundotnet run ソースからコードを実行します。Run code from source.
dnu builddnu build dotnet builddotnet build コードの IL バイナリをビルドします。Build an IL binary of your code.
dnu packdnu pack dotnet packdotnet pack コードの NuGet パッケージをパッケージ化します。Package up a NuGet package of your code.
dnx [command] ("dnx web" など)dnx [command] (for example, "dnx web") 適用なし*N/A* DNX の環境では、project.json 内の定義に従ってコマンドを実行します。In DNX world, run a command as defined in the project.json.
dnu installdnu install 適用なし*N/A* DNX の環境では、パッケージを依存関係としてインストールします。In the DNX world, install a package as a dependency.
dnu restorednu restore dotnet restoredotnet restore project.json に指定された依存関係を復元します。Restore dependencies specified in your project.json. (注記参照)(see note)
dnu publishdnu publish dotnet publishdotnet publish 展開対象のアプリケーションを 3 つの形式 (ポータブル、ネイティブ アプリ、スタンドアロン) のいずれかで発行します。Publish your application for deployment in one of the three forms (portable, portable with native and standalone).
dnu wrapdnu wrap 適用なし*N/A* DNX の環境では、csproj で project.json をラップします。In DNX world, wrap a project.json in csproj.
dnu commandsdnu commands 適用なし*N/A* DNX の環境では、インストールされたコマンドをグローバルに管理します。In DNX world, manage the globally installed commands.

(*) - これらの機能は、CLI では設計上サポートされていません。(*) - these features are not supported in the CLI by design.

サポートされていない DNX 機能DNX features that are not supported

上表に示すように、DNX 環境の機能の中には、少なくとも当面の間、CLI でサポートしないことに決定した機能があります。As the table above shows, there are features from the DNX world that we decided not to support in the CLI, at least for the time being. このセクションでは、その中で最も重要なものを取り上げ、それらのサポートを中止した論理的根拠と、必要になった場合の解決策について概説します。This section will go through the most important ones and outline the rationale behind not supporting them as well as workarounds if you do need them.

グローバル コマンドGlobal commands

DNU には、"グローバル コマンド" と呼ばれる概念が採用されています。DNU came with a concept called "global commands". これらは基本的に、NuGet パッケージとしてパッケージ化されたコンソール アプリケーションであり、指定された DNX を呼び出してアプリケーションを実行するシェル スクリプトが含まれていました。These were, essentially, console applications packaged up as NuGet packages with a shell script that would invoke the DNX you specified to run the application.

CLI では、この概念をサポートしていません。The CLI does not support this concept. しかし、使い慣れた dotnet <command> 構文を使用して呼び出し可能なプロジェクトごとのコマンドを追加する、という概念はサポートされています。It does, however, support the concept of adding per-project commands that can be invoked using the familiar dotnet <command> syntax.

依存関係のインストールInstalling dependencies

V1 の時点で、.NET Core CLI ツールは、依存関係をインストールするための install コマンドを備えていません。As of v1, the .NET Core CLI tools don't have an install command for installing dependencies. NuGet からパッケージをインストールするには、該当するパッケージを依存関係として project.json ファイルに追加し、dotnet restore を実行する必要があります (注記参照)。In order to install a package from NuGet, you would need to add it as a dependency to your project.json file and then run dotnet restore (see note).

コードの実行Running your code

コードを実行する方法は、主に 2 つあります。There are two main ways to run your code. 1 つは、dotnet run を使用してソースから実行する方法です。One is from source, with dotnet run. この方法では、dnx run の場合とは異なり、メモリ内のコンパイルを行いません。Unlike dnx run, this will not do any in-memory compilation. dotnet build を実際に呼び出すことで、コードをビルドし、ビルドされたバイナリを実行します。It will actually invoke dotnet build to build your code and then run the built binary.

もう 1 つは、dotnet 自体を使用してコードを実行する方法です。Another way is using the dotnet itself to run your code. そのためには、アセンブリへのパス dotnet path/to/an/assembly.dll を指定します。This is done by providing a path to your assembly: dotnet path/to/an/assembly.dll.

DNX プロジェクトを .NET Core CLI に移行するMigrating your DNX project to .NET Core CLI

DNX から移行する際には、コードの操作時に新しいコマンドを使用することに加えて、重要なことが他に 3 つあります。In addition to using new commands when working with your code, there are three major things left in migrating from DNX:

  1. global.json ファイルで CLI を使用できるようにする場合は、このファイルを移行します。Migrate the global.json file if you have it to be able to use CLI.
  2. プロジェクト ファイル (project.json) 自体を CLI ツールに移行します。Migrating the project file (project.json) itself to the CLI tooling.
  3. 任意の DNX API を、対応する BCL API に移行します。Migrating off of any DNX APIs to their BCL counterparts.

global.json ファイルの変更Changing the global.json file

global.json ファイルは、RC1 プロジェクトと RC2 (またはそれ以降の) プロジェクトの両方に対して、ソリューション ファイルのように機能します。The global.json file acts like a solution file for both the RC1 and RC2 (or later) projects. CLI ツール (および Visual Studio) で RC1 とそれ以降のバージョンを区別するために、"sdk": { "version" } プロパティを使用して、RC1 のプロジェクトまたはそれ以降のプロジェクトを区別します。In order for the CLI tools (as well as Visual Studio) to differentiate between RC1 and later versions, they use the "sdk": { "version" } property to make the distinction which project is RC1 or later. global.json にこのノードがまったく存在しない場合は、最新の状態であると見なされます。If global.json doesn't have this node at all, it is assumed to be the latest.

global.json ファイルを更新するには、プロパティを削除するか、使用するツールの正確なバージョンをプロパティに設定します (次の例では、1.0.0-preview2-003121)。In order to update the global.json file, either remove the property or set it to the exact version of the tools that you wish to use, in this case 1.0.0-preview2-003121:

{
    "sdk": {
        "version": "1.0.0-preview2-003121"
    }
}

プロジェクト ファイルの移行Migrating the project file

CLI と DNX は両方とも、project.json ファイルに基づいた同じ基本プロジェクト システムを使用しています。The CLI and DNX both use the same basic project system based on project.json file. プロジェクト ファイルの構文とセマンティクスはほぼ同じですが、シナリオに基づく多少の違いがあります。The syntax and the semantics of the project file are pretty much the same, with small differences based on the scenarios. スキーマの変更もあります。内容はスキーマ ファイルを参照してください。There are also some changes to the schema which you can see in the schema file.

コンソール アプリケーションを作成する場合は、プロジェクト ファイルに次のスニペットを追加する必要があります。If you are building a console application, you need to add the following snippet to your project file:

"buildOptions": {
    "emitEntryPoint": true
}

このスニペットは、アプリケーションのエントリ ポイントを出力するように dotnet build に指示し、コードが効果的に実行されるようにします。This instructs dotnet build to emit an entry point for your application, effectively making your code runnable. クラス ライブラリを作成する場合、上記のセクションは省略します。If you are building a class library, simply omit the above section. 当然ながら、上記のスニペットを project.json ファイルに追加したら、静的なエントリ ポイントを追加する必要があります。Of course, once you add the above snippet to your project.json file, you need to add a static entry point. DNX を移行すると、DNX によって提供されていた DI サービスは利用できなくなります。したがって、static void Main() のように基本的な .NET のエントリ ポイントとする必要があります。With the move off DNX, the DI services it provided are no longer available and thus this needs to be a basic .NET entry point: static void Main().

project.json に "コマンド" セクションがある場合は、それを削除することができます。If you have a "commands" section in your project.json, you can remove it. Entity Framework CLI コマンドなど、DNU コマンドとして存在していたコマンドの一部は、プロジェクトごとの拡張機能となるように CLI に移植されます。Some of the commands that used to exist as DNU commands, such as Entity Framework CLI commands, are being ported to be per-project extensions to the CLI. プロジェクトで使用する独自のコマンドをビルドした場合は、それらのコマンドを CLI の拡張機能に置き換える必要があります。If you built your own commands that you are using in your projects, you need to replace them with CLI extensions. この場合、project.json 内の commands ノードを tools ノードに置き換え、ツールの依存関係を一覧する必要があります。In this case, the commands node in project.json needs to be replaced by the tools node and it needs to list the tools dependencies.

これらの処理が完了したら、アプリにどのような種類の移植性を持たせるかを決める必要があります。After these things are done, you need to decide which type of portability you wish for you app. .NET Core では、幅広い移植性オプションを用意し、その中から選択できるようにすることに力を注ぎました。With .NET Core, we have invested into providing a spectrum of portability options that you can choose from. たとえば、完全に移植可能なアプリケーションが必要な場合もあれば、自己完結型 アプリケーションが必要な場合もあります。For instance, you may want to have a fully portable application or you may want to have a self-contained application. 移植可能なアプリケーションの方は .NET Framework アプリケーションの動作によく似ています。対象のコンピューター上でアプリケーションを実行するには共有コンポーネント (.NET Core) が必要です。The portable application option is more like .NET Framework applications work: it needs a shared component to execute it on the target machine (.NET Core). 自己完結型アプリケーションの場合は、.NET Core を対象のコンピューターにインストールする必要はありませんが、サポートする OS ごとにアプリケーションを 1 つずつ作成する必要があります。The self-contained application doesn't require .NET Core to be installed on the target, but you have to produce one application for each OS you wish to support. このような移植性の種類と詳細情報については、アプリケーションの移植性の種類に関するページを参照してください。These portability types and more are discussed in the application portability type document.

目的の移植性の種類に対して呼び出しを行ったら、対象となるフレームワークを変更する必要があります。Once you make a call on what type of portability you want, you need to change your targeted framework(s). .NET Core 用のアプリケーションを作成していた場合、対象となるフレームワークとして dnxcore50 を使用していた可能性が最も高くなります。If you were writing applications for .NET Core, you were most likely using dnxcore50 as your targeted framework. CLI の場合、新しい .NET Standard によってもたらされた変更点があるので、フレームワークを次のいずれかに設定する必要があります。With the CLI and the changes that the new .NET Standard brought, the framework needs to be one of the following:

  1. netcoreapp1.0 - .NET Core でアプリケーションを作成する場合 (ASP.NET Core アプリケーションを含む)- if you are writing applications on .NET Core (including ASP.NET Core applications)
  2. netstandard1.6 - .NET Core 用のクラス ライブラリを作成する場合- if you are writing class libraries for .NET Core

その他の dnx の対象 (dnx451 など) を使用する場合も、それらを変更する必要があります。If you are using other dnx targets, like dnx451 you will need to change those as well. dnx451 は、net451 に変更する必要があります。should be changed to net451. 詳細については、「.NET Standard」のトピックをご覧ください。Please refer to the .NET Standard topic for more information.

これで、project.json は、ほぼ準備ができました。Your project.json is now mostly ready. 特に ASP.NET Core の依存関係を使用している場合は、依存関係の一覧を確認し、依存関係を新しいバージョンに更新する必要があります。You need to go through your dependencies list and update the dependencies to their newer versions, especially if you are using ASP.NET Core dependencies. BCL API 用に個別のパッケージを使用していた場合は、アプリケーションの移植性の種類に関するページの説明に従って、ランタイム パッケージを使用することができます。If you were using separate packages for BCL APIs, you can use the runtime package as explained in the application portability type document.

準備ができたら、dotnet restore を使用して復元を試みることができます (注記参照)。Once you are ready, you can try restoring with dotnet restore (see note). 依存関係のバージョンによっては、上記の対象となるフレームワークのいずれかの依存関係を NuGet が解決できない場合にエラーが発生する可能性があります。Depending on the version of your dependencies, you may encounter errors if NuGet cannot resolve the dependencies for one of the targeted frameworks above. これは "ポイント イン タイム" 問題です。時間の経過と共に、これらのフレームワークのサポートを含むパッケージが増える現象です。This is a "point-in-time" problem; as time progresses, more and more packages will include support for these frameworks. 今のところ、このエラーが発生した場合は、framework ノード内に imports ステートメントを使用して、"imports" ステートメント内のフレームワークを対象とするパッケージを復元できるという条件を NuGet に示すことができます。For now, if you run into this, you can use the imports statement within the framework node to specify to NuGet that it can restore the packages targeting the framework within the "imports" statement. この場合に返される復元エラーに含まれる情報を見れば、どのフレームワークをインポートすればよいかを特定できるはずです。The restoring errors you get in this case should provide enough information to tell you which frameworks you need to import. 情報が不足している場合、または、まだ慣れていない場合は、通常、dnxcore50portable-net45+win8imports ステートメントに指定することで、うまくいくはずです。If you are slightly lost or new to this, in general, specifying dnxcore50 and portable-net45+win8 in the imports statement should do the trick. 次の JSON スニペットに、例を示します。The JSON snippet below shows how this looks like:

    "frameworks": {
        "netcoreapp1.0": {
            "imports": ["dnxcore50", "portable-net45+win8"]
        }
    }

dotnet build を実行した場合、数がそんなに多くなくても、最終的にビルド エラーが表示されます。Running dotnet build will show any eventual build errors, though there shouldn't be too many of them. コードが構築され正常に動作したら、ランナーを使用して試してみることができます。After your code is building and running properly, you can test it out with the runner. dotnet <path-to-your-assembly> を実行し、それが実行されているのを確認してください。Execute dotnet <path-to-your-assembly> and see it run.

注意

.NET Core 2.0 SDK 以降、dotnet restore を実行する必要がなくなりました。dotnet newdotnet builddotnet run のような、復元を必要とするあらゆるコマンドによって暗黙的に実行されるためです。Starting with .NET Core 2.0 SDK, you don't have to run dotnet restore because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build and dotnet run. Azure DevOps Services の継続的インテグレーション ビルドなど、明示的な復元が合理的となる一部のシナリオや、復元の時刻を明示的に制御する必要があるビルド システムでは、引き続き有効なコマンドとなります。It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control the time at which the restore occurs.