使用する .NET のバージョンを選択する

  • [アーティクル]

この記事では、.NET ツール、SDK、ランタイムによって使用されるバージョン選択ポリシーについて説明します。 これらのポリシーでは、指定バージョンを使用してアプリケーションを実行することと、開発者のコンピューターとエンド ユーザーのコンピューターの両方を簡単にアップグレードすることを両立させています。 これらのポリシーでは、次のことが可能です。

  • セキュリティと信頼性の更新プログラムを含む、.NET の簡単で効率的な展開。
  • ターゲット ランタイムとは関係なく、最新のツールとコマンドを使用する。

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

このドキュメントの残りの部分では、これら 4 つのシナリオについて説明します。

SDK はインストールされている最新バージョンを使用する

SDK コマンドには dotnet new または dotnet run が含まれています。 .NET CLI の場合、どの dotnet コマンドについても SDK バージョンを選択する必要があります。 以下のような場合でも、既定でマシンにインストールされている最新の SDK が使用されます。

  • プロジェクトのターゲットが、以前のバージョンの .NET ランタイムである。
  • .NET SDK の最新バージョンがプレビュー バージョンである。

以前のバージョンの .NET ランタイムをターゲットにしていても、SDK の最新の機能と機能改善を利用できます。 同じ SDK ツールを使用して、異なるランタイム バージョンの .NET をターゲットにすることができます。

まれに、以前のバージョンの SDK を使用する必要がある場合があります。 そのバージョンは global.json ファイルで指定します。 "最新版を使用する" というポリシーは、インストールされている最新版より以前のバージョンの .NET SDK を指定するには global.json を使用することを意味します。

global.json はファイル階層のどこにでも配置できます。 CLI はプロジェクト ディレクトリから上方を検索し、最初の global.json を見つけます。 ファイル システム内のその場所によって、特定の global.json が適用されるプロジェクトを制御します。 .NET CLI は、現在の作業ディレクトリからパスを上方に移動し、global.json ファイルを繰り返し検索します。 見つかった最初の global.json ファイルによって、使用されるバージョンが指定されます。 その SDK バージョンがインストールされている場合、そのバージョンが使用されます。 global.json で指定された SDK が見つからない場合、.NET CLI では照合ルールを使用して、互換性のある SDK を選択します。何も見つからない場合は失敗します。

次の例は global.json 構文を示しています。

{
  "sdk": {
    "version": "5.0.0"
  }
}

SDK バージョンを選択するためのプロセス:

  1. dotnet は、現在の作業ディレクトリからパスを上方に逆移動し、global.json ファイルを繰り返し検索します。
  2. dotnet は見つかった最初の global.json に指定されている SDK を使用します。
  3. global.json が見つからない場合、dotnet はインストールされている最新の SDK を使用します。

SDK バージョンの選択の詳細については、「global.js の概要」記事の「照合ルール」と「rollForward」のセクションを参照してください。

ターゲット フレームワーク モニカーによりビルド時間 API を定義する

ターゲット フレームワーク モニカー (TFM) に定義されている API に対してプロジェクトをビルドします。 ターゲット フレームワークはプロジェクト ファイルで指定します。 次の例のように、プロジェクト ファイルに TargetFramework 要素を設定します。

<TargetFramework>net8.0</TargetFramework>

複数の TFM に対してプロジェクトをビルドできます。 複数のターゲット フレームワークを設定することはライブラリで一般的ですが、アプリケーションでも可能です。 TargetFrameworks プロパティ (TargetFramework の複数形) を指定します。 次の例のように、ターゲット フレームワークはセミコロンで区切られます。

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

特定の SDK でサポートされる一連のフレームワークは決まっており、同梱のランタイムのターゲット フレームワークが上限となります。 たとえば、.NET 8 SDK には .NET 8 ランタイムが含まれますが、これは net8.0 ターゲット フレームワークの実装です。 .NET 8 SDK は net7.0、net6.0、net5.0 をサポートしますが、net9.0 (以降) はサポートされません。 net9.0 用のビルドには、.NET 9 SDK をインストールします。

.NET Standard

.NET Standard は、.NET のさまざまな実装で共有される API サーフェスをターゲットにするための方法でした。 API 標準自体である .NET 5 のリリース以降では、NET と .NET Framework の両方をターゲットとする場合は .NET Standard が便利であるという 1 つのシナリオを除き、.NET Standard との関連性はほとんどありません。 .NET 5 では、すべての .NET Standard バージョンが実装されています。

詳細については、「.NET 5 と .NET Standard」を参照してください。

フレームワーク依存のアプリのロールフォワード

ソースからdotnet run、フレームワークに依存する配置からdotnet myapp.dll、またはフレームワークに依存する実行可能ファイルからmyapp.exeを使用してアプリケーションを実行する場合、dotnet実行可能ファイルはアプリケーションのホストになります。

このホストがコンピューターにインストールされている最新版のパッチを選択します。 たとえば、プロジェクト ファイルに net5.0 を指定したとき、5.0.2 がインストールされている最新の .NET ランタイムであれば、5.0.2 ランタイムが使用されます。

許容される 5.0.* バージョンが見つからない場合、新しい 5.* バージョンが使用されます。 たとえば、net5.0 を指定したとき、5.1.0 だけがインストールされている場合、アプリケーションは 5.1.0 ランタイムを利用して実行されます。 この動作は "マイナー バージョン ロールフォワード" と呼ばれます。下位バージョンも考慮されません。 許容されるランタイムがインストールされていないとき、アプリケーションは実行されません。

以下にこの動作を示す使用例をいくつか示します (ターゲットが 5.0 の場合):

  • ✔️ 5.0 が指定されています。 インストールされている最も高いパッチ バージョンは 5.0.3 です。 5.0.3 が使用されます。
  • ❌ 5.0 が指定されています。 5.0.* バージョンはインストールされていません。 インストールされている最も高いランタイムは 3.1.1 です。 エラー メッセージが表示されます。
  • ✔️ 5.0 が指定されています。 5.0.* バージョンはインストールされていません。 インストールされている最も高いランタイム バージョンは 5.1.0 です。 5.1.0 が使用されます。
  • ❌ 3.0 が指定されています。 3.x バージョンはインストールされていません。 インストールされている最も高いランタイムは 5.0.0 です。 エラー メッセージが表示されます。

マイナー バージョン ロールフォワードには、エンド ユーザーに影響を与える可能性がある副作用が 1 つあります。 以下のシナリオについて考えてみます。

  1. アプリケーションで 5.0 が必要であると指定されます。
  2. 実行すると、バージョン 5.0.* はインストールされませんが、5.1.0 はインストールされます。 バージョン 5.1.0 が使用されます。
  3. 後で、ユーザーが 5.0.3 をインストールし、もう一度アプリケーションを実行すると、5.0.3 が使用されるようになります。

バイナリ データをシリアル化するなどのシナリオでは特に、5.0.3 と 5.1.0 の動作が異なることがあります。

ロールフォワード動作を制御する

既定のロールフォワード動作をオーバーライドする前に、 .NET ランタイムの互換性のレベルを理解しておいてください。

アプリケーションのロールフォワード動作は、次の 4 つの方法で構成できます。

  1. <RollForward> プロパティを設定することによる、プロジェクトレベルの設定:

    <PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

  2. *.runtimeconfig.json ファイル。

    このファイルは、アプリケーションをコンパイルするときに生成されます。 <RollForward> プロパティがプロジェクトで設定されている場合は、rollForward 設定として *.runtimeconfig.json ファイルで再現されます。 ユーザーはこのファイルを編集して、アプリケーションの動作を変更できます。

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. dotnet コマンドの --roll-forward <value> プロパティ。

    アプリケーションの実行時に、コマンド ラインを使用してロールフォワード動作を制御できます。

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. DOTNET_ROLL_FORWARD 環境変数。

優先順位

ロールフォワード動作は、アプリの実行時に次の順序で設定されます。番号が大きい項目は、番号の小さい項目よりも優先されます。

  1. 最初に、*.runtimeconfig.json 構成ファイルが評価されます。
  2. 次に、DOTNET_ROLL_FORWARD 環境変数が考慮されて、前のチェックがオーバーライドされます。
  3. 最後に、実行中のアプリケーションに渡される --roll-forward パラメーターによって、他のすべてがオーバーライドされます。

値

ロールフォワードをどのように設定する場合でも、次のいずれかの値を使用して動作を設定します。

Value 説明
Minor 指定されない場合は既定値。
要求されたマイナー バージョンが見つからない場合は、それよりも高い最小マイナー バージョンにロール フォワードします。 要求されたマイナー バージョンが存在する場合は、LatestPatch ポリシーが使用されます。
Major 要求されたメジャー バージョンが見つからない場合は、次に利用できる中でそれよりも高いメジャー バージョンかつ最小マイナー バージョンにロール フォワードします。 要求されたメジャー バージョンが存在する場合は、Minor ポリシーが使用されます。
LatestPatch 最新のパッチ バージョンにロール フォワードします。 この値によって、マイナー バージョンのロールフォワードが無効になります。
LatestMinor 要求されたマイナー バージョンが存在する場合でも、最上位のマイナー バージョンにロール フォワードします。
LatestMajor 要求されたメジャーが存在する場合でも、最上位のメジャー バージョンで最上位のマイナー バージョンにロール フォワードします。
Disable ロールフォワードせず、指定されたバージョンにバインドされるだけです。 このポリシーは、最新のパッチにロールフォワードする機能が無効になるため、一般的な使用にはお勧めできません。 この値はテスト用にのみ推奨されます。

自己完結型の展開に選択したランタイムが含まれる

自己完結型ディストリビューションとしてアプリケーションを公開できます。 この手法を使用すると、.NET のランタイムとライブラリがアプリケーションと共にバンドルされます。 自己完結型の展開には、ランタイム環境に対する依存性がありません。 ランタイム バージョンは実行時ではなく、公開時に選択されます。

発行時に発生する ''復元'' イベントでは、特定のランタイム ファミリの最新のパッチ版が選択されます。 たとえば、dotnet publish では、.NET 5 ランタイム ファミリの最新版パッチが .NET 5.0.3 であればそれが選択されます。 ターゲット フレームワーク (インストールされているセキュリティ パッチを含む) がアプリケーションと共にパッケージ化されます。

アプリケーションに指定されている最小バージョンでは十分でない場合、エラーが発生します。 dotnet publish は (特定の major.minor バージョン ファミリ内の) 最新ランタイム パッチ バージョンにバインドします。 dotnet publish は dotnet run のロールフォワード セマンティクスをサポートしません。 パッチや自己完結型の展開の詳細については、.NET アプリケーション展開のランタイム パッチ選択に関する記事を参照してください。

自己完結型の展開では、特定のパッチ バージョンが必要になることがあります。 次の例のように、プロジェクト ファイルで最小ランタイム パッチ バージョンを (上位または下位のバージョンに) オーバーライドできます。

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

RuntimeFrameworkVersion 要素は既定のバージョン ポリシーをオーバーライドします。 自己完結型の展開の場合、RuntimeFrameworkVersion によって厳密なランタイム フレームワーク バージョンが指定されます。 フレームワーク依存アプリケーションの場合、RuntimeFrameworkVersion によって最小限必要なランタイム フレームワーク バージョンが指定されます。

関連項目