選取要使用的 .NET 版本

發行項
02/06/2025

本文說明 .NET 工具、SDK 和運行時間用於選取版本的原則。這些政策在使用指定版本執行應用程式與輕鬆升級開發者和使用者裝置之間取得平衡。這些政策會啟用：

輕鬆且有效率地部署 .NET，包括安全性和可靠性更新。
使用與目標運行時間無關的最新工具和命令。

正在進行版本選擇：

當您執行 SDK 命令時，SDK 會使用最新版本。
當您建置元件時，目標框架標誌定義了建置時的 API。
當您執行 .NET 應用程式時，目標框架相依應用程式向前移動。
當您發布獨立式應用程式時，獨立部署包包含選取的執行階段。

本檔的其餘部分會檢查這四個案例。

SDK 使用最新安裝的版本

SDK 命令包括 dotnet new 與 dotnet run。 .NET CLI 必須為每個 dotnet 命令選擇 SDK 版本。它預設會使用電腦上安裝的最新 SDK，即使：

專案以舊版 .NET 運行時間為目標。
最新版的 .NET SDK 是預覽版本。

您可以利用最新的 SDK 功能和改進，同時支援舊版 .NET 執行階段。您可以使用相同的 SDK 工具，以不同的 .NET 執行時間版本為目標。

在某些情況下，您可能需要使用特定版本的 SDK。您可以在 global.json 檔案中指定該版本，。

global.json 可以放在檔案階層中的任何位置。您可以透過檔案系統中位置來控制指定 global.json 套用的專案。 .NET CLI 會反覆搜尋 global.json 檔案，從目前的工作目錄向上巡覽路徑（這不一定與專案目錄相同）。找到的第一個 global.json 檔案會指定所使用的版本。如果已安裝該 SDK 版本，則會使用該版本。如果找不到 global.json 中指定的 SDK，.NET CLI 會使用比對規則來選取相容的 SDK，如果找不到任何規則，則失敗。

下列範例顯示 global.json 語法：

{
  "sdk": {
    "version": "5.0.0"
  }
}

選取 SDK 版本的過程如下：

dotnet 搜尋 global.json 檔案，反覆地從目前工作目錄向上瀏覽路徑。
dotnet 會使用找到的第一個 global.json 中指定的 SDK。
如果找不到 global.json，dotnet 會使用最新安裝的 SDK。

如需 SDK 版本選取的詳細資訊，請參閱 global.json 概觀一文的比對規則和 rollForward 小節。

更新 SDK 版本

請務必定期更新至最新版本的 SDK，以採用最新的功能、效能改善和錯誤修正。若要輕鬆地檢查 SDK 的更新，請使用 dotnet sdk check命令。此外，如果您使用 global.json選取特定版本，請考慮使用 Dependabot 之類的工具，在新版本可用時自動更新釘選的 SDK 版本。

目標框架識別符號定義建置時的 API

您可以針對 目標架構Moniker （TFM）中所定義的 API 建置專案。您可以在項目檔中指定目標架構。在您的項目檔中設置 TargetFramework 元件，如下列範例所示：

<TargetFramework>net8.0</TargetFramework>

您可以針對多個TFM 建置專案。為連結庫設定多個目標架構更為常見，但也可以使用應用程式來完成。您可以指定 TargetFrameworks 屬性（TargetFramework複數）。目標架構是以分號分隔，如下列範例所示：

<TargetFrameworks>net8.0;net47</TargetFrameworks>

指定的 SDK 支援固定的一組架構，其上限為隨附之運行時間的目標架構。例如，.NET 8 SDK 包含 .NET 8 執行階段，這是 net8.0 目標框架的實作。 .NET 8 SDK 支援 net7.0、net6.0和 net5.0，但不支援 net9.0 （或更新版本）。您可以安裝 .NET 9 SDK 來建置 net9.0。

.NET Standard

.NET Standard 是以不同 .NET 實作所共用的 API 介面為目標的一種方式。從 .NET 5 版本開始，這是 API 標準本身，.NET Standard 沒有什麼相關性，但有一個案例除外：當您想要以 .NET 和 .NET Framework 為目標時，.NET Standard 很有用。 .NET 5 會實作所有 .NET Standard 版本。

如需詳細資訊，請參閱 .NET 5 和 .NET Standard。

框架相依的應用程式向前更新

當您從具有 dotnet run的原始來源執行應用程式，或從具有 dotnet myapp.dll的 架構相依部署，或從具有 myapp.exe的 架構相依的 可執行檔執行應用程式時，dotnet 可執行檔將成為應用程式的主機。

主機會選擇計算機上安裝的最新修補程式版本。例如，如果您在項目檔中指定了 net5.0，而且 5.0.2 已安裝最新的 .NET 運行時間，則會使用 5.0.2 運行時間。

如果找不到可接受的 5.0.* 版本，則會使用新的 5.* 版本。例如，如果您指定了 net5.0，而且只安裝 5.1.0，則應用程式會使用 5.1.0 運行時間執行。此行為稱為「次要版本向前遞進」。較低版本也不會被考慮。未安裝可接受的運行時間時，應用程式將不會執行。

如果您以 5.0 為目標，一些使用範例會示範行為：

✔️ 已指定 5.0。 5.0.3 是安裝的最高修補程式版本。使用 5.0.3。
指定為 ❌ 5.0。未安裝 5.0.* 版本。 3.1.1 是安裝的最高運行時間。顯示錯誤訊息。
✔️ 已指定 5.0。未安裝 5.0.* 版本。 5.1.0 是安裝的最高運行時間版本。使用 5.1.0。
已指定 ❌ 3.0。未安裝 3.x 版本。 5.0.0 是安裝的最高運行時間。顯示錯誤訊息。

次要版本向前更新有一個可能影響終端使用者的副作用。請考慮下列案例：

應用程式會指定需要 5.0。
執行時，不會安裝 5.0.* 版，但 5.1.0 版為。將會使用 5.1.0 版。
稍後，用戶會安裝 5.0.3 並再次執行應用程式，現在將會使用 5.0.3。

5.0.3 和 5.1.0 的行為可能不同，特別是針對串行化二進位數據等案例。

控制前滾行為

在覆寫預設向前復原行為之前，請先熟悉 .NET 運行時間相容性層級。

應用程式的向前復原行為可以透過四種不同的方式進行設定：

藉由設定 <RollForward> 屬性來設定專案層級設定：

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

*.runtimeconfig.json 檔案。

當您編譯應用程式時，會產生此檔案。如果專案中已設定 <RollForward> 屬性，則會在 *.runtimeconfig.json 檔案中重現為 rollForward 設定。用戶可以編輯此檔案來變更應用程式的行為。
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
dotnet 命令的 --roll-forward <value> 屬性。

當您執行應用程式時，您可以透過命令列控制前進更新行為：
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
DOTNET_ROLL_FORWARD 環境變數。

優先權

當您的應用程式執行時，向前復原行為會依照下列順序來設定，較高的編號專案優先於較低的編號專案：

首先會評估 *.runtimeconfig.json 組態檔。
接下來，會考慮 DOTNET_ROLL_FORWARD 環境變數，並覆寫先前的檢查。
最後，傳遞至執行中應用程式的任何 --roll-forward 參數會覆寫其他所有參數。

價值觀

無論您如何設定向前推進選項，請使用以下其中一個值來設定其行為：

價值	描述
`Minor`	如果未指定，將預設使用。如果要求的次要版本缺失，則升級到最低可用的更高次要版本。如果要求的次要版本存在，則會使用 `LatestPatch` 原則。
`Major`	如果缺少要求的主要版本，請向前復原至下一個可用的較高主要版本，以及最低次要版本。如果要求的主要版本存在，則會使用 `Minor` 原則。
`LatestPatch`	升級至最高版本的補丁。此值會停用次要版本的升級跳躍。
`LatestMinor`	升級至最高次要版本，即便要求的次要版本已存在。
`LatestMajor`	向前升級至最高的主要和次要版本，即使所要求的主要版本已存在。
`Disable`	請勿向前更新，只綁定至指定的版本。此原則不建議用於一般用途，因為它會停用向前復原至最新修補程式的功能。這個值僅供測試使用。

獨立部署包含選取的運行時間

您可以將應用程式發佈為 獨立發行。此方法會將 .NET 運行時間和連結庫與您的應用程式組合在一起。獨立式部署與運行時間環境沒有相依性。運行時間版本選取會在發佈時發生，而不是運行時間。

發佈時所發生的還原事件，會選取指定運行時間系列的最新修補程式版本。例如，如果它是 .NET 5 運行時間系列中最新的修補程式版本，dotnet publish 將會選取 .NET 5.0.3。目標架構（包括最新安裝的安全性修補程式）會與應用程式一起封裝。

如果不符合為應用程式指定的最低版本，就會發生錯誤。 dotnet publish 系結至最新的執行時修補版本（在指定的主次版本系列內）。 dotnet publish 不支援 dotnet run的向前復原語意。如需修補程式和獨立部署的詳細資訊，請參閱部署 .NET 應用程式中運行時間修補程式選取一文。

獨立式部署可能需要特定的修補程式版本。您可以在專案檔中覆寫最低執行階段修補版本（至更高或更低版本），如下列範例所示：

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

RuntimeFrameworkVersion 元素會覆寫預設版本原則。對於獨立式部署，RuntimeFrameworkVersion 會指定確切運行時間架構版本。針對架構相依的應用程式，RuntimeFrameworkVersion 會指定所需的運行時間架構版本最低。

共用方式為