.NET Standard.NET Standard

.NET Standard 是一套正式的 .NET API 规范,有望在所有 .NET 实现中推出。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 基类库 (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:

  • 为要实现的所有 .NET 实现定义一组统一的、与工作负荷无关的 BCL API。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 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.1 2018 年 1 月2018.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. 在这一行中从右向左查找可以定位的 .NET Standard 版本所在的列。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 评审委员会认为新 API 应可用于所有 .NET 实现,则会将它们添加到新的 .NET Standard 版本中。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 文件。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 设定为目标,因为 .NET Standard 2.0 的可用 API 数量比 .NET Standard 1.6 的两倍还多。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 库及定义 .Net Standard 的相关 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 StandardTargeting .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 client 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 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.

基于配置文件的 PCL 兼容性由 Microsoft.NETCore.Portable.Compatibility NuGet 包提供。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.

与以常规方式打包的基于配置文件的 PCL 相比,打包为 netstandard 的基于配置文件的 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