global.json 概觀global.json overview

本文適用于:✓ .net CORE 1.x sdk .net core 2.x sdkThis article applies to: ✓ .NET Core 1.x SDK .NET Core 2.x SDK

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 tools are used. 一般情況下,您要使用最新版本的工具,所以不需要 global.json 檔案。In general, you want to use the latest version of the tools, so no global.json file is needed.

如需改為指定執行階段的詳細資訊,請參閱目標架構For more information about specifying the runtime instead, see Target frameworks.

.NET Core CLI 工具會在目前工作目錄 (這不一定與專案目錄相同) 或它的其中一個上層目錄中尋找 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 SDK 版本。The version of the .NET Core SDK to use.

請注意,此欄位:Note that this field:

  • 不支援萬用字元,亦即,必須指定完整的版本號碼。Doesn't have globbing support, that is, the full version number has to be specified.
  • 不支援版本範圍。Doesn't support version ranges.

下列範例顯示 global.json 檔案的內容:The following example shows the contents of a global.json file:

{
  "sdk": {
    "version": "2.2.100"
  }
}

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

最好知道哪一個版本可供使用,以便在 global.json 檔案中設定一個。It's helpful to know which versions are available in order to set one in the global.json file. 您可以在下載 .Net Core頁面上找到支援的可用 sdk 完整清單。You can find the full list of supported available SDKs at the Download .NET Core page. 從 .NET Core 2.1 SDK 開始,您可以執行下列命令來確認電腦上已經安裝的 SDK 版本:Starting with .NET Core 2.1 SDK, you can run the following command to verify which SDK versions are already installed on your machine:

dotnet --list-sdks

若要在您的電腦上安裝其他 .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 2.2.100

比對規則Matching rules

注意

比對規則由 apphost 規範,這是.NET Core 執行階段的一部分。The matching rules are governed by the apphost, which is part of the .NET Core runtime. 您有多個執行階段並列安裝時,會使用最新版本的主機。The latest version of the host is used when you have multiple runtimes installed side-by-side.

從 .NET Core 2.0 開始,決定要使用哪個 SDK 版本時會使用下列規則:Starting with .NET Core 2.0, the following rules apply when determining which version of the SDK to use:

  • 如果找不到 global.json 檔案或 global.json 沒有指定 SDK 版本,則會使用最新安裝的 SDK 版本。If no global.json file is found or global.json doesn't specify an SDK version, the latest installed SDK version is used. 最新的 SDK 版本可以是發行版本或發行前版本,而最高版本號碼優先採用。Latest SDK version can be either release or pre-release - the highest version number wins.
  • 如果 global.json 未指定 SDK 版本:If global.json does specify an SDK version:
    • 如果在電腦上找到了指定的 SDK 版本,則會使用這個版本。If the specified SDK version is found on the machine, that exact version is used.
    • 如果在電腦上找不到指定的 SDK 版本,則會使用該版本的最新已安裝 SDK 修補程式版本If the specified SDK version can't be found on the machine, the latest installed SDK patch version of that version is used. 最新已安裝的 SDK 修補程式版本可以是發行版本或發行前版本,而最高版本號碼優先採用。Latest installed SDK patch version can be either release or pre-release - the highest version number wins. 對於 .NET Core 2.1 和更新版本,在 SDK 選取項目中,低於指定的修補程式版本修補程式版本會被忽略。In .NET Core 2.1 and higher, the patch versions lower than the patch version specified are ignored in the SDK selection.
    • 如果找不到指定的 SDK 版本和適當的 SDK 修補程式版本,則會擲回錯誤。If the specified SDK version and an appropriate SDK patch version can't be found, an error is thrown.

SDK 版本目前由下列部分組成:The SDK version is currently composed of the following parts:

[.NET Core major version].[.NET Core minor version].[xyz][-optional preview name]

.NET Core SDK 功能版本是由 SDK 2.1.100 和更新版本號碼最後部分 (xyz) 的第一個數字 (x) 表示。The feature release of the .NET Core SDK is represented by the first digit (x) in the last portion of the number (xyz) for SDK versions 2.1.100 and higher. 一般而言,.NET Core SDK 的發行週期比 .NET Core 快。In general, the .NET Core SDK has a faster release cycle than .NET Core.

修補程式版本由 SDK 2.1.100 和更新版本號碼最後部分 (xyz) 的最後兩個數字 (yz) 定義。The patch version is defined by the last two digits (yz) in the last portion of the number (xyz) for SDK versions 2.1.100 and higher. 例如,如果指定 2.1.300 做為 SDK 版本,SDK 選取項目最高會找到 2.1.399,但是 2.1.400 不視為 2.1.300 的修補版本。For example, if you specify 2.1.300 as the SDK version, SDK selection finds up to 2.1.399 but 2.1.400 isn't considered a patch version for 2.1.300.

.NET Core SDK 版本 2.1.1002.1.201 是在版本號碼轉換期間發行,它們並沒有正確地處理 xyz 標記法。.NET Core SDK versions 2.1.100 through 2.1.201 were released during the transition between version number schemes and don't correctly handle the xyz notation. 強烈建議如果您在 global.json 檔案中指定這些版本,則必須確保目標電腦上有這些指定的版本。We highly recommend if you specify these versions in the global.json file, that you ensure the specified versions are on the target machines.

對於.NET Core SDK 1.x,如果您指定了某個版本但找不到它,則會使用最新安裝的 SDK 版本。With .NET Core SDK 1.x, if you specified a version and no exact match was found, the latest installed SDK version was used. 最新的 SDK 版本可以是發行版本或發行前版本,而最高版本號碼優先採用。Latest SDK version can be either release or pre-release - the highest version number wins.

為組建警告進行疑難排解Troubleshooting build warnings

警告

您正在使用.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=869452More at https://go.microsoft.com/fwlink/?linkid=869452

這則警告指出您的專案正使用.NET Core SDK 的預覽版本編譯,如比對規則一節中的說明。This warning indicates that your project is being compiled using a preview version of the .NET Core SDK, as explained in the Matching rules section. .NET Core SDK 版本一向承諾提供高品質的產品。.NET Core SDK versions have a history and commitment of being high quality. 不過,如果您不想使用預覽版本,請新增 global.json 檔案到專案階層架構以指定要使用的 SDK 版本,並使用 dotnet --list-sdks 來確認電腦上已安裝該版本。However, if you don't want to use a preview version, add a global.json file to your project hierarchy structure to specify which SDK version to use, and use dotnet --list-sdks to confirm that the version is installed on your machine. 新版本發行時,若要使用新的版本,可移除 global.json 檔案或更新它以使用較新版本。When a new version is released, to use the new version, either remove the global.json file or update it to use the newer version.

警告

啟動專案 '{startupProject}' targets framework '.NETCoreApp' version '{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. 這個警告指出您的專案目標為 EF Core 1.0 或 1.1,與 .NET Core 2.1 SDK 和更新版本不相容。This 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. 若要編譯您的專案,請在您的機器上安裝 .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) and 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