global.json の概要

この記事の対象: ✔️ .NET Core 3.1 SDK 以降のバージョン

global.json ファイルを使うと、.NET CLI コマンドを実行するときに使う .NET SDK のバージョンを定義できます。 .NET SDK バージョンの選択は、プロジェクトのターゲットであるランタイム バージョンの指定とは関係ありません。 .NET SDK のバージョンは、使われている .NET CLI のバージョンを示します。 この記事では、global.json を使用して SDK バージョンを選択する方法について説明します。

コンピューターにインストールされている最新の SDK バージョンを常に使用する場合は、global.json ファイルは必要ありません。 ただし、CI (継続的インテグレーション) シナリオでは、通常、使用される SDK バージョンに許容できる範囲を指定する必要があります。 global.json ファイルには、許容できるバージョンの範囲を指定する柔軟な方法を提供する rollForward 機能があります。 たとえば、次の global.json ファイルでは、コンピューターにインストールされている 6.0 の 6.0.300 以降の機能バンドまたはパッチが選択されます。

{
  "sdk": {
    "version": "6.0.300",
    "rollForward": "latestFeature"
  }
}

.NET SDK は、現在の作業ディレクトリ (プロジェクト ディレクトリと同じではない場合があります) 内、またはその親ディレクトリのいずれかで、global.json ファイルを探します。

SDK バージョンの代わりにランタイム バージョンを指定する方法については、「 ターゲット フレームワーク」を参照してください。

global.json のスキーマ

SDK

型: object

選択する .NET SDK についての情報を指定します。

version

  • 型: string

使用する .NET SDK のバージョンです。

このフィールドでは:

  • ワイルドカードはサポートされていません。つまり、完全なバージョン番号を指定する必要があります。
  • バージョン範囲はサポートされていません。

allowPrerelease

  • 型: boolean
  • .NET Core 3.0 SDK 以降で利用できます。

使用する SDK バージョンを選択するときに、SDK リゾルバーでプレリリース バージョンを考慮する必要があるかどうかを示します。

この値を明示的に設定しない場合、Visual Studio から実行しているかどうかによって既定値が決まります。

  • Visual Studio を使用していない場合、既定値は true になります。
  • Visual Studio を使用している場合は、要求されたプレリリース状態が使用されます。 つまり、Visual Studio のプレビュー バージョンを使用している場合、または [.NET SDK のプレビューを使用する] オプション ( [ツール]>[オプション]>[環境]>[プレビュー機能] ) を設定している場合、既定値は true です。 それ以外の場合、既定値は false です。

rollForward

  • 型: string
  • .NET Core 3.0 SDK 以降で利用できます。

SDK バージョンを選択するときに、特定の SDK バージョンがない場合のフォールバックとして、またはより新しいバージョンを使用するためのディレクティブとして使用するロールフォワード ポリシー。 バージョン は、latestMajor に設定する場合を除き、rollForward 値を使用して指定する必要があります。 既定のロールフォワード動作は、照合ルールによって決まります。

使用可能なポリシーとその動作を理解するには、x.y.znn の形式で SDK バージョンの次の定義を考慮してください。

  • x はメジャー バージョンです。
  • y はマイナー バージョンです。
  • z は機能帯です。
  • nn はパッチ バージョンです。

rollForward キーの有効値を次の表に示します。

[値] 動作
patch 指定されたバージョンを使用します。
見つからない場合は、最新のパッチ レベルにロールフォワードします。
見つからない場合は、失敗します。

この値は、以前のバージョンの SDK の従来の動作です。
feature 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。
見つからない場合は、同じメジャーまたはマイナー内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、失敗します。
minor 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。
見つからない場合は、同じメジャー バージョンまたはマイナー バージョン内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、同じメジャー内の次の上位のマイナーおよび機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、失敗します。
major 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。
見つからない場合は、同じメジャー バージョンまたはマイナー バージョン内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、同じメジャー内の次の上位のマイナーおよび機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、次の上位のメジャー、マイナー、機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。
見つからない場合は、失敗します。
latestPatch 要求されたメジャー、マイナー、および機能帯が、指定された値以上のパッチ レベルと一致する、インストールされている最新のパッチ レベルを使用します。
見つからない場合は、失敗します。
latestFeature 要求されたメジャーおよびマイナーと一致し、機能帯とパッチ レベルが指定された値以上である、インストールされているものの中で最も高い機能帯とパッチ レベルを使用します。
見つからない場合は、失敗します。
latestMinor 要求されたメジャーと一致し、マイナー、機能帯、パッチ レベルが指定された値以上である、インストールされているものの中で最も高いマイナー、機能帯、パッチ レベルを使用します。
見つからない場合は、失敗します。
latestMajor バージョンが指定された値以上である、インストールされているものの中で最も高い .NET SDK を使用します。
見つからない場合は、失敗します。
disable ロールフォワードしません。 完全一致が必要です。

msbuild-sdks

型: object

個々のプロジェクトではなく、1 か所でプロジェクト SDK バージョンを管理できます。 詳細については、「プロジェクト SDK の解決方法」を参照してください。

使用例

次の例は、プレリリース バージョンを使用しない方法を示しています。

{
  "sdk": {
    "allowPrerelease": false
  }
}

次の例は、指定したバージョン以上の、インストールされている最新バージョンを使用する方法を示しています。 この JSON では、2.2.200 より前の SDK バージョンがすべて禁止され、3.0.xxx や 3.1.xxx など、2.2.200 以降のバージョンがすべて許可されます。

{
  "sdk": {
    "version": "2.2.200",
    "rollForward": "latestMajor"
  }
}

次の例は、指定された正確なバージョンを使用する方法を示しています。

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

次の例では、特定のメジャー バージョンとマイナー バージョンでインストールされる最新の機能バンドと修正プログラムのバージョンを使用する方法を示します。 この JSON では、3.1.102 より前の SDK バージョンがすべて禁止され、3.1.103 や 3.1.200 など、3.1.102 とそれ以降の 3.1.xxx バージョンがすべて許可されます。

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestFeature"
  }
}

次の例は、特定のバージョンのインストールされている最新のパッチ バージョンを使用する方法を示しています。 この JSON では、3.1.102 より前の SDK バージョンがすべて禁止され、3.1.103 や 3.1.199 など、3.1.102 とそれ以降の 3.1.1xx バージョンがすべて許可されます。

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestPatch"
  }
}

global.json と .NET CLI

global.json ファイルで SDK のバージョンを設定するには、マシンにインストールされている SDK のバージョンを把握しておくと便利です。 その方法の詳細については、.NET が既にインストールされていることを確認する方法に関するセクションを参照してください。

.NET SDK の別のバージョンをコンピューターにインストールするには、.NET のダウンロード ページにアクセスしてください。

次の例のような dotnet new コマンドを実行することにより、新しい global.json ファイルを現在のディレクトリに作成できます。

dotnet new globaljson --sdk-version 6.0.100

照合ルール

注意

照合ルールは、すべてのインストール済み .NET のインストール済みランタイムで共通の dotnet.exe エントリ ポイントによって管理されます。 複数のランタイムがサイドバイサイドでインストールされている場合、または global.json ファイルを使用している場合は、インストールされている最も新しいバージョンの .NET ランタイムの照合ルールが使用されます。

使用する SDK のバージョンを決定するときには、次のルールが適用されます。

  • global.json ファイルが見つからない場合、または global.json で SDK のバージョンまたは allowPrerelease 値が指定されていない場合は、インストールされている最新バージョンの SDK が使用されます (rollForwardlatestMajor に設定するのと同じ)。 プレリリース SDK のバージョンを考慮するかどうかは、dotnet の呼び出し方法によって決まります。

    • Visual Studio を使用していない場合は、プレリリース バージョンが考慮されます。
    • Visual Studio を使用している場合は、要求されたプレリリース状態が使用されます。 つまり、Visual Studio のプレビュー バージョンを使用している場合、または [.NET SDK のプレビューを使用する] オプション ( [ツール]>[オプション]>[環境]>[プレビュー機能] ) を設定している場合、プレリリース バージョンが考慮され、それ以外の場合は、リリース バージョンのみが考慮されます。
  • SDK のバージョンは指定していないが allowPrerelease 値を指定している global.json ファイルが見つかった場合は、インストールされている最新の SDK バージョンが使用されます (rollForwardlatestMajor に設定するのと同じ)。 最新の SDK バージョンをリリースまたはプレリリースにできるかどうかは、allowPrerelease の値によって決まります。 true は、プレリリースバージョンが考慮されることを示し、false は、リリース バージョンのみが考慮されることを示します。

  • global.json ファイルが見つかり、そこで SDK バージョンが指定されている場合は、次のようになります。

    • rollForward 値が設定されていない場合、latestPatch が既定の rollForward ポリシーとして使用されます。 それ以外の場合は、「rollForward」セクションで各値とその動作を確認します。
    • allowPrerelease」セクションには、プレリリース バージョンが考慮されるかどうか、allowPrerelease が設定されていない場合の既定の動作についての説明があります。

ビルドの警告のトラブルシューティング

  • 次の警告は、プロジェクトがプレリリース バージョンの .NET SDK を使用してコンパイルされたことを示しています。

    .NET Core SDK のプレビュー バージョンを使用しています。 現在のプロジェクトの global.json ファイルを使用して、SDK のバージョンを定義できます。 詳しくは https://go.microsoft.com/fwlink/?linkid=869452 を参照してください。

    .NET のプレビュー バージョンを使用しています。 https://aka.ms/dotnet-core-preview を参照

    .NET SDK のバージョンには高品質であるという履歴とコミットメントがあります。 ただし、プレリリース バージョンを使用しない場合は、「allowPrerelease」セクションで使用できるさまざまな方法を確認してください。 .NET Core 3.0 以降のランタイムまたは SDK がインストールされていないマシンの場合は、global.json ファイルを作成し、使用する正確なバージョンを指定する必要があります。

  • 次の警告は、プロジェクトのターゲットが EF Core 1.0 または 1.1 であり、.NET Core 2.1 SDK 以降のバージョンと互換性がないことを示します。

    スタートアップ プロジェクト '{startupProject}' で、フレームワーク '.NETCoreApp' バージョン '{targetFrameworkVersion}' がターゲットになっています。このバージョンの Entity Framework Core .NET コマンド ライン ツールは、バージョン 2.0 以降のみをサポートします。 古いバージョンのツールの使用については、https://go.microsoft.com/fwlink/?linkid=871254 をご覧ください。

    .NET Core 2.1 SDK (バージョン 2.1.300) 以降で、dotnet ef コマンドは SDK に含まれています。 プロジェクトをコンパイルするには、.NET Core 2.0 SDK (バージョン 2.1.201) またはそれ以前のバージョンをご利用のコンピューター上にインストールし、global.json ファイルを使用して必要な SDK バージョンを定義します。 dotnet ef コマンドの詳細については、「EF Core .NET コマンドライン ツール」を参照してください。

関連項目