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 キーの有効値を次の表に示します。
| 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": "7.0.100" /* This is comment 2*/
/* This is a
multiline comment.*/
}
}
例
次の例は、プレリリース バージョンを使用しない方法を示しています。
{
"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
照合ルール
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 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 コマンドライン ツール」を参照してください。global.json を使って .NET SDK の特定のバージョンを使い続けている場合、Visual Studio は .NET SDK のコピーを 1 つしかインストールしないことに注意してください。 そのため、Visual Studio のバージョンをアップグレードすると、新しいバージョンのインストールに使用した .NET SDK の以前のバージョンが削除されます。 .NET のメジャー バージョンが異なる場合でも、以前のバージョンが削除されます。
Visual Studio が .NET SDK のバージョンを削除しないようにするには、ダウンロード ページからスタンドアロンの .NET SDK をインストールする必要があります。 その場合、Visual Studio を通じてそのバージョンの .NET SDK への自動更新が行われなくなり、セキュリティ上の問題が発生する可能性があることに注意してください。
関連項目
.NET
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示