深刻理解.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開發人員來講，瞭解背後的原理是一件好事，但願本文是對共享框架功能的良好概述。我儘量的關聯了一些官網文檔和指南，以便你能夠找到更多的信息。若是還有其餘問題，請在下面發表評論。