選取要使用的 .NET 版本

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

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

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

本文件的其餘部分會說明這四個案例。

SDK 使用最新安裝的版本

SDK 命令包含 dotnet newdotnet 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,如果找不到任何 SDK,則會失敗。

下列範例示範 global.json 語法:

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

選取 SDK 版本的過程如下:

  1. dotnet 會從目前的工作目錄向上反覆反向巡覽路徑,以搜尋 global.json 檔案。
  2. dotnet 使用第一個找到的 global.json 中指定的 SDK。
  3. 如果找不到 global.jsondotnet 會使用最新安裝的 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 執行時間,這是目標 Framework 的實作 net5.0 。 .NET 5 SDK 支援 netcoreapp2.0netcoreapp2.1netcoreapp3.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 是安裝的最高執行時間。 顯示錯誤訊息。

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

  1. 應用程式指定需要 5.0。
  2. 執行時,未安裝 5.0.* 版,不過 5.1.0 版是 。 將會使用 5.1.0 版。
  3. 稍後,使用者會安裝 5.0.3 並再次執行應用程式,現在將會使用 5.0.3。

5.0.3 和 5.1.0 的行為可能不同,特別是序列化二進位資料等案例。

控制向前復原行為

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

  1. 設定 屬性來設定專案層級設定 <RollForward>

    <PropertyGroup>
      <RollForward>LatestMinor</RollForward>
    </PropertyGroup>
    
  2. 檔案 *.runtimeconfig.json

    當您編譯應用程式時,會產生此檔案。 如果屬性 <RollForward> 是在專案中設定,則會在 檔案中 *.runtimeconfig.json 重現為 rollForward 設定。 使用者可以編輯此檔案來變更應用程式的行為。

    {
      "runtimeOptions": {
        "tfm": "net5.0",
        "rollForward": "LatestMinor",
        "framework": {
          "name": "Microsoft.NETCore.App",
          "version": "5.0.0"
        }
      }
    }
    
  3. 命令 dotnet--roll-forward <value> 屬性。

    當您執行應用程式時,您可以透過命令列控制向前復原行為:

    dotnet run --roll-forward LatestMinor
    dotnet myapp.dll --roll-forward LatestMinor
    myapp.exe --roll-forward LatestMinor
    
  4. DOTNET_ROLL_FORWARD環境變數。

優先順序

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

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

不過,您設定向前復原設定,請使用下列其中一個值來設定行為:

描述
Minor 如果未指定,則為預設值
如果遺漏要求的次要版本,請向前復原至最低較高的次要版本。 如果要求的次要版本存在,則會使用原則 LatestPatch
Major 如果缺少要求的主要版本,請向前復原至下一個可用的較高主要版本,以及最低次要版本。 如果要求的主要版本存在,則會使用原則 Minor
LatestPatch 向前復原至最高修補程式版本。 此值會停用次要版本向前復原。
LatestMinor 向前復原至最高次要版本,即使要求次要版本存在也一樣。
LatestMajor 向前復原至最高主要和最高次要版本,即使要求的主要版本存在也一樣。
Disable 不要向前復原,只系結至指定的版本。 不建議將此原則用於一般用途,因為它會停用向前復原至最新修補程式的功能。 只有測試時才建議使用這個值。

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

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

發佈時所發生的 還原 事件會選取指定執行時間系列的最新修補程式版本。 例如, dotnet publish 如果 .NET 5.0.3 是 .NET 5 執行時間系列中的最新修補程式版本,則會選取 。NET 5.0.3。 目標 Framework (包括最新安裝的安全性修補程式) 會封裝於應用程式。

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

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

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

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

另請參閱