選取要使用的 .NET 版本

發行項
02/24/2024

本文說明 .NET 工具、SDK 和執行階段用於選取版本的原則。這些原則在執行使用指定版本的應用程式，以及輕鬆升級開發人員和終端使用者電腦之間提供平衡。這些原則會實現：

輕鬆且有效率地部署 .NET，包括安全性和可靠性更新。
使用最新的工具和命令，且不受目標執行階段影響。

版本選取發生於下列情況：

當您執行 SDK 命令時，SDK 使用最新安裝的版本。
當您繫結組件時，目標 Framework Moniker 定義建置時間 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 指定比最新安裝版本更早的 .NET SDK 版本。

global.json 可能放在檔案階層中的任何地方。 CLI 會從專案目錄向上搜尋，以找到第一個 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 章節。

目標 Framework Moniker 定義建置時間 API

您可以針對目標 Framework Moniker (TFM) 中定義的 API 建置專案。您會在專案檔中指定目標 Framework。在您的專案檔中設定 TargetFramework 項目，如下列範例所示：

<TargetFramework>net5.0</TargetFramework>

您可以針對多個 TFM 建置專案。設定多個目標 Framework 對程式庫較常見，但也可透過應用程式完成。您會指定 TargetFrameworks 屬性 (TargetFramework 的複數形式)。目標 Framework 是以分號分隔，如下列範例所示：

<TargetFrameworks>net5.0;netcoreapp3.1;net47</TargetFrameworks>

指定的 SDK 支援一組固定的架構，限制為其隨附執行階段的目標 Framework。例如，.NET 5 SDK 包含 .NET 5 執行階段，這是 net5.0 目標架構的實作。 .NET 5 SDK 支援 netcoreapp2.0、netcoreapp2.1、netcoreapp3.0 等，但不支援 net6.0 (或更新版本)。您可以安裝 .NET 6 SDK 來建置 net6.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 參數會覆寫所有其他參數。

值

不過，您可以設定向前復原設定，請使用下列其中一個值來設定行為：

值	Description
`Minor`	預設值 (如果未指定) 如果缺少要求的次要版本，則會向前復原到最低次要版本中次高的版本。如果要求的次要版本存在，則會使用 `LatestPatch` 原則。
`Major`	如果缺少要求的主要版本，則會向前復原到次高的主要版本，以及最低的次要版本。如果要求的主要版本存在，則會使用 `Minor` 原則。
`LatestPatch`	向前復原到最高的修補程式版本。此值會停用次要版本向前復原。
`LatestMinor`	向前復原到最高的次要版本，即使要求的次要版本存在也一樣。
`LatestMajor`	向前復原到最高主要版本和最高次要版本，即使要求的主要版本存在也一樣。
`Disable`	請勿向前復原，只繫結至指定的版本。此原則不建議一般用途，因為它會停用向前復原到最新修補程式的功能。只有測試時才建議使用這個值。

獨立部署包含選取的執行階段

您可以將應用程式發佈為獨立散發。此方法會將 .NET 執行階段和程式庫與您的應用程式配套。獨立部署不會相依於執行階段環境。執行階段版本選取發生於發佈時，而不是執行時。

發佈期間發生的 restore 是鍵會選取指定執行階段系列的最新修補程式版本。舉例來說，如果 .NET 5.0.3 是 .NET 5 執行階段系列中的最新修補程式版本，dotnet publish 就會加以選取。目標 Framework (包括最新安裝的安全性修補程式) 會封裝於應用程式。

如果不符合針對應用程式指定的最低版本，就會發生錯誤。 dotnet publish 會繫結至最新的執行階段修補程式版本 (指定的主要.次要版本系列內)。 dotnet publish 不支援 dotnet run 的向前復原語意。如需修補程式和獨立部署的詳細資訊，請參閱部署 .NET 應用程式中有關執行階段修補程式選取的文章。

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

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

RuntimeFrameworkVersion 項目會覆寫預設版本原則。針對獨立部署，RuntimeFrameworkVersion 會指定「確切」的執行階段架構版本。針對架構相依應用程式，RuntimeFrameworkVersion 會指定所需的「最低」執行階段架構版本。