.NET Standard.NET Standard

.NET Standard 是計劃在所有 .NET 實作提供的 .NET API 型式規格。The .NET Standard is a formal specification of .NET APIs that are intended to be available on all .NET implementations. .NET Standard 背後的動機是在 .NET 生態系統中建立更高的一致性。The motivation behind the .NET Standard is establishing greater uniformity in the .NET ecosystem. ECMA 335 會繼續建立 .NET 實作行為的一致性,但對 .NET 程式庫實作之 .NET Base 類別庫 (BCL) 沒有類似規格。ECMA 335 continues to establish uniformity for .NET implementation behavior, but there's no similar spec for the .NET Base Class Libraries (BCL) for .NET library implementations.

.NET Standard 支援下列重要案例:The .NET Standard enables the following key scenarios:

  • 定義一致的 BCL API 集合,以供所有 .NET 實作來實作,而不論工作負載為何。Defines uniform set of BCL APIs for all .NET implementations to implement, independent of workload.
  • 可讓開發人員使用這組相同的 API,產生可跨 .NET 實作使用的可攜式程式庫。Enables developers to produce portable libraries that are usable across .NET implementations, using this same set of APIs.
  • 減少或甚至排除因 .NET API 而必須對共用原始檔進行的條件式編譯,僅適用於 OS API。Reduces or even eliminates conditional compilation of shared source due to .NET APIs, only for OS APIs.

不同的 .NET 實作會以特定版本的 .NET Standard 為目標。The various .NET implementations target specific versions of .NET Standard. 每個 .NET 實作版本會宣佈它所支援的最高 .NET Standard 版本,此聲明表示它也會支援舊版。Each .NET implementation version advertises the highest .NET Standard version it supports, a statement that means it also supports previous versions. 例如,.NET Framework 4.6 會實作 .NET Standard 1.3,這意謂著它會公開 .NET Standard 1.0 到 1.3 版中定義的所有 API。For example, the .NET Framework 4.6 implements .NET Standard 1.3, which means that it exposes all APIs defined in .NET Standard versions 1.0 through 1.3. 同樣地,.NET Framework 4.6.1 會實作 .NET Standard 1.4,而 .NET Core 1.0 會實作 .NET Standard 1.6。Similarly, the .NET Framework 4.6.1 implements .NET Standard 1.4, while .NET Core 1.0 implements .NET Standard 1.6.

.NET 實作支援.NET implementation support

下表列出支援每個 .NET Standard 版本的最低平台版本。The following table lists the minimum platform versions that support each .NET Standard version. 這表示所列出平台的更新版本也支援所對應 .NET Standard 版本。That means that later versions of a listed platform also support the corresponding .NET Standard version. 例如,.NET Core 2.2 支援 .NET Standard 2.0 及更早版本。For example, .NET Core 2.2 supports .NET Standard 2.0 and earlier.

.NET Standard.NET Standard 1.01.0 1.11.1 1.21.2 1.31.3 1.41.4 1.51.5 1.61.6 2.02.0
.NET Core.NET Core 1.01.0 1.01.0 1.01.0 1.01.0 1.01.0 1.01.0 1.01.0 2.02.0
.NET Framework 1.NET Framework 1 4.54.5 4.54.5 4.5.14.5.1 4.64.6 4.6.14.6.1 4.6.1 24.6.1 2 4.6.1 24.6.1 2 4.6.1 24.6.1 2
MonoMono 4.64.6 4.64.6 4.64.6 4.64.6 4.64.6 4.64.6 4.64.6 5.45.4
Xamarin.iOSXamarin.iOS 10.010.0 10.010.0 10.010.0 10.010.0 10.010.0 10.010.0 10.010.0 10.1410.14
Xamarin.MacXamarin.Mac 3.03.0 3.03.0 3.03.0 3.03.0 3.03.0 3.03.0 3.03.0 3.83.8
Xamarin.AndroidXamarin.Android 7.07.0 7.07.0 7.07.0 7.07.0 7.07.0 7.07.0 7.07.0 8.08.0
通用 Windows 平台Universal Windows Platform 10.010.0 10.010.0 10.010.0 10.010.0 10.010.0 10.0.1629910.0.16299 10.0.1629910.0.16299 10.0.1629910.0.16299
UnityUnity 2018.12018.1 2018.12018.1 2018.12018.1 2018.12018.1 2018.12018.1 2018.12018.1 2018.12018.1 2018.12018.1

1 為 .NET Framework 列出的版本適用於 .NET Core 2.0 SDK 和更新版本的工具。較舊的版本為 .NET Standard 1.5 與更新版本使用了不同的對應。若您無法升級到 Visual Studio 2017,您可以下載適用於 Visual Studio 2015 的 .NET Core 工具的工具1 The versions listed for .NET Framework apply to .NET Core 2.0 SDK and later versions of the tooling. Older versions used a different mapping for .NET Standard 1.5 and higher. You can download tooling for .NET Core tools for Visual Studio 2015 if you cannot upgrade to Visual Studio 2017.

2 列於此處的版本代表 NuGet 用來決定指定 .NET Standard 程式庫是否適用的規則。雖然 NuGet 將 .NET Framework 4.6.1 視為支援 .NET Standard 1.5 到 2.0,但從 .NET Framework 4.6.1 專案取用為這些版本建置的 .NET Standard 程式庫仍有許多問題。對於必須使用這類程式庫的 .NET Framework 專案,我們建議您將專案升級為目標 .NET Framework 4.7.2 或更新版本。2 The versions listed here represent the rules that NuGet uses to determine whether a given .NET Standard library is applicable. While NuGet considers .NET Framework 4.6.1 as supporting .NET Standard 1.5 through 2.0, there are several issues with consuming .NET Standard libraries that were built for those versions from .NET Framework 4.6.1 projects. For .NET Framework projects that need to use such libraries, we recommend that you upgrade the project to target .NET Framework 4.7.2 or higher.

  • 資料行代表 .NET Standard 版本。The columns represent .NET Standard versions. 每個標題儲存格都是一個文件連結,該文件說明在該 .NET Standard 版本中新增了哪些 API。Each header cell is a link to a document that shows which APIs got added in that version of .NET Standard.
  • 資料列代表不同的 .NET 實作。The rows represent the different .NET implementations.
  • 每個資料格中的版本號碼分別表示以該 .NET Standard 版本為目標所需的「最低」實作版本。The version number in each cell indicates the minimum version of the implementation you'll need in order to target that .NET Standard version.
  • 若為互動式資料表,請參閱 .NET Standard 版本For an interactive table, see .NET Standard versions.

若要尋找可作為您目標的最新版 .NET Standard,請執行下列步驟:To find the highest version of .NET Standard that you can target, do the following steps:

  1. 尋找指出要作為您執行位置之 .NET 實作的資料列。Find the row that indicates the .NET implementation you want to run on.
  2. 在該資料列中,由左到右尋找指出您版本的資料行。Find the column in that row that indicates your version starting from right to left.
  3. 資料行標題會指出您目標所支援的 .NET Standard 版本。The column header indicates the .NET Standard version that your target supports. 您也可以將目標設為任何較低的 .NET Standard 版本。You may also target any lower .NET Standard version. 較高的 .NET Standard 版本也會支援您的實作。Higher .NET Standard versions will also support your implementation.
  4. 針對您想要作為目標的每個平台重複此程序。Repeat this process for each platform you want to target. 如果您有多個目標平台,應該從中挑選最舊的版本。If you have more than one target platform, you should pick the smaller version among them. 例如,如果您想要在 .NET Framework 4.5 和 .NET Core 1.0 上執行,則可以使用的最新 .NET Standard 版本是 .NET Standard 1.1。For example, if you want to run on .NET Framework 4.5 and .NET Core 1.0, the highest .NET Standard version you can use is .NET Standard 1.1.

要以哪個 .NET Standard 版本作為目標Which .NET Standard version to target

選擇 .NET Standard 版本時,您應該考量下列取捨:When choosing a .NET Standard version, you should consider this trade-off:

  • 版本越新,可供您使用的 API 就越多。The higher the version, the more APIs are available to you.
  • 版本越舊,可實作它的平台就越多。The lower the version, the more platforms implement it.

一般而言,建議您儘可能以「最舊的」.NET Standard 版本為目標。In general, we recommend you to target the lowest version of .NET Standard possible. 因此,在您找到可作為目標的最新 .NET Standard 版本之後,請依照下列步驟操作:So, after you find the highest .NET Standard version you can target, follow these steps:

  1. 以次舊的 .NET Standard 版本為目標並建置您的專案。Target the next lower version of .NET Standard and build your project.
  2. 如果您的專案建置成功,便重複步驟 1。If your project builds successfully, repeat step 1. 否則,請將目標重新設定為次新版本,這會是您應該使用的版本。Otherwise, retarget to the next higher version and that's the version you should use.

不過,以較低的 .NET Standard 版本作為目標會產生數個支援相依性。However, targeting lower .NET Standard versions introduces a number of support dependencies. 如果您的專案是以 .NET Standard 1.x 為目標,我們建議同時以 .NET Standard 2.0 作為目標。If your project targets .NET Standard 1.x, we recommend that you also target .NET Standard 2.0. 這能為使用您的程式庫並執行與 .NET Standard 2.0 相容之架構的使用者簡化相依性關係圖,也能減少他們所需下載的套件數目。This simplifies the dependency graph for users of your library that run on .NET Standard 2.0 compatible frameworks, and it reduces the number of packages they need to download.

.NET Standard 版本控制規則.NET Standard versioning rules

有兩個主要的版本控制規則:There are two primary versioning rules:

  • 累加:.NET Standard 版本就邏輯而言是同心圓:較新的版本會包含來自較舊版本的所有 API。Additive: .NET Standard versions are logically concentric circles: higher versions incorporate all APIs from previous versions. 版本之間並沒有任何重大變更。There are no breaking changes between versions.
  • 固定:.NET Standard 在交付後,版本便已凍結。Immutable: Once shipped, .NET Standard versions are frozen. 新的 API 將先在特定的 .NET 實作 (例如 .NET Core) 中提供。New APIs first become available in specific .NET implementations, such as .NET Core. 如果 .NET Standard 審查委員會認為應該為所有 .NET 實作,提供新的 API,即會在新的 .NET Standard 版本中加入這些 API。If the .NET Standard review board believes the new APIs should be available for all .NET implementations, they're added in a new .NET Standard version.

規格Specification

.NET Standard 規格是一組標準化的 API。The .NET Standard specification is a standardized set of APIs. 此規格由 .NET 實作人員維護,具體而言即為 Microsoft (包括 .NET Framework、.NET Core 與 Mono) 和 Unity。The specification is maintained by .NET implementors, specifically Microsoft (includes .NET Framework, .NET Core, and Mono) and Unity. 透過 GitHub 建立新的 .NET Standard 版本時,會使用公開回饋程序。A public feedback process is used as part of establishing new .NET Standard versions through GitHub.

正式成品Official artifacts

正式規格是一組定義 API 的 .cs 檔案,這些 API 是標準的一部分。The official specification is a set of .cs files that define the APIs that are part of the standard. dotnet/standard 存放庫中的 ref 目錄定義 .NET Standard API。The ref directory in the dotnet/standard repository defines the .NET Standard APIs.

NETStandard.Library 中繼套件 (原始檔) 描述定義 (部分) 一或多個 .NET Standard 版本的程式庫集合。The NETStandard.Library metapackage (source) describes the set of libraries that define (in part) one or more .NET Standard versions.

像是 System.Runtime 等指定的元件,其描述:A given component, like System.Runtime, describes:

  • .NET Standard 的組件 (僅限其範圍)。Part of .NET Standard (just its scope).
  • 適用於該範圍的多個 .NET Standard 版本。Multiple versions of .NET Standard, for that scope.

為了更方便閱讀及支援特定開發人員案例 (例如使用編譯器),已提供衍生成品。Derivative artifacts are provided to enable more convenient reading and to enable certain developer scenarios (for example, using a compiler).

封裝表示Package representation

.NET Standard 參考組件的主要散發工具是 NuGet 套件The primary distribution vehicle for the .NET Standard reference assemblies is NuGet packages. 傳遞實作的方法有許多種,各自適合每種 .NET 實作。Implementations are delivered in a variety of ways, appropriate for each .NET implementation.

NuGet 套件是以一個或多個架構為目標。NuGet packages target one or more frameworks. .NET Standard 套件是以 ".NET Standard" 架構為目標。The .NET Standard packages target the ".NET Standard" framework. 您可使用 netstandard 壓縮 TFM (例如,netstandard1.4),以 .NET Standard 架構為目標。You can target the .NET Standard framework using the netstandard compact TFM (for example, netstandard1.4). 要在多個執行階段上執行的程式庫應以此架構為目標。Libraries that are intended to run on multiple runtimes should target this framework. 對大多數的 API 來說,會以 netstandard2.0 為目標,因為提供的 API 數目,超過 .NET Standard 1.6 與 2.0 之間的一倍。For the broadest set of APIs, target netstandard2.0 since the number of available APIs more than doubled between .NET Standard 1.6 and 2.0.

NETStandard.Library 中繼套件會參考定 .NET Standard 的完整一組 NuGet 套件。The NETStandard.Library metapackage references the complete set of NuGet packages that define .NET Standard. 若要將 netstandard 設為目標,最常見方式是參考這個中繼套件。The most common way to target netstandard is by referencing this metapackage. 它描述大約 40 種定義 .NET Standard 的 .NET 程式庫和相關 API,並提供其存取權。It describes and provides access to the ~40 .NET libraries and associated APIs that define .NET Standard. 您可以參考目標為 netstandard 的其他套件,以存取其他 API。You can reference additional packages that target netstandard to get access to additional APIs.

版本控制Versioning

此規格不是單一的,而是一組以累加方式擴充並以線性方式控制版本的 API。The specification is not singular, but an incrementally growing and linearly versioned set of APIs. 此標準的第一個版本會建立一組基準 API。The first version of the standard establishes a baseline set of APIs. 後續版本會新增 API,並繼承舊版所定義的 API。Subsequent versions add APIs and inherit APIs defined by previous versions. 沒有任何既定的佈建可從標準中移除 API。There is no established provision for removing APIs from the standard.

.NET Standard 並非專屬於任何一個 .NET 實作,也不符合任何這些執行階段的版本配置。.NET Standard is not specific to any one .NET implementation, nor does it match the versioning scheme of any of those runtimes.

新增至任何實作 (例如 .NET Framework、.NET Core 和 Mono) 的 API 都可視為要新增至規格的候選項目,尤其是如果本質上要作為基礎的 API。APIs added to any of the implementations (such as, .NET Framework, .NET Core and Mono) can be considered as candidates to add to the specification, particularly if they are thought to be fundamental in nature. 新的 .NET Standard 版本是根據 .NET 實作版本所建立,可讓您以來自 .NET Standard PCL 的新 API 為目標。New versions of .NET Standard are created based on .NET implementation releases, enabling you to target new APIs from a .NET Standard PCL. 如需版本控制機制的詳細資訊,請參閱 .NET Core 版本控制The versioning mechanics are described in more detail in .NET Core Versioning.

.NET Standard 版本控制對於使用至關重要。.NET Standard versioning is important for usage. 指定 .NET Standard 版本之後,您可以使用以相同版本或更舊版本為目標的程式庫。Given a .NET Standard version, you can use libraries that target that same or lower version. 下列方法描述使用 .NET Standard PCL (專門用於 .NET Standard 目標設定) 的工作流程。The following approach describes the workflow for using .NET Standard PCLs, specific to .NET Standard targeting.

  • 選取要用於 PCL 的 .NET Standard 版本。Select a .NET Standard version to use for your PCL.
  • 使用相依於相同 .NET Standard 版本或更舊版本的程式庫。Use libraries that depend on the same .NET Standard version or lower.
  • 如果您發現有程式庫相依於更新的 .NET Standard 版本,就需要採用該相同的版本,或決定不要使用該程式庫。If you find a library that depends on a higher .NET Standard version, you either need to adopt that same version or decide not to use that library.

以 .NET Standard 為目標Targeting .NET Standard

您可以搭配使用 netstandard 架構和 NETStandard.Library 中繼套件,來建置 .NET Standard 程式庫You can build .NET Standard Libraries using a combination of the netstandard framework and the NETStandard.Library metapackage. 您可以查看使用 .NET Core 工具將 .NET Standard 設為目標的範例。You can see examples of targeting the .NET Standard with .NET Core tools.

.NET Framework 相容性模式.NET Framework compatibility mode

從 .NET Standard 2.0 開始,引進了 .NET Framework 相容性模式。Starting with .NET Standard 2.0, the .NET Framework compatibility mode was introduced. 此相容性模式可讓 .NET Standard 專案可參考 .NET Framework 程式庫,就如同是為 .NET Standard 編譯一般。This compatibility mode allows .NET Standard projects to reference .NET Framework libraries as if they were compiled for .NET Standard. 並非所有專案都適合參考 .NET Framework 程式庫。例如,像是使用 Windows Presentation Foundation (WPF) API 的程式庫。Referencing .NET Framework libraries doesn't work for all projects, such as libraries that use Windows Presentation Foundation (WPF) APIs.

如需詳細資訊,請參閱 .NET Framework 相容模式For more information, see .NET Framework compatibility mode.

.NET Standard 程式庫與 Visual Studio.NET Standard libraries and Visual Studio

若要在 Visual Studio 中建置 .NET Standard 程式庫,請確定您已在 Windows 上安裝了 Visual Studio 2017 版本 15.3 或是更新版本,或是已在 macOS 上安裝了 Visual Studio for Mac 版本 7.1 或更新版本。In order to build .NET Standard libraries in Visual Studio, make sure you have Visual Studio 2017 version 15.3 or later installed on Windows, or Visual Studio for Mac version 7.1 or later installed on macOS.

若在您專案中只需要使用 .NET Standard 2.0 程式庫,也可於 Visual Studio 2015 中執行。If you only need to consume .NET Standard 2.0 libraries in your projects, you can also do that in Visual Studio 2015. 但需要安裝 NuGet 用戶端 3.6 或更新版本。However, you need NuGet client 3.6 or higher installed. 您可從 NuGet下載頁面,下載 Visual Studio 2015 的 NuGet 用戶端。You can download the NuGet client for Visual Studio 2015 from the NuGet downloads page.

與可攜式類別庫的比較Comparison to Portable Class Libraries

.NET Standard 會取代可攜式類別庫 (PCL).NET Standard is the replacement for Portable Class Libraries (PCL). .NET Standard 可透過策劃標準 BCL,進而在 .NET 實作之間建立更高的一致性,來改善建立可攜式程式庫的體驗。The .NET Standard improves on the experience of creating portable libraries by curating a standard BCL and establishing greater uniformity across .NET implementations as a result. 以 .NET Standard 為目標的程式庫是 PCL 或「.NET Standard 型 PCL」。A library that targets .NET Standard is a PCL or a ".NET Standard-based PCL". 現有的 PCL 是「設定檔型 PCL」。Existing PCLs are "profile-based PCLs".

.NET Standard 和 PCL 設定檔是為了類似的目的而建立,但也有幾點重要的不同之處。.NET Standard and PCL profiles were created for similar purposes but also differ in key ways.

相似之處:Similarities:

  • 定義可用於二進位程式碼共用的 API。Define APIs that can be used for binary code sharing.

不同之處:Differences:

  • .NET Standard 是一組經過策劃的 API,而 PCL 設定檔則是由現有平台的交集所定義。.NET Standard is a curated set of APIs, while PCL profiles are defined by intersections of existing platforms.
  • .NET Standard 是以線性方式控制版本,而 PCL 設定檔則不是。.NET Standard linearly versions, while PCL profiles do not.
  • PCL 設定檔代表 Microsoft 平台,而 .NET Standard 則代表平台不明。PCL profiles represents Microsoft platforms while the .NET Standard is platform-agnostic.

PCL 相容性PCL compatibility

.NET Standard 與 PCL 設定檔子集相容。.NET Standard is compatible with a subset of PCL profiles. .NET Standard Library 1.0、1.1 和 1.2 會各自與一組 PCL 設定檔重疊。.NET Standard 1.0, 1.1 and 1.2 each overlap with a set of PCL profiles. 建立此重疊的原因有兩個:This overlap was created for two reasons:

  • 可讓 .NET Standard 型 PCL 參考設定檔型 PCL。Enable .NET Standard-based PCLs to reference profile-based PCLs.
  • 可將設定檔型 PCL 封裝成 .NET Standard 型 PCL。Enable profile-based PCLs to be packaged as .NET Standard-based PCLs.

Microsoft.NETCore.Portable.Compatibility NuGet 套件提供設定檔型 PCL 相容性。Profile-based PCL compatibility is provided by the Microsoft.NETCore.Portable.Compatibility NuGet package. 參考包含設定檔型 PCL 的 NuGet 套件時需要此相依性。This dependency is required when referencing NuGet packages that contain profile-based PCLs.

封裝成 netstandard 的設定檔型 PCL,會比一般封裝的設定檔型 PCL 更容易使用。Profile-based PCLs packaged as netstandard are easier to consume than typically packaged profile-based PCLs. 現有的使用者可以使用 netstandard 封裝。netstandard packaging is compatible with existing users.

您會看到與 .NET Standard 相容的 PCL 設定檔集合:You can see the set of PCL profiles that are compatible with the .NET Standard:

PCL 設定檔PCL Profile .NET Standard.NET Standard PCL 平台PCL Platforms
Profile7Profile7 1.11.1 .NET Framework 4.5、Windows 8.NET Framework 4.5, Windows 8
Profile31Profile31 1.01.0 Windows 8.1、Windows Phone Silverlight 8.1Windows 8.1, Windows Phone Silverlight 8.1
Profile32Profile32 1.21.2 Windows 8.1、Windows Phone 8.1Windows 8.1, Windows Phone 8.1
Profile44Profile44 1.21.2 .NET Framework 4.5.1、Windows 8.1.NET Framework 4.5.1, Windows 8.1
Profile49Profile49 1.01.0 .NET Framework 4.5、Windows Phone Silverlight 8.NET Framework 4.5, Windows Phone Silverlight 8
Profile78Profile78 1.01.0 .NET Framework 4.5、Windows 8, Windows Phone Silverlight 8.NET Framework 4.5, Windows 8, Windows Phone Silverlight 8
Profile84Profile84 1.01.0 Windows Phone 8.1、Windows Phone Silverlight 8.1Windows Phone 8.1, Windows Phone Silverlight 8.1
Profile111Profile111 1.11.1 .NET Framework 4.5、Windows 8, Windows Phone 8.1.NET Framework 4.5, Windows 8, Windows Phone 8.1
Profile151Profile151 1.21.2 .NET Framework 4.5.1、Windows 8.1、Windows Phone 8.1.NET Framework 4.5.1, Windows 8.1, Windows Phone 8.1
Profile157Profile157 1.01.0 Windows 8.1、Windows Phone 8.1、Windows Phone Silverlight 8.1Windows 8.1, Windows Phone 8.1, Windows Phone Silverlight 8.1
Profile259Profile259 1.01.0 .NET Framework 4.5、Windows 8、Windows Phone 8.1、Windows Phone Silverlight 8.NET Framework 4.5, Windows 8, Windows Phone 8.1, Windows Phone Silverlight 8

另請參閱See also