使用する .NET Core のバージョンを選択するSelect the .NET Core version to use

この記事では、.NET Core ツール、SDK、ランタイムによって使用されるバージョン選択ポリシーについて説明します。This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. これらのポリシーでは、指定バージョンを使用してアプリケーションを実行することと、開発者のコンピューターとエンド ユーザーのコンピューターの両方を簡単にアップグレードすることを両立させています。These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. これらのポリシーによって次のアクションが実行されます。These policies perform the following actions:

  • セキュリティと信頼性の更新プログラムを含め、.NET Core を簡単かつ効率的に展開する。Easy and efficient deployment of .NET Core, including security and reliability updates.
  • ターゲット ランタイムとは関係なく、最新のツールとコマンドを使用する。Use the latest tools and commands independent of target runtime.

バージョンが次のように選択されます。Version selection occurs:

このドキュメントの残りの部分では、これら 4 つのシナリオについて説明します。The rest of this document examines those four scenarios.

SDK はインストールされている最新バージョンを使用するThe SDK uses the latest installed version

SDK コマンドには dotnet new または dotnet run が含まれています。SDK commands include dotnet new and dotnet run. .NET Core CLI の場合、どの dotnet コマンドに対しても SDK バージョンを選択する必要があります。The .NET Core CLI must choose an SDK version for every dotnet command. 以下のような場合でも、既定でマシンにインストールされている最新の SDK が使用されます。It uses the latest SDK installed on the machine by default, even if:

  • このプロジェクトは、.NET Core ランタイムの以前のバージョンをターゲットとしています。The project targets an earlier version of the .NET Core runtime.
  • .NET Core SDK の最新バージョンはプレビュー バージョンです。The latest version of the .NET Core SDK is a preview version.

以前のバージョンの .NET Core ランタイムをターゲットにしているとき、SDK の最新の機能と機能改善を活用できます。You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. すべてのプロジェクトに同じ SDK ツールを使用し、異なるプロジェクトで複数のランタイム バージョンの .NET Core をターゲットにできます。You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

まれに、以前のバージョンの SDK を使用する必要がある場合があります。On rare occasions, you may need to use an earlier version of the SDK. そのバージョンは global.json ファイルで指定します。You specify that version in a global.json file. "最新版を使用する" というポリシーは、インストールされている最新版より以前のバージョンの .NET Core SDK を指定するには global.json を使用することを意味します。The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

global.json はファイル階層のどこにでも配置できます。global.json can be placed anywhere in the file hierarchy. CLI はプロジェクト ディレクトリから上方を検索し、最初の global.json を見つけます。The CLI searches upward from the project directory for the first global.json it finds. ファイル システム内のその場所によって、特定の global.json が適用されるプロジェクトを制御します。You control which projects a given global.json applies to by its place in the file system. .NET CLI は、現在の作業ディレクトリからパスを上方に移動し、global.json ファイルを繰り返し検索します。The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. 見つかった最初の global.json ファイルによって、使用されるバージョンが指定されます。The first global.json file found specifies the version used. そのバージョンがインストールされている場合、そのバージョンが使用されます。If that version is installed, that version is used. global.json に指定されている SDK が見つからない場合、.NET CLI はインストールされている最新の SDK にロールフォワードします。If the SDK specified in the global.json is not found, the .NET CLI rolls forward to the latest SDK installed. ロール フォワードは、global.json ファイルが見つからないとき、これは既定の動作と同じになります。Roll-forward is the same as the default behavior, when no global.json file is found.

次の例は global.json 構文を示しています。The following example shows the global.json syntax:

{
  "sdk": {
    "version": "2.0.0"
  }
}

SDK バージョンを選択するためのプロセス:The process for selecting an SDK version is:

  1. dotnet は、現在の作業ディレクトリからパスを上方に逆移動し、global.json ファイルを繰り返し検索します。dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet は見つかった最初の global.json に指定されている SDK を使用します。dotnet uses the SDK specified in the first global.json found.
  3. global.json が見つからない場合、dotnet はインストールされている最新の SDK を使用します。dotnet uses the latest installed SDK if no global.json is found.

SDK バージョンの選択に関する詳細は、global.json に関する記事の「照合ルール」にあります。You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

ターゲット フレームワーク モニカーによりビルド時間 API を定義するTarget Framework Monikers define build time APIs

ターゲット フレームワーク モニカー (TFM) に定義されている API に対してプロジェクトをビルドします。You build your project against APIs defined in a Target Framework Moniker (TFM). ターゲット フレームワークはプロジェクト ファイルで指定します。You specify the target framework in the project file. 次の例のように、プロジェクト ファイルに TargetFramework 要素を設定します。Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp2.0</TargetFramework>

複数の TFM に対してプロジェクトをビルドできます。You may build your project against multiple TFMs. 複数のターゲット フレームワークを設定することはライブラリで一般的ですが、アプリケーションでも可能です。Setting multiple target frameworks is more common for libraries but can be done with applications as well. TargetFrameworks プロパティ (TargetFramework の複数形) を指定します。You specify a TargetFrameworks property (plural of TargetFramework). 次の例のように、ターゲット フレームワークはセミコロンで区切られます。The target frameworks are semicolon-delimited as shown in the following example:

<TargetFrameworks>netcoreapp2.0;net47</TargetFrameworks>

特定の SDK でサポートされる一連のフレームワークは決まっており、同梱のランタイムのターゲット フレームワークが上限となります。A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. たとえば、.NET Core 2.0 SDK には .NET Core 2.0 ランタイムが含まれますが、これは netcoreapp2.0 ターゲット フレームワークの実装です。For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the netcoreapp2.0 target framework. .NET Core 2.0 SDK は netcoreapp1.0netcoreapp1.1netcoreapp2.0 をサポートしますが、netcoreapp2.1 (以降) はサポートされません。The .NET Core 2.0 SDK supports netcoreapp1.0, netcoreapp1.1, and netcoreapp2.0 but not netcoreapp2.1 (or higher). netcoreapp2.1 のビルドには、.NET Core 2.1 SDK をインストールします。You install the .NET Core 2.1 SDK to build for netcoreapp2.1.

.NET Standard ターゲット フレームワークの上限も、SDK に付属するランタイムのターゲット フレームワークになります。.NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. .NET Core 2.0 SDK の上限は netstandard2.0 になります。The .NET Core 2.0 SDK is capped to netstandard2.0.

フレームワーク依存のアプリをロールフォワードするFramework-dependent apps roll forward

dotnet myapp.dll が存在するフレームワークに依存するデプロイdotnet run を使用する、または myapp.exe が存在するフレームワークに依存する実行可能ファイルを使用して、ソースからアプリケーションを実行した場合、dotnet 実行可能ファイルがアプリケーションのホストになります。When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

このホストがコンピューターにインストールされている最新版のパッチを選択します。The host chooses the latest patch version installed on the machine. たとえば、プロジェクト ファイルに netcoreapp2.0 を指定したとき、2.0.4 がインストールされている最新の .NET ランタイムであれば、2.0.4 ランタイムが使用されます。For example, if you specified netcoreapp2.0 in your project file, and 2.0.4 is the latest .NET runtime installed, the 2.0.4 runtime is used.

許容される 2.0.* バージョンが見つからない場合、新しい 2.* バージョンが使用されます。If no acceptable 2.0.* version is found, a new 2.* version is used. たとえば、netcoreapp2.0 を指定したとき、2.1.0 だけがインストールされている場合、アプリケーションは 2.1.0 ランタイムを利用して実行されます。For example, if you specified netcoreapp2.0 and only 2.1.0 is installed, the application runs using the 2.1.0 runtime. この動作は "マイナー バージョン ロールフォワード" と呼ばれます。This behavior is referred to as "minor version roll-forward." 下位バージョンも考慮されません。Lower versions also won't be considered. 許容されるランタイムがインストールされていないとき、アプリケーションは実行されません。When no acceptable runtime is installed, the application won't run.

以下にこの動作を示す使用例をいくつか示します (ターゲットが 2.0 の場合):A few usage examples demonstrate the behavior, if you target 2.0:

  • 2.0 が指定されます。2.0 is specified. インストールされているパッチ バージョンのうち、一番上が 2.0.5 です。2.0.5 is the highest patch version installed. 2.0.5 が使用されます。2.0.5 is used.
  • 2.0 が指定されます。2.0 is specified. 2.0.* バージョンはインストールされていません。No 2.0.* versions are installed. インストールされているランタイムのうち、一番上が 1.1.1 です。1.1.1 is the highest runtime installed. エラー メッセージが表示されます。An error message is displayed.
  • 2.0 が指定されます。2.0 is specified. 2.0.* バージョンはインストールされていません。No 2.0.* versions are installed. インストールされている 2.x ランタイム バージョンのうち、一番上が 2.2.2 です。2.2.2 is the highest 2.x runtime version installed. 2.2.2 が使用されます。2.2.2 is used.
  • 2.0 が指定されます。2.0 is specified. 2.x バージョンはインストールされていません。No 2.x versions are installed. 3.0.0 がインストールされます。3.0.0 is installed. エラー メッセージが表示されます。An error message is displayed.

マイナー バージョン ロールフォワードには、エンド ユーザーに影響を与える可能性がある副作用が 1 つあります。Minor version roll-forward has one side-effect that may affect end users. 次のシナリオについて検討してください。Consider the following scenario:

  1. アプリケーションで 2.0 が必要であると指定されます。The application specifies that 2.0 is required.
  2. 実行すると、バージョン 2.0.* はインストールされませんが、2.2.2 がインストールされます。When run, version 2.0.* is not installed, however, 2.2.2 is. バージョン 2.2.2 が使用されます。Version 2.2.2 will be used.
  3. 後で、ユーザーが 2.0.5 をインストールし、もう一度アプリケーションを実行すると、2.0.5 が使用されるようになりました。Later, the user installs 2.0.5 and runs the application again, 2.0.5 will now be used.

バイナリ データをシリアル化するなどのシナリオでは特に、2.0.5 と 2.2.2 の動作が異なることがあります。It's possible that 2.0.5 and 2.2.2 behave differently, particularly for scenarios like serializing binary data.

自己完結型の展開に選択したランタイムが含まれるSelf-contained deployments include the selected runtime

自己完結型ディストリビューションとしてアプリケーションを公開できます。You can publish an application as a self-contained distribution. この手法では、.NET Core のランタイムとライブラリがアプリケーションと共にバンドルされます。This approach bundles the .NET Core runtime and libraries with your application. 自己完結型の展開には、ランタイム環境に対する依存性がありません。Self-contained deployments don't have a dependency on runtime environments. ランタイム バージョンは実行時ではなく、公開時に選択されます。Runtime version selection occurs at publishing time, not run time.

公開プロセスでは、特定のランタイム ファミリの最新版パッチが選択されます。The publishing process selects the latest patch version of the given runtime family. たとえば、dotnet publish では、.NET Core 2.0 ランタイム ファミリの最新版パッチが .NET Core 2.0.4 であればそれが選択されます。For example, dotnet publish will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. ターゲット フレームワーク (インストールされているセキュリティ パッチを含む) がアプリケーションと共にパッケージ化されます。The target framework (including the latest installed security patches) is packaged with the application.

アプリケーションに指定されている最小バージョンで十分ではない場合、エラーとなります。It's an error if the minimum version specified for an application isn't satisfied. dotnet publish は (特定の major.minor バージョン ファミリ内の) 最新ランタイム パッチ バージョンにバインドします。dotnet publish binds to the latest runtime patch version (within a given major.minor version family). dotnet publishdotnet run のロールフォワード セマンティクスをサポートしません。dotnet publish doesn't support the roll-forward semantics of dotnet run. パッチや自己完結型の展開の詳細については、.NET Core アプリケーション展開のランタイム パッチ選択に関する記事を参照してください。For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

自己完結型の展開では、特定のパッチ バージョンが必要になることがあります。Self-contained deployments may require a specific patch version. 次の例のように、プロジェクト ファイルで最小ランタイム パッチ バージョンを (上位または下位のバージョンに) オーバーライドできます。You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>

RuntimeFrameworkVersion 要素は既定のバージョン ポリシーをオーバーライドします。The RuntimeFrameworkVersion element overrides the default version policy. 自己完結型の展開の場合、RuntimeFrameworkVersion によって厳密なランタイム フレームワーク バージョンが指定されます。For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. フレームワーク依存アプリケーションの場合、RuntimeFrameworkVersion によって最小限必要なランタイム フレームワーク バージョンが指定されます。For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.