global.json 概觀

發行項
01/27/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 版本遺失時作為後援，或是作為使用較高版本的指示詞。除非您將版本設定為，否則必須以 rollForward 值指定版本 latestMajor 。預設向前復原行為取決於比對規則。

若要瞭解可用的原則及其行為，請考慮下列 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。

appsettings.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 的方式