深入理解.NET Core的基元（二） - 共享框架

原文：Deep-dive into .NET Core primitives, part 2: the shared framework

作者：Nate McMaster

译文：深入理解.NET Core的基元（二） - 共享框架

作者： Lamond Lu

本篇是之前翻译过的《深入理解.NET Core的基元: deps.json, runtimeconfig.json, dll文件》的后续，这个系列作者暂时只写了3篇，虽然有一些内容和.NET Core 3.0已经不兼容了，但是大部分的原理还都是相通的，所以后面的第三篇我也会翻译。

• 深入理解.NET Core的基元（一）：deps.json, runtimeconfig.json, dll文件
• 深入理解.NET Core的基元（二）：共享框架
• 深入理解.NET Core的基元（三）：深入理解runtimeconfig.json

前言

自.NET Core 1.0起，共享框架(Shared Framework)就已经成为了.NET Core的重要组成部分。自.NET Core 2.1起，ASP.NET Core就已经作为共享框架的第一次出现。你可能从来注意过这一点，但是在设计它的时候，我们经历了许多反复和持续的讨论。在本篇文章中，我们将深入共享框架并讨论一些开发人员经常遇到的一些陷阱。

基础部分

.NET Core应用可以在两种模式下运行， 分别是框架依赖模式(Framework - Dependent) 和独立运行模式（Self Contained) 。在我的Macbook上，一个最小的可独立运行的ASP.NET Core网站应用，大约拥有350个文件，文件大小总共是93MB。相对的，一个最小的框架依赖应用，大约5个文件，文件大小总共239KB。

你可以如下命令行生成基于两种不同模式的应用。

dotnet new web
dotnet publish --runtime osx-x64 --output bin/self_contained_app/
dotnet publish --output bin/framework_dependent_app/

当程序运行的时候，他们的功能是一样的。那么这两种模式有什么区别么？其实正如官网文档中的解释：

框架依赖部署(framework-dependant deployment) 依赖目标中安装的.NET Core共享组件。独立部署（self-contained deployment）不依赖目标系统中安装的共享组件，程序所需的所有组件都已经包含在当前应用程序中。

这篇官方文档（https://docs.microsoft.com/en-us/dotnet/core/deploying/）中很好的解释了不同模式的优势。

PS: 作者当时写这边文章的时候, 没有引入Framework-dependent executables (FDE)，有兴趣的同学可以自行查看。

共享框架

这里，简单的说，.NET Core的共享框架就是一个程序集（*.dll文件）集合的目录，这些程序集不需要出现在你的.NET Core的应用目录中。这个目录是.NET Core的共享系统范围版本的一部分，通常你可以在C:\Program Filres\dotnet\shared中发现它。

当你运行dotnet.exe WebApi1.dll命令时，.NET Core宿主程序会

• 尝试发现你的应用依赖的程序集名称和版本
• 在某些固定位置中尝试查找该程序集

这些程序集可以在许多不同的位置被发现了，包含且不限于共享框架。在我之前的文章中，我主要解释了如果通过deps.json和runtimeconfig.json文件配置宿主程序的行为。希望了解更多的同学，可以查看那篇文章。

.NET Core宿主程序会读取*.runtimeconfig.json文件来确定加载哪个版本的共享框架。这个文件的内容类似：

{
  "runtimeOptions": {
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "2.1.1"
    }
  }
}

这里，共享框架名称只是一个名字。按照约定，这个名字应该是以.App结尾的，但是实际上它可以是任何字符串，例如"FooBananaShark"。

对于共享框架的版本，这里只是配置了一个最低的版本。.NET Core宿主程序会根据配置，加载对应版本的共享框架，或者更高版本的共享框架，但是它永远不会加载比指定版本低的共享框架。

那么，我到底安装了哪些共享框架呢？

运行dotnet --list-runtimes, 你就可以看到你电脑中安装了哪些共享框架，以及它们的版本和文件位置。

对比Microsoft.NETCore.App, AspNetCore.App以及AspNetCore.All

这里，以.NET Core 2.2为例。

框架名称	描述
Microsoft.NETCore.App	基础运行时。它主要提供了System.Object、List<T>、string类，以及内存管理，文件管理，网络I/O, 线程管理等功能
Microsoft.AspNetCore.App	默认Web运行时。它主要提供了使用API创建Web服务器的功能，这里主要包含Kestral, Mvc, SignalR, Razor, 以及EF Core的部分功能。
Microsoft.AspNetCore.All	与第三方的集成库。它追加了EF Core + Sqlite的支持，以及一些扩展功能， 例如Redis, Azure Key Valut等。（在.NET Core 3.0中已经不再使用）

共享框架与Nuget包的关系

.NET Core SDK生成了runtimeconfig.json文件。在.NET Core 1和2中，SDK使用了项目配置中的两部分来确定runtimeconfig.json文件中框架部分内容。

• MicrosoftNETPlatformLibrary属性。对于所有.NET Core项目，它默认是Microsoft.NETCore.App。
• Nuget包管理工具的还原结果集，结果集中可能包含了相同名称的包

这里针对所有的.NET Core项目， .NET Core SDK都会添加一个隐式的包来引用Microsoft.NETCore.App。ASP.NET Core通过修改默认配置MicrosoftNETPlatformLibrary, 将其改为Microsoft.AspNetCore.App。

但是这里需要注意，Nuget包管理工具不提供任何共享框架!不提供任何共享框架! 不提供任何共享框架! 重要的事情说三遍^_。Nuget包管理工具只提供编译器使用的一些API，以及少量SDK。共享框架的获取来源可以是运行时安装器 https://aka.ms/dotnet-download， 或者捆绑在Visual Studio中，Docker镜像中，以及一些Azure服务器中。

版本前滚策略

正如我上面提到的，runtimeconfig.json只是指定了一个最小版本。实际使用的版本会依赖于一个版本前滚策略（详细内容可以参阅官方文档。例如

• 如果应用使用的共享框架最小版本是2.1.0, 那么程序最高会加载的共享框架版本是2.1.*。

针对这一部分，可以参见《深入理解.NET Core的基元（三）：深入理解runtimeconfig.json》

作者：《深入理解.NET Core的基元（三）：深入理解runtimeconfig.json》后续会补上

分层的共享框架

在.NET Core 2.1版本中引入了分层共享框架的特性。

共享框架可以依赖于其他共享框架。引入此特性是为了支持ASP.NET Core, 这个特性可以将程序包的运行时存储转换为一个共享框架。

如果你查看一下$DOTNET_ROOT/shared/Microsoft.AspNetCore.All/$version/文件夹，你会发现一个名为Microsoft.AspNetCore.All.runtimeconfig.json的文件，其内容如下

$ cat /usr/local/share/dotnet/shared/Microsoft.AspNetCore.All/2.1.2/Microsoft.AspNetCore.All.runtimeconfig.json
{
  "runtimeOptions": {
    "tfm": "netcoreapp2.1",
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "2.1.2"
    }
  }
}

多级检索

在.NET Core 2.0中引入了多级检索特性。

宿主程序在启动时会探查多个位置，以寻找合适的共享框架。程序首先会查找dotnet根目录，即包含一个dotnet.exe可执行文件的目录。这里我们可以通过配置DOTNET_ROOT的环境变量来覆盖此配置。根据此配置，程序检索的第一个目录是：

$DOTNET_ROOT/shared/$name/$version

如果这个目录不存在，宿主程序会尝试使用多级检索机制，检索预定的全局路径列表。这个机制可以通过设置全局变量DOTNET_MULTILEVEL_LOOKUP=0来关闭。默认情况下，预定的全局路径列表如下：

OS	Location
Windows	C:\Program Files\dotnet (64位进程) C:\Program Files (x86)\dotnet (32位进程) (查看源代码)
macOS	/usr/local/share/dotnet (查看源代码)
Unix	/usr/share/dotnet (查看源代码)

最终宿主程序会在找到的全局目录中检索以下目录

$GLOBAL_DOTNET_ROOT/shared/$name/$version

ReadyToRun特性

共享框架中的程序集，都是经过crossgen工具预优化过的。使用这个工具可以生成"ReadyToRun"版本的程序集，这些程序集都是针对指定操作系统和CPU架构优化过的。这里主要的性能提升是，减少了JIT在启动时准备代码所花费的时间。

Crossgen相关文档：https://github.com/dotnet/coreclr/blob/v2.1.3/Documentation/building/crossgen.md

一些陷阱

我相信每个.NET Core程序员都会遇到以下陷阱中的一部分。我将尽力解释这些问题是如何产生的。

Http Error 502.5 Process Failure

到目前为止，开发人员，最常遇到的陷阱是在IIS中或者Azure Web Services中托管ASP.NET Core应用程序。这个问题通常发生在开发人员升级了一个项目，或者当应用部署的时候，目标机器没有更新。这个错误的真正原因通常是应用所需版本的共享框架找不到，导致.NET Core应用程序无法正常启动。当dotnet无法启动应用程序时，IIS会返回HTTP 502.5的错误，但是不会显示内部的错误消息。

"The specified framework was not found"

It was not possible to find any compatible framework version
The specified framework 'Microsoft.AspNetCore.App', version '2.1.3' was not found.
  - Check application dependencies and target a framework version installed at:
      /usr/local/share/dotnet/
  - Installing .NET Core prerequisites might help resolve this problem:
      http://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409
  - The .NET Core framework and SDK can be installed from:
      https://aka.ms/dotnet-download
  - The following versions are installed:
      2.1.1 at [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
      2.1.2 at [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]

这个错误通常出现在HTTP 502.5错误之后，或者Visual Studio Test Explorer故障。

如上所述，当runtimeconfig.json文件指定了一个框架名称和版本，但是经过多级检索特性和前滚策略之后，主机依然无法找到一个合适的框架版本的时候，就会出现以上错误。

升级Microsoft.AspNetCore.App程序集的Nuget包

Microsoft.AspNetCore.App程序集的Nuget包，并不提供共享框架。它只是提供了C#/F#编译器使用的一些API以及少量SDK. 所以你必须要单独下载并安装共享框架。

同时，由于前滚策略，你并不需要更新Nuget包的版本，来让你的程序运行在新版本的共享框架中。

这可能是ASP.NET Core团队的一个设计失误，我们无法将共享框架作为Nuget包出现在项目文件中。共享框架所提供的程序包并不是通常意义上的程序包。与大部分程序包不同，它们不是自给自足的。我们希望当项目使用<PackageReference>时，Nuget能够安装所需的所有引用，但是令人沮丧的是，这些特殊程序包的设计偏离我们期望的模式。当然，现在我们已经得到了各种建议来解决这个问题。我希望它能早日实现。

在ASP.NET Core 2.1的新项目模板和文档中，微软向开发人员展示了，他们只需要在项目文件中添加如下的一行代码。

<PackageReference Include="Microsoft.AspNetCore.App" />

其他的<PackageReference>引用代码都必须要包含Version属性。只有当项目文件是以<Project Sdk="Microsoft.NET.Sdk.Web">开头的，那么以上这句与版本无关的程序包引用才会起作用，并且这里只对Microsoft.AspNetCore.{App, All}程序集包起作用。Web SDK将根据项中的其他配置, 例如：<TargetFramework>和<RuntimeIdentifier>， 来自动选择一个合适的程序包版本。

如果你在包引用的部分加入的Version属性，并指定了版本，或者你没有使用Web SDK作为项目文件的开头，则无法使用此功能。这里我很难推荐一个好的解决方案，因为最好的实现方式是基于你对此的理解水平和项目类型的。

发布修剪（Publish Trimming）

当你使用dotnet publish命令发布一个框架依赖的应用时，SDK会使用Nuget的还原结果（restore result)来决定哪些程序集应该出现在发布目录中。有一些程序集是通过Nuget程序集包拷贝的，而有一些就不是，因为他们已经出现在共享框架中。

这很容易产生一些错误，因为ASP.NET Core作为共享框架和Nuget程序包都是可用的。项目发布修剪特性会尝试通过图形数学来检查依赖传递，以及升级等，并以此选择正确的程序包文件。

下面我们以如下的项目引用为例：

<PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.1" />
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.9" />

MVC实际上是Microsoft.AspNetCore.App的一部分，但是当调用dotnet publish命令发布项目后，你会发现你的项目选用了升级后的Microsoft.AspNetCore.Mvc.dll程序包，这个程序包比Microsoft.AspNetCore.App中包含的2.1.1版本要高，所以最终Microsoft.AspNetCore.Mvc.dll会被拷贝到发布目录中。

这就不太理想了，因为随着你的应用程序大小不断增长，你永远得不到ReadyToRun优化版本的Microsoft.AspNetCore.Mvc.dll。

PS： 这个问题以前很少注意到，不过真的很常见。

混淆目标框架的别称与共享框架

如果简单认为"netcoreapp2.0" == "Microsoft.NETCore.App, v2.0.0", 你就大错特错了。目标框架别称(Target Framework Moniker简称TFM)只通过项目文件中<TargetFramework>节点指定的。"netcoreapp2.0"只是希望以人类友好的方式来表达你要使用哪个版本的.NET Core。

TFM的陷阱在于它的名称太短了。它不能表达出多种共享框架，特定补丁的版本控制，版本前滚，输出类型以及是独立发布还是框架依赖发布等内容。SDK会尝试从TFM推断许多设置，但是无法推断所有内容。

所以，更准确的说“netcoreapp2.0”意味着"Microsoft.NETCore.App v2.0.0及以上版本"。

混淆项目配置

最后一个陷阱和项目配置有关。在这里有很多术语和配置名称，它们不总是一致的。这些术语非常令人困惑，因此，如果混淆了这些术语，也没有关系，那不是你的错。

下面，我就列出一些常见的项目设置及其实际含义。

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
  <!--
    实际意义:
      * 从Nuget包解析编译引用时使用的API集合的版本
  -->

  <TargetFrameworks>netcoreapp2.1;net471</TargetFrameworks>
  <!--
    实际意义:
      * 使用两个不同的API集合版本进行编译。但这并不代表多层共享框架
  -->

  <MicrosoftNETPlatformLibrary>Microsoft.AspNetCore.App</MicrosoftNETPlatformLibrary>
  <!--
    实际意义:
      * 最顶层的共享框架名称
  -->

  <RuntimeFrameworkVersion>2.1.2</RuntimeFrameworkVersion>
  <!--
    实际意义:
      * 指定了Microsoft.AspNetCore.App程序包的版本，这个版本就是最小的共享框架版本
  -->

  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <!--
    实际意义:
      * 操作系统种类 + CPU架构
  -->

  <RuntimeIdentifiers>win-x64;win-x86</RuntimeIdentifiers>
  <!--
    实际意义:
      * 运行此项目可能使用的操作系统种类和CPU架构列表，你必须要通过RuntimeIdentifier配置选择其中一个
  -->

</PropertyGroup>

<ItemGroup>

  <PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.2" />
  <!--
    实际意义:
      * 使用Microsoft.AspNetCore.App作为共享框架
      * 最低版本2.1.2
  -->

  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.2" />
  <!--
    实际意义:
      * 引用Microsoft.AspNetCore.Mvc程序包
      * 实际版本2.1.2
  -->

  <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <!--
    实际意义:
      * 使用Microsoft.AspNetCore.App作为共享框架.
  -->

</ItemGroup>

总结

共享框架作为.NET Core的可选功能，尽管存在缺陷，但是我认为对于绝大部分用户来说，这是一个合理的默认设置。我依然认为对于.NET Core开发人员来说，了解背后的原理是一件好事，希望本文是对共享框架功能的良好概述。我尽可能的关联了一些官网文档和指南，以便你可以找到更多的信息。如果还有其他问题，请在下面发表评论。