global.json の概要

この記事は、.NET Core 3.1 SDK 以降のバージョンに適用されます: ✔️

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

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

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

.NET SDK の 2 つのコンポーネントを使用して、global.json ファイルを検索します。 各コンポーネントは、異なる場所から開始し、先祖ディレクトリを検索します。

• .NET SDK muxer は、dotnet CLI コマンドを処理します。 現在の作業ディレクトリから開始します。これは、必ずしもプロジェクト ディレクトリと同じではありません。
• .NET MSBuild プロジェクト SDK リゾルバー ビルド中にプロジェクト SDK が解決されます。 ソリューション ファイルが存在する場合は、ソリューション ファイルを含むディレクトリから開始します。 ソリューション ファイルが存在しない場合は、現在のプロジェクト ファイルを含むディレクトリから開始されます。 どちらのファイルも存在しない場合は、現在の作業ディレクトリが使用されます。

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

global.json のスキーマ

sdk

タイプ: object

選択する.NET SDK に関する情報を指定します。

version

• タイプ: string

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

このフィールド:

• 完全なバージョン番号 (10.0.100 など) が必要です。
• 10、10.0、10.0.x などのバージョン番号はサポートされていません。
• ワイルドカードはサポートされていません。
• バージョン範囲はサポートされていません。

allowPrerelease

• タイプ: boolean
• 以降利用可能: .NET Core 3.0 SDK。

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

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

• Visual Studioで not の場合、既定値は true です。
• Visual Studioしている場合は、要求されたプレリリースの状態が使用されます。 つまり、 Visual Studioのプレビュー バージョンを使用している場合、または .NET SDK オプションのプレビューを使用する (Tools>Options>Environment>Preview Features) 既定値は true です。 それ以外の場合、既定値は false です。

rollForward

• タイプ: string
• 以降利用可能: .NET Core 3.0 SDK。

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

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

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

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

^{† パッケージ ロック ファイルを使用する場合は、SDK のバージョンと依存関係グラフがロックステップに留まるよう、 rollForward を disable に設定します。 関連する問題については、「 https://github.com/dotnet/aspnetcore/issues/65061 と https://github.com/dotnet/sdk/issues/48795」を参照してください。}

paths

• 型: [string] の配列
• 以降利用可能: .NET 10 SDK。

互換性のある .NET SDK を検索するときに考慮する必要がある場所を指定します。 パスは、絶対パスでも、 global.json ファイルの場所に対する相対パスでもかまいません。 特別な値 $host$ は、実行中の dotnet 実行可能ファイルに対応する場所を表します。

これらのパスは、定義されている順序で検索され、最初に 一致する SDK が使用されます。

この機能により、システムにグローバルにインストールされていないローカル SDK インストール (リポジトリ ルートに対する SDK やカスタム フォルダーに配置された SDK など) を使用できます。

"パス" 機能は、dotnet run など、.NET SDK と連携するコマンドを使用する場合にのみ機能します。 ネイティブ apphost ランチャー (app.exe) の実行、 dotnet app.dllでの実行、 dotnet exec app.dllでの実行などのシナリオには影響しません。 "パス" 機能を使用するには、 dotnet runなどの SDK コマンドを使用する必要があります。

errorMessage

• タイプ: string
• 以降利用可能: .NET 10 SDK。

SDK リゾルバーが互換性のある .NET SDK を見つけることができない場合に表示されるカスタム エラー メッセージを指定します。

msbuild-sdks

タイプ: object

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

test

• タイプ: object

テストに関する情報を指定します。

runner

• タイプ: string
• 以降利用可能: .NET 10.0 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.*/
  }
}

Examples

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

{
  "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"
  }
}

次の例は、追加の SDK 検索パスとカスタム エラー メッセージを指定する方法を示しています。

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

次の例では、無効なバージョンが指定されています。 コマンド dotnet --info の出力には、"バージョン '10.0' は 'sdk/version' 値に対して無効です" というエラー メッセージが表示されます。

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

次の例は、テスト ランナーとして Microsoft.Testing.Platform (MTP) を指定する方法を示しています。

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

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

照合ルール

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

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

  • Visual Studioにいない場合は、プレリリース バージョンが検討されます。
  • Visual Studioしている場合は、要求されたプレリリースの状態が使用されます。 つまり、 Visual Studioのプレビュー バージョンを使用している場合、または .NET SDK オプションのプレビューを使用する (Tools>Options>Environment>Preview Features) プレリリース バージョンが考慮されます。それ以外の場合は、リリース バージョンのみが考慮されます。

• SDK のバージョンは指定していないが 値を指定している allowPrerelease ファイルが見つかった場合は、インストールされている最新の SDK バージョンが使用されます (rollForward を latestMajor に設定するのと同じ)。 最新の SDK バージョンをリリースまたはプレリリースにできるかどうかは、allowPrerelease の値によって決まります。 true は、プレリリースバージョンが考慮されることを示し、false は、リリース バージョンのみが考慮されることを示します。

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

  • rollForward 値が設定されていない場合、patch が既定の rollForward ポリシーとして使用されます。 それ以外の場合は、「rollForward」セクションで各値とその動作を確認します。
  • 「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 バージョンであっても、古いバージョンが削除されます。

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

こちらも参照ください

• プロジェクト SDK の解決方法