global.json の概要

[アーティクル]
07/23/2024

この記事の対象: ✔️ .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 ファイルでは、コンピューターにインストールされている 8.0 の 8.0.300 以降の機能バンドまたはパッチが選択されます。

{
  "sdk": {
    "version": "8.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 キーの有効値を次の表に示します。

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

msbuild-sdks

型: object

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

global.json 内のコメント

global.json ファイル内のコメントは、JavaScript または C# スタイルのコメントを使用した場合にサポートされています。次に例を示します。

{
   // This is a comment.
  "sdk": {
    "version": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

例

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

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

次の例は、指定したバージョン以上の、インストールされている最新バージョンを使用する方法を示しています。示されている JSON では、7.0.200 より前の SDK バージョンがすべて禁止され、7.0.200 以降のバージョン (8.0.xxx を含む) が許可されます。

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

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

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

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

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

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

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

global.json と .NET CLI

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

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

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

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

照合ルール

Note

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

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

global.json ファイルが見つからない場合、または global.json で SDK バージョンが指定されておらず、allowPrerelease 値を指定しない場合は、インストールされている最も高い SDK バージョンが使用されます (rollForward を latestMajor に設定することと同じです)。プレリリース SDK のバージョンを考慮するかどうかは、dotnet の呼び出し方法によって決まります。
- Visual Studio を使用していない場合は、プレリリースバージョンが考慮されます。
- Visual Studio を使用している場合は、要求されたプレリリース状態が使用されます。つまり、Visual Studio のプレビューバージョンを使用している場合、または [.NET SDK のプレビューを使用する] オプション ([ツール]>[オプション]>[環境]>[プレビュー機能]) を設定している場合、プレリリースバージョンが考慮され、それ以外の場合は、リリースバージョンのみが考慮されます。
SDK のバージョンは指定していないが allowPrerelease 値を指定している global.json ファイルが見つかった場合は、インストールされている最新の SDK バージョンが使用されます (rollForward を latestMajor に設定するのと同じ)。最新の SDK バージョンをリリースまたはプレリリースにできるかどうかは、allowPrerelease の値によって決まります。 true は、プレリリースバージョンが考慮されることを示し、false は、リリースバージョンのみが考慮されることを示します。
global.json ファイルが見つかり、そこで SDK バージョンが指定されている場合は、次のようになります。
- rollForward 値が設定されていない場合、latestPatch が既定の rollForward ポリシーとして使用されます。それ以外の場合は、「rollForward」セクションで各値とその動作を確認します。
- 「allowPrerelease」セクションには、プレリリースバージョンが考慮されるかどうか、allowPrerelease が設定されていない場合の既定の動作についての説明があります。

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

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

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

.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 コマンドラインツール」を参照してください。
global.json を使って .NET SDK の特定のバージョンを使い続けている場合、Visual Studio は .NET SDK のコピーを 1 つしかインストールしないことに注意してください。そのため、Visual Studio のバージョンをアップグレードすると、新しいバージョンのインストールに使用した .NET SDK の以前のバージョンが削除されます。 .NET のメジャーバージョンが異なる場合でも、以前のバージョンが削除されます。

Visual Studio によって .NET SDK のバージョンが削除されないようにするには、ダウンロードページからスタンドアロンの .NET SDK をインストールします。ただし、その場合、Visual Studio を通じてそのバージョンの .NET SDK の自動更新が行われなくなり、セキュリティの問題が発生する可能性があります。

次の方法で共有