global.json 概觀

發行項
05/10/2023

本文適用於： ✔️ .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.300 或更新版本功能範圍或修補檔選取 6.0：

{
  "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 值指定。預設向前復原行為取決於對比規則。

若要了解可用的原則及其行為，請考慮下列 SDK 版本的定義格式 x.y.znn：

x 為主要版本。
y 為次要版本。
z 為功能範圍。
nn 為修補檔版本。

下表顯示 rollForward 金鑰可能值：

值	行為
`patch`	使用指定的版本。如果找不到，請向前復原至最新的修補檔層級。如果找不到，則會失敗。此值是先前 SDK 版本的舊版行為。
`feature`	針對指定的主要、次要和功能範圍，使用最新的修補檔層級。如果找不到，請向前復原至相同主要/次要中的下一個較高的功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，則會失敗。
`minor`	針對指定的主要、次要和功能範圍，使用最新的修補檔層級。如果找不到，請向前復原至相同主要/次要版本中的下一個較高功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，請向前復原至相同主要中的下一個較高的次要和功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，則會失敗。
`major`	針對指定的主要、次要和功能範圍，使用最新的修補檔層級。如果找不到，請向前復原至相同主要/次要版本中的下一個較高功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，請向前復原至相同主要中的下一個較高的次要和功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，請向前復原至下一個較高的主要、次要和功能範圍，並使用該功能範圍的最新修補檔層級。如果找不到，則會失敗。
`latestPatch`	使用已安裝的修補程式等級，符合要求的主要、次要和功能帶，以及大於或等於指定值的修補程式等級。如果找不到，則會失敗。
`latestFeature`	使用已安裝的最高功能帶和修補程式等級，符合要求的主要與次要，以及功能帶和大於或等於指定值的修補程式等級。如果找不到，則會失敗。
`latestMinor`	使用已安裝的次要、最高功能帶和修補程式等級，符合要求的主要與次要，以及功能帶和大於或等於指定值的修補程式等級。如果找不到，則會失敗。
`latestMajor`	使用已安裝的最高 .NET SDK 版本，且版本大於或等於指定的值。如果找不到，則會失敗。
`disable`	不會向前復原。需要完全相符。

msbuild-sdks

輸入： object

可讓您在一個地方統一控制專案 SDK 版本，而不是在每個個別專案中。如需詳細資訊，請參閱如何解析專案 SDK。

global.json 中的批註

使用 JavaScript 或 C# 樣式註解支援 global.json 檔案中的註解。例如：

{
   // 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 版本，並允許 2.2.200 或任何更新版本，包括 3.0.xxx 和 3.1.xxx。

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

下列範例示範如何使用確切的指定版本：

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

下列範例示範如何使用安裝特定主要和次要版本的最新功能範圍與修補檔版本。所示的 JSON 不允許任何早於 3.1.102 的 SDK 版本，並允許 3.1.102 或耿欣的 3.1.xxx 版本，例如 3.1.103 和 3.1.200。

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

下列範例示範如何使用已安裝特定版本的最高修補檔版本。所示的 JSON 不允許任何早於 3.1.102 的 SDK 版本，並允許 3.1.102 或耿欣的 3.1.1xx 版本，例如 3.1.103 和 3.1.199。

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

比對規則

注意

比對規則是由進入點所控管 dotnet.exe ，這在所有已安裝的 .NET 安裝執行時間中都是通用的。當您已並存安裝多個執行時間，或是或正在使用 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)。最新版本是否可以發行或發行前版本取決於 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}' targets framework '.NETCoreApp' version '{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 命令列工具。

另請參閱

解析專案 SDK 的方式