選取要使用的 .NET Core 版本Select the .NET Core version to use

本文說明 .NET Core 工具、SDK 和執行階段用於選取版本的原則。This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. 這些原則在執行使用指定版本的應用程式,以及輕鬆升級開發人員和終端使用者電腦之間提供平衡。These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. 這些原則執行下列動作:These policies perform the following actions:

  • 輕鬆且有效率地部署 .NET Core,包括安全性和可靠性更新。Easy and efficient deployment of .NET Core, including security and reliability updates.
  • 使用最新的工具和命令,且不受目標執行階段影響。Use the latest tools and commands independent of target runtime.

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

本文件的其餘部分會說明這四個案例。The rest of this document examines those four scenarios.

SDK 使用最新安裝的版本The SDK uses the latest installed version

SDK 命令包含 dotnet newdotnet runSDK commands include dotnet new and dotnet run. .NET Core CLI 針對每個 dotnet 命令都必須選擇 SDK 版本。The .NET Core CLI must choose an SDK version for every dotnet command. 根據預設,它會使用電腦上最新安裝的 SDK,即使:It uses the latest SDK installed on the machine by default, even if:

  • 專案是以 .NET Core 執行階段的舊版為目標。The project targets an earlier version of the .NET Core runtime.
  • .NET Core SDK 的最新版本是預覽版。The latest version of the .NET Core SDK is a preview version.

您可以利用最新的 SDK 功能和增強功能,同時以舊版 .NET Core 執行階段為目標。You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. 您可以在不同專案上以多個 .NET Core 執行階段版本為目標,並針對所有專案使用相同的 SDK 工具。You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

在罕見的情況下,您可能需要使用舊版的 SDK。On rare occasions, you may need to use an earlier version of the SDK. 您可以在 global.json 檔案中指定該版本。You specify that version in a global.json file. 「使用最新版」原則表示您只會使用 global.json 指定比最新安裝版本更早的 .NET Core SDK 版本。The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

global.json 可能放在檔案階層中的任何地方。global.json can be placed anywhere in the file hierarchy. CLI 會從專案目錄向上搜尋,以找到第一個 global.jsonThe CLI searches upward from the project directory for the first global.json it finds. 您可以根據指定的 global.json 在檔案系統中的位置,來控制其所套用的專案。You control which projects a given global.json applies to by its place in the file system. .NET CLI 會從目前的工作目錄向上反覆巡覽路徑,以搜尋 global.json 檔案。The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. 第一個找到的 global.json 檔案指定所使用的版本。The first global.json file found specifies the version used. 如果安裝該版本,則會使用該版本。If that version is installed, that version is used. 如果找不到 global.json 中指定的 SDK,.NET CLI 會向前復原到最新安裝的 SDK。If the SDK specified in the global.json is not found, the .NET CLI rolls forward to the latest SDK installed. 找不到 global.json 檔案時,向前復原會與預設行為相同。Roll-forward is the same as the default behavior, when no global.json file is found.

下列範例示範 global.json 語法:The following example shows the global.json syntax:

{
  "sdk": {
    "version": "2.0.0"
  }
}

選取 SDK 版本的過程如下:The process for selecting an SDK version is:

  1. dotnet 會從目前的工作目錄向上反覆反向巡覽路徑,以搜尋 global.json 檔案。dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet 使用第一個找到的 global.json 中指定的 SDK。dotnet uses the SDK specified in the first global.json found.
  3. 如果找不到 global.jsondotnet 會使用最新安裝的 SDK。dotnet uses the latest installed SDK if no global.json is found.

您可以在 global.json 一文的比對規則一節中,深入了解如何選取 SDK 版本。You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

目標 Framework Moniker 定義建置時間 APITarget Framework Monikers define build time APIs

您可以針對目標 Framework Moniker (TFM) 中定義的 API 建置專案。You build your project against APIs defined in a Target Framework Moniker (TFM). 您會在專案檔中指定目標 FrameworkYou specify the target framework in the project file. 在您的專案檔中設定 TargetFramework 項目,如下列範例所示:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp2.0</TargetFramework>

您可以針對多個 TFM 建置專案。You may build your project against multiple TFMs. 設定多個目標 Framework 對程式庫較常見,但也可透過應用程式完成。Setting multiple target frameworks is more common for libraries but can be done with applications as well. 您會指定 TargetFrameworks 屬性 (TargetFramework 的複數形式)。You specify a TargetFrameworks property (plural of TargetFramework). 目標 Framework 是以分號分隔,如下列範例所示:The target frameworks are semicolon-delimited as shown in the following example:

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

指定的 SDK 支援一組固定的架構,限制為其隨附執行階段的目標 Framework。A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. 例如,.NET Core 2.0 SDK 包含 .NET Core 2.0 執行階段,這是 netcoreapp2.0 目標 Framework 的實作。For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the netcoreapp2.0 target framework. .NET Core 2.0 SDK 支援 netcoreapp1.0netcoreapp1.1netcoreapp2.0,但不支援 netcoreapp2.1 (或更新版本)。The .NET Core 2.0 SDK supports netcoreapp1.0, netcoreapp1.1, and netcoreapp2.0 but not netcoreapp2.1 (or higher). 您可以安裝 .NET Core 2.1 SDK 來建置 netcoreapp2.1You install the .NET Core 2.1 SDK to build for netcoreapp2.1.

.NET Standard 目標 Framework 也限制為 SDK 隨附執行階段的目標 Framework。.NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. .NET Core 2.0 SDK 限制為 netstandard2.0The .NET Core 2.0 SDK is capped to netstandard2.0.

架構相依應用程式向前復原Framework-dependent apps roll forward

當您使用 dotnet run 從來源執行應用程式、使用 dotnet myapp.dll架構相依部署執行應用程式,或使用 myapp.exe架構相依可執行檔執行應用程式時,dotnet 可執行檔會是該應用程式的主機When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

該主機會選擇電腦上最新安裝的修補程式版本。The host chooses the latest patch version installed on the machine. 例如,如果您在專案檔中指定 netcoreapp2.0,且 2.0.4 是最新安裝的 .NET 執行階段,則會使用 2.0.4 執行階段。For example, if you specified netcoreapp2.0 in your project file, and 2.0.4 is the latest .NET runtime installed, the 2.0.4 runtime is used.

如果找不到可接受的 2.0.* 版本,則會使用新的 2.* 版本。If no acceptable 2.0.* version is found, a new 2.* version is used. 例如,如果您指定 netcoreapp2.0 並只安裝 2.1.0,應用程式會使用 2.1.0 執行階段來執行。For example, if you specified netcoreapp2.0 and only 2.1.0 is installed, the application runs using the 2.1.0 runtime. 此行為稱為「次要版本向前復原」。This behavior is referred to as "minor version roll-forward." 也不會考慮舊版。Lower versions also won't be considered. 若未安裝可接受的執行階段,應用程式將不會執行。When no acceptable runtime is installed, the application won't run.

若您以 2.0 作為目標,下列使用方式範例會表現出此行為:A few usage examples demonstrate the behavior, if you target 2.0:

  • 已指定 2.0。2.0 is specified. 2.0.5 是安裝的最高修補程式版本。2.0.5 is the highest patch version installed. 使用 2.0.5。2.0.5 is used.
  • 已指定 2.0。2.0 is specified. 未安裝 2.0.* 版本。No 2.0.* versions are installed. 1.1.1 是安裝的最高執行階段版本。1.1.1 is the highest runtime installed. 顯示錯誤訊息。An error message is displayed.
  • 已指定 2.0。2.0 is specified. 未安裝 2.0.* 版本。No 2.0.* versions are installed. 2.2.2 是安裝的最高 2.x 執行階段版本。2.2.2 is the highest 2.x runtime version installed. 使用 2.2.2。2.2.2 is used.
  • 已指定 2.0。2.0 is specified. 未安裝 2.x 版本。No 2.x versions are installed. 而是安裝了 3.0.0。3.0.0 is installed. 顯示錯誤訊息。An error message is displayed.

次要版本向前復原有一個可能會影響終端使用者的副作用。Minor version roll-forward has one side-effect that may affect end users. 請考慮下列案例:Consider the following scenario:

  1. 應用程式指定 2.0 為必要項目。The application specifies that 2.0 is required.
  2. 執行時,未安裝 2.0.* 版,但已安裝 2.2.2。When run, version 2.0.* is not installed, however, 2.2.2 is. 則會使用 2.2.2 版。Version 2.2.2 will be used.
  3. 稍後,使用者會安裝 2.0.5 並再次執行應用程式,則現在會使用 2.0.5。Later, the user installs 2.0.5 and runs the application again, 2.0.5 will now be used.

2.0.5 和 2.2.2 的行為可能不同,特別是針對序列化二進位資料等案例。It's possible that 2.0.5 and 2.2.2 behave differently, particularly for scenarios like serializing binary data.

獨立部署包含選取的執行階段Self-contained deployments include the selected runtime

您可以將應用程式發佈為獨立散發You can publish an application as a self-contained distribution. 此方法會將 .NET Core 執行階段和程式庫與您的應用程式配套。This approach bundles the .NET Core runtime and libraries with your application. 獨立部署不會相依於執行階段環境。Self-contained deployments don't have a dependency on runtime environments. 執行階段版本選取發生於發佈時,而不是執行時。Runtime version selection occurs at publishing time, not run time.

發佈過程會選取指定執行階段系列的最新修補程式版本。The publishing process selects the latest patch version of the given runtime family. 例如,如果 .NET Core 2.0.4 是 .NET Core 2.0 執行階段系列中的最新修補程式版本,dotnet publish 會選取此版本。For example, dotnet publish will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. 目標 Framework (包括最新安裝的安全性修補程式) 會封裝於應用程式。The target framework (including the latest installed security patches) is packaged with the application.

如果不符合針對應用程式指定的最低版本,就會發生錯誤。It's an error if the minimum version specified for an application isn't satisfied. dotnet publish 會繫結至最新的執行階段修補程式版本 (指定的主要.次要版本系列內)。dotnet publish binds to the latest runtime patch version (within a given major.minor version family). dotnet publish 不支援 dotnet run 的向前復原語意。dotnet publish doesn't support the roll-forward semantics of dotnet run. 如需修補程式和獨立部署的詳細資訊,請參閱部署 .NET Core 應用程式中有關執行階段修補程式選取的文章。For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

獨立部署可能需要特定修補程式版本。Self-contained deployments may require a specific patch version. 您可以覆寫專案檔中的最低執行階段修補程式版本 (改為較高或較低版本),如下列範例所示:You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>

RuntimeFrameworkVersion 項目會覆寫預設版本原則。The RuntimeFrameworkVersion element overrides the default version policy. 針對獨立部署,RuntimeFrameworkVersion 會指定「確切」 的執行階段架構版本。For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. 針對架構相依應用程式,RuntimeFrameworkVersion 會指定所需的「最低」 執行階段架構版本。For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.