global.json の概要global.json overview

この記事の対象: ✔️ .NET Core 2.0 SDK 以降のバージョンThis article applies to: ✔️ .NET Core 2.0 SDK and later versions

global.json ファイルを使うと、.NET Core CLI コマンドを実行するときに使う .NET Core SDK のバージョンを定義できます。The global.json file allows you to define which .NET Core SDK version is used when you run .NET Core CLI commands. .NET Core SDK の選択は、プロジェクトのターゲットであるランタイムの指定とは関係ありません。Selecting the .NET Core SDK is independent from specifying the runtime your project targets. .NET Core SDK のバージョンは、使われている .NET Core CLI のバージョンを示します。The .NET Core SDK version indicates which versions of the .NET Core CLI is used.

通常は、最新バージョンの SDK ツールを使うので、global.json ファイルは必要ありません。In general, you want to use the latest version of the SDK tools, so no global.json file is needed. 一部の高度なシナリオでは、SDK ツールのバージョンを管理する必要がある場合があります。この記事では、この方法について説明します。In some advanced scenarios, you might want to control the version of the SDK tools, and this article explains how to do this.

代わりにランタイムを指定する方法について詳しくは、「ターゲット フレームワーク」をご覧ください。For more information about specifying the runtime instead, see Target frameworks.

.NET Core SDK は、現在の作業ディレクトリ (プロジェクト ディレクトリと同じではない場合があります) 内、またはその親ディレクトリのいずれかで、global.json ファイルを探します。.NET Core SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

global.json のスキーマglobal.json schema

SDKsdk

型: objectType: object

選択する .NET Core SDK についての情報を指定します。Specifies information about the .NET Core SDK to select.

versionversion

  • 型: stringType: string

  • .NET Core 1.0 SDK 以降で利用できます。Available since: .NET Core 1.0 SDK.

使用する .NET Core SDK のバージョンです。The version of the .NET Core SDK to use.

このフィールドでは:This field:

  • ワイルドカードはサポートされていません。つまり、完全なバージョン番号を指定する必要があります。Doesn't have wildcard support, that is, the full version number has to be specified.
  • バージョン範囲はサポートされていません。Doesn't support version ranges.

allowPrereleaseallowPrerelease

  • 型: booleanType: boolean

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

使用する SDK バージョンを選択するときに、SDK リゾルバーでプレリリース バージョンを考慮する必要があるかどうかを示します。Indicates whether the SDK resolver should consider prerelease versions when selecting the SDK version to use.

この値を明示的に設定しない場合、Visual Studio から実行しているかどうかによって既定値が決まります。If you don't set this value explicitly, the default value depends on whether you're running from Visual Studio:

  • Visual Studio を使用していない場合、既定値は true になります。If you're not in Visual Studio, the default value is true.
  • Visual Studio を使用している場合は、要求されたプレリリース状態が使用されます。If you are in Visual Studio, it uses the prerelease status requested. つまり、Visual Studio のプレビュー バージョンを使用している場合、または ( [ツール] > [オプション] > [環境] > [プレビュー機能] で) [.NET Core SDK のプレビューを使用する] オプションを設定している場合、既定値は true で、それ以外の場合は、false です。That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), the default value is true; otherwise, false.

rollForwardrollForward

  • 型: stringType: string

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

SDK バージョンを選択するときに、特定の SDK バージョンがない場合のフォールバックとして、またはより新しいバージョンを使用するためのディレクティブとして使用するロールフォワード ポリシー。The roll-forward policy to use when selecting an SDK version, either as a fallback when a specific SDK version is missing or as a directive to use a higher version. バージョン は、latestMajor に設定する場合を除き、rollForward 値を使用して指定する必要があります。A version must be specified with a rollForward value, unless you're setting it to latestMajor.

使用可能なポリシーとその動作を理解するには、x.y.znn の形式で SDK バージョンの次の定義を考慮してください。To understand the available policies and their behavior, consider the following definitions for an SDK version in the format x.y.znn:

  • x はメジャー バージョンです。x is the major version.
  • y はマイナー バージョンです。y is the minor version.
  • z は機能帯です。z is the feature band.
  • nn はパッチ バージョンです。nn is the patch version.

rollForward キーの有効値を次の表に示します。The following table shows the possible values for the rollForward key:

[値]Value 動作Behavior
patch 指定されたバージョンを使用します。Uses the specified version.
見つからない場合は、最新のパッチ レベルにロールフォワードします。If not found, rolls forward to the latest patch level.
見つからない場合は、失敗します。If not found, fails.

この値は、以前のバージョンの SDK の従来の動作です。This value is the legacy behavior from the earlier versions of the SDK.
feature 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。Uses the latest patch level for the specified major, minor, and feature band.
見つからない場合は、同じメジャーまたはマイナー内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher feature band within the same major/minor and uses the latest patch level for that feature band.
見つからない場合は、失敗します。If not found, fails.
minor 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。Uses the latest patch level for the specified major, minor, and feature band.
見つからない場合は、同じメジャー バージョンまたはマイナー バージョン内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
見つからない場合は、同じメジャー内の次の上位のマイナーおよび機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
見つからない場合は、失敗します。If not found, fails.
major 指定されたメジャー、マイナー、および機能帯に対して最新のパッチ レベルを使用します。Uses the latest patch level for the specified major, minor, and feature band.
見つからない場合は、同じメジャー バージョンまたはマイナー バージョン内の次の上位の機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
見つからない場合は、同じメジャー内の次の上位のマイナーおよび機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
見つからない場合は、次の上位のメジャー、マイナー、機能帯にロールフォワードし、その機能帯に最新のパッチ レベルを使用します。If not found, rolls forward to the next higher major, minor, and feature band and uses the latest patch level for that feature band.
見つからない場合は、失敗します。If not found, fails.
latestPatch 要求されたメジャー、マイナー、および機能帯が、指定された値以上のパッチ レベルと一致する、インストールされている最新のパッチ レベルを使用します。Uses the latest installed patch level that matches the requested major, minor, and feature band with a patch level and that is greater or equal than the specified value.
見つからない場合は、失敗します。If not found, fails.
latestFeature 要求されたメジャーとマイナーが、指定された値以上の機能帯と一致する、インストールされている最上位の機能帯を使用します。Uses the highest installed feature band and patch level that matches the requested major and minor with a feature band that is greater or equal than the specified value.
見つからない場合は、失敗します。If not found, fails.
latestMinor 要求されたメジャーが指定された値以上のマイナーと一致する、インストールされている最上位のマイナー、機能帯、パッチ レベルを使用します。Uses the highest installed minor, feature band, and patch level that matches the requested major with a minor that is greater or equal than the specified value.
見つからない場合は、失敗します。If not found, fails.
latestMajor インストールされている最上位の .NET Core SDK と、指定した値以上のメジャーを使用します。Uses the highest installed .NET Core SDK with a major that is greater or equal than the specified value.
見つからない場合は、失敗します。If not found, fail.
disable ロールフォワードしません。Doesn't roll forward. 完全一致が必要です。Exact match required.

msbuild-sdksmsbuild-sdks

型: objectType: object

個々のプロジェクトではなく、1 か所でプロジェクト SDK バージョンを管理できます。Lets you control the project SDK version in one place rather than in each individual project. 詳細については、「プロジェクト SDK の解決方法」を参照してください。For more information, see How project SDKs are resolved.

使用例Examples

次の例は、プレリリース バージョンを使用しない方法を示しています。The following example shows how to not use prerelease versions:

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

次の例は、指定したバージョン以上の、インストールされている最新バージョンを使用する方法を示しています。The following example shows how to use the highest version installed that is greater or equal than the specified version. この JSON では、2.2.200 より前の SDK バージョンがすべて禁止され、3.0.xxx や 3.1.xxx など、2.2.200 以降のバージョンがすべて許可されます。The JSON shown disallows any SDK version earlier than 2.2.200 and allows 2.2.200 or any later version, including 3.0.xxx and 3.1.xxx.

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

次の例は、指定された正確なバージョンを使用する方法を示しています。The following example shows how to use the exact specified version:

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

次の例では、特定のメジャー バージョンとマイナー バージョンでインストールされる最新の機能バンドと修正プログラムのバージョンを使用する方法を示します。The following example shows how to use the latest feature band and patch version installed of a specific major and minor version. この JSON では、3.1.102 より前の SDK バージョンがすべて禁止され、3.1.103 や 3.1.200 など、3.1.102 とそれ以降の 3.1.xxx バージョンがすべて許可されます。The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.xxx version, such as 3.1.103 or 3.1.200.

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

次の例は、特定のバージョンのインストールされている最新のパッチ バージョンを使用する方法を示しています。The following example shows how to use the highest patch version installed of a specific version. この JSON では、3.1.102 より前の SDK バージョンがすべて禁止され、3.1.103 や 3.1.199 など、3.1.102 とそれ以降の 3.1.1xx バージョンがすべて許可されます。The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.1xx version, such as 3.1.103 or 3.1.199.

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

global.json と .NET Core CLIglobal.json and the .NET Core CLI

ご使用のマシンにインストールされている SDK のバージョンを把握しておくと、global.json ファイルにそれを設定するときに役立ちます。It's helpful to know which SDK versions are installed on your machine to set one in the global.json file. その方法の詳細については、.NET Core が既にインストールされていることを確認する方法に関するセクションを参照してください。For more information on how to do that, see How to check that .NET Core is already installed.

.NET Core SDK の別のバージョンをコンピューターにインストールするには、.NET Core のダウンロード ページにアクセスしてください。To install additional .NET Core SDK versions on your machine, visit the Download .NET Core page.

次の例のような dotnet new コマンドを実行することにより、新しい global.json ファイルを現在のディレクトリに作成できます。You can create a new the global.json file in the current directory by executing the dotnet new command, similar to the following example:

dotnet new globaljson --sdk-version 3.0.100

照合ルールMatching rules

注意

照合ルールは、すべてのインストール済み .NET Core のインストール済みランタイムで共通の dotnet.exe エントリ ポイントによって管理されます。The matching rules are governed by the dotnet.exe entry point, which is common across all installed .NET Core installed runtimes. .NET Core ランタイムのインストール済みの最新バージョンの照合ルールは、複数のランタイムがサイドバイサイドでインストールされている場合に使用されます。The matching rules for the latest installed version of the .NET Core Runtime are used when you have multiple runtimes installed side-by-side.

.NET Core 3.0 以降では、使用する SDK のバージョンを決定するときに次のルールが適用されます。Starting with .NET Core 3.0, the following rules apply when determining which version of the SDK to use:

  • global.json ファイルが見つからない場合、または global.json で SDK のバージョンまたは allowPrerelease 値が指定されていない場合は、インストールされている最新バージョンの SDK が使用されます (rollForwardlatestMajor に設定するのと同じ)。If no global.json file is found, or global.json doesn't specify an SDK version nor an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). プレリリース SDK のバージョンを考慮するかどうかは、dotnet の呼び出し方法によって決まります。Whether prerelease SDK versions are considered depends on how dotnet is being invoked.

    • Visual Studio を使用していない場合は、プレリリース バージョンが考慮されます。If you're not in Visual Studio, prerelease versions are considered.
    • Visual Studio を使用している場合は、要求されたプレリリース状態が使用されます。If you are in Visual Studio, it uses the prerelease status requested. つまり、Visual Studio のプレビュー バージョンを使用している場合、または ( [ツール] > [オプション] > [環境] > [プレビュー機能] で) [.NET Core SDK のプレビューを使用する] オプションを設定している場合、プレリリース バージョンが考慮され、それ以外の場合は、リリース バージョンのみが考慮されます。That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), prerelease versions are considered; otherwise, only release versions are considered.
  • SDK のバージョンは指定していないが allowPrerelease 値を指定している global.json ファイルが見つかった場合は、インストールされている最新の SDK バージョンが使用されます (rollForwardlatestMajor に設定するのと同じ)。If a global.json file is found that doesn't specify an SDK version but it specifies an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). 最新の SDK バージョンをリリースまたはプレリリースにできるかどうかは、allowPrerelease の値によって決まります。Whether the latest SDK version can be release or prerelease depends on the value of allowPrerelease. true は、プレリリースバージョンが考慮されることを示し、false は、リリース バージョンのみが考慮されることを示します。true indicates prerelease versions are considered; false indicates that only release versions are considered.

  • global.json ファイルが見つかり、そこで SDK バージョンが指定されている場合は、次のようになります。If a global.json file is found and it specifies an SDK version:

    • rollFoward 値が設定されていない場合、latestPatch が既定の rollForward ポリシーとして使用されます。If no rollFoward value is set, it uses latestPatch as the default rollForward policy. それ以外の場合は、「rollForward」セクションで各値とその動作を確認します。Otherwise, check each value and their behavior in the rollForward section.
    • allowPrerelease」セクションには、プレリリース バージョンが考慮されるかどうか、allowPrerelease が設定されていない場合の既定の動作についての説明があります。Whether prerelease versions are considered and what's the default behavior when allowPrerelease isn't set is described in the allowPrerelease section.

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

  • 次の警告は、プロジェクトがプレリリース バージョンの .NET Core SDK を使用してコンパイルされたことを示しています。The following warning indicates that your project was compiled using a prerelease version of the .NET Core SDK:

    .NET Core SDK のプレビュー バージョンを使用しています。You are working with a preview version of the .NET Core SDK. 現在のプロジェクトの global.json ファイルを使用して、SDK のバージョンを定義できます。You can define the SDK version via a global.json file in the current project. 詳しくは https://go.microsoft.com/fwlink/?linkid=869452 を参照してください。More at https://go.microsoft.com/fwlink/?linkid=869452.

    .NET Core SDK のバージョンには高品質の履歴とコミットメントがあります。.NET Core SDK versions have a history and commitment of being high quality. ただし、プレリリース バージョンを使用しない場合は、「allowPrerelease」セクションで、.NET Core 3.0 SDK 以降のバージョンで使用できるさまざまな方法を確認してください。However, if you don't want to use a prerelease version, check the different strategies you can use with the .NET Core 3.0 SDK or a later version in the allowPrerelease section. .NET Core 3.0 以降のランタイムまたは SDK がインストールされていないマシンの場合は、global.json ファイルを作成し、使用する正確なバージョンを指定する必要があります。For machines that have never had a .NET Core 3.0 or higher Runtime or SDK installed, you need to create a global.json file and specify the exact version you want to use.

  • 次の警告は、プロジェクトのターゲットが EF Core 1.0 または 1.1 であり、.NET Core 2.1 SDK 以降のバージョンと互換性がないことを示します。The following warning indicates that your project targets EF Core 1.0 or 1.1, which isn't compatible with .NET Core 2.1 SDK and later versions:

    スタートアップ プロジェクト '{startupProject}' で、フレームワーク '.NETCoreApp' バージョン '{targetFrameworkVersion}'Startup project '{startupProject}' targets framework '.NETCoreApp' version '{targetFrameworkVersion}'. がターゲットになっています。このバージョンの Entity Framework Core .NET コマンド ライン ツールは、バージョン 2.0 以降のみをサポートします。This version of the Entity Framework Core .NET Command-line Tools only supports version 2.0 or higher. 古いバージョンのツールの使用については、https://go.microsoft.com/fwlink/?linkid=871254 をご覧ください。For information on using older versions of the tools, see https://go.microsoft.com/fwlink/?linkid=871254.

    .NET Core 2.1 SDK (バージョン 2.1.300) 以降で、dotnet ef コマンドは SDK に含まれています。Starting with .NET Core 2.1 SDK (version 2.1.300), the dotnet ef command comes included in the SDK. プロジェクトをコンパイルするには、.NET Core 2.0 SDK (バージョン 2.1.201) またはそれ以前のバージョンをご利用のコンピューター上にインストールし、global.json ファイルを使用して必要な SDK バージョンを定義します。To compile your project, install .NET Core 2.0 SDK (version 2.1.201) or earlier on your machine and define the desired SDK version using the global.json file. dotnet ef コマンドの詳細については、「EF Core .NET コマンドライン ツール」を参照してください。For more information about the dotnet ef command, see EF Core .NET Command-line Tools.

関連項目See also