global.json 概觀

  • 發行項

本文適用於： ✔️ .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 命令列工具。

  • 如果您使用 global.json 維持特定版本的 .NET SDK，須留意 Visual Studio 只會安裝 .NET SDK 的單一複本。 因此，如果升級 Visual Studio 版本，將會移除先前用來安裝新版本的舊版 .NET SDK。 舊版本會遭到移除，即使是不同的主要 .NET 版本亦然。

若要避免 Visual Studio 移除 .NET SDK 的版本，您必須從下載頁面安裝獨立 .NET SDK。 請注意，若這麼做，則不會再透過 Visual Studio 取得該 .NET SDK 版本的自動更新，而且可能會面臨安全性問題的風險。

另請參閱