.NET5.0 单文件发布打包操作深度剖析

前言

随着 .NET5.0 Preview 8 的发布，许多新功能正在被社区成员一一探索；这其中就包含了“单文件发布”这个炫酷的功能，实际上，这也是社区一直以来的呼声，从 WinForm 的 msi 开始，我们就希望有这样一个功能，虽然在 docker 时代，单文件发布的功能显得“不那么重要”，但正是从这一点可以看出，.NET 的团队成员一直在致力于实用功能的完善。

在 Java 的世界里，单文件发布一直伴随着他们的成长，War 文件可以直接上传到 Tomcat 上运行，话说我们还是有那么一丢丢的羡慕的，不过凡事有利就有弊，单文件发布对于细分模块的热更新来说，还有有一点点的不方便。

不过瑕不掩瑜，在微服务概念越来越火热的今天，相信单文件发布的功能带给大家更多的是兴奋。

什么是单文件发布

首先，我们要清楚的了解，什么是单文件发布。

官方的目标定义：

.Net 5.0单个文件解决方案应为：

广泛兼容：可以将包含IL程序集，随时运行的程序集，复合程序集，本机二进制文件，配置文件等的应用程序打包为一个可执行文件。
可以直接从打包软件直接运行应用程序的托管组件，而无需提取到磁盘。
可与调试器和工具一起使用。

从上面的目标可以看出，和以往版本最大的不同在于：将所有依赖打包到一个可执行文件中，可直接运行，不影响调试操作。

注意上面的这句话“将所有依赖打包到一个可执行文件中”，而在以往，我们使用 dotnet publish 将应用程序进行发布之后，我们会看到，在 publish 下有许多项目依赖的 dll 文件，在 .NET5.0 到来之后，这些依赖文件可收纳到一个文件中，瞬间让人感受到了清凉。

发布操作指令相关

命令

可选参数

配置文件设置参数

除了可以使用命令行参数的形式，还可以通过配置文件的形式设置发布参数，编辑项目文件，添加配置节点到文件中并保存即可。

<PropertyGroup>
  <TargetFramework>net5.0</TargetFramework>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
  <PublishSingleFile>true</PublishSingleFile>
  <IncludeContentInSingleFile>true</IncludeContentInSingleFile>
</PropertyGroup>

关于 RID 说明见：https://docs.microsoft.com/en-us/dotnet/core/rid-catalog

这是截止本文发布前的 RID 版本，不排除 .NET5.0 有新的发布

其它参数

除了上面的三个可选参数，我在查询文档的过程中还发现，官方还提到了其它参数的使用，目前不确定是否有效

<PropertyGroup>
  <SelfContained>true</SelfContained>
  <!--启用使用assemby修剪-仅支持自包含应用程序-->
  <PublishTrimmed> true </PublishTrimmed>
  <!--启用AOT编译 目前暂不支持预编译-->
  <!--<PublishReadyToRun>true</PublishReadyToRun>-->
</PropertyGroup>
<ItemGroup>
  <Content Update="*-exclute.dll">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
  </Content>
</ItemGroup>

还可以通过设置 ExcludeFromSingleFile 元素，该设置将指定某些文件不嵌入单个文件之中。

编写待打包的应用程序

为了更直观的看出正常发布和单文件发布的区别，我们特别准备了一个 Web 应用程序，并对两个程序集进行依赖引用。

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

准备好项目，编译成功，尝试发布，打开 PowerShel 控制台，分别输入以下命令

dotnet publish -r linux-x64 /p:PublishSingleFile=true
dotnet publish -r win-x64 --self-contained=false /p:PublishSingleFile=true

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

linux-x64 和 win-x64 两个目录下，分别有 publish 目录，由于平台的不同，所引用的依赖也不一样，这是我们早就了解过的，我们看看打包前后的区别

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

以上执行的两条命令语句，会为我们生成 Linux 和 Windows 两个平台的程序包，从上图中可以看出，在打包之前，项目的各种引用依赖都被复制到了发布目录下，这也是我们之前的程序发布方式，在经过打包后，所有依赖文件都被装入了一个可执行文件中，在 Linux 平台下表现为：PreviewWebApplication ，Windows 平台下则为：PreviewWebApplication.exe。从打包效果来看，迁移将变得更加方便了。

运行打包程序

打包后的程序和未打包的发布程序在运行方式上没有太多的差异性，在 Windows 平台上，只需要双击 PreviewWebApplication.exe 就可以运行该打包程序了，本示例创建的是一个 WebApi 的程序，直接访问程序侦听的地址后得到接口返回的结果，如果您创建的是带有 Razor 视图或者携带其它资源文件的，可能无法访问指定的 url。

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

在程序成功运行起来后，我们发现，打包程序并没有解压缩文件到磁盘，而是直接从包中加载文件到内存中运行；这是巨大的进步，也是和 War 文件根本的区别。

需要注意的是，该 .exe 文件并不能单独复制到别的地方运行，你必须把 .exe 当前目录完整的复制才能运行，这涉及到主机探测的问题，下面我们将会一一提到。

跨平台的打包文件

通过上面的示例我们了解到，打包程序总是为不同的平台生成独立的包程序，这是为什么呢？这里就涉及到一个概念，也就是 Tool Interface Standard (TIS)

Executable and Linking Format(ELF)

Common Object File Format（COFF）于1983年引入，最初使用在 AT&T 的 UNIX 系统上。由于 COFF 的各种局限性，比如：节的最大数量受到限制，节名称，所包含的源文件的长度受到限制，并且符号调试信息无法支持实际的语言。最后，在 System V Release 4 (SVR4) 发布后，AT&T 使用 ELF 替代了 COFF。

ELF 文件结构又分为三种类型，分别是：

Portable Executable (PE)

在 Windows 阵营，微软在此 COFF 标准的基础上，又进行了创新和发展出了 PE 文件标准

从上面的两种规范中可以看出，LinuX 和 Windows 都有各自的文件格式规范，而这种规范在一定程度上是不兼容的，不论是从文件结构还是解析方式；所以 .NET5.0 中的打包程序必须为不同的平台实现独立的打包器。打包器的实现在 runtime 中的 Microsoft.NET.HostModel 库中。

认识了 ELF 和 PE 文件结构之后，我们就可以对打包器代码进行阅读理解。

Microsoft.NET.HostModel

你可以从 github 上下载 .NET 5.0 的源代码，转到目录：

runtime/src/installer/managed/Microsoft.NET.HostModel

源码不太多，可直接进行阅读，主要理解层次关系即可。

打包器主要包含了三大部分的内容，分别是 AppHost、Bundler、ComHost

在文件 Bundle/Manifest.cs 的头部，我们看到了“单文件程序”的文件结构定义

 BundleManifest is a description of the contents of a bundle file.
 This class handles creation and consumption of bundle-manifests.

 Here is the description of the Bundle Layout:
 _______________________________________________
 AppHost


------------Embedded Files ---------------------
The embedded files including the app, its
configuration files, dependencies, and
possibly the runtime.







------------ Bundle Header -------------
    MajorVersion
    MinorVersion
    NumEmbeddedFiles
    ExtractionID
    DepsJson Location [Version 2+]
       Offset
       Size
    RuntimeConfigJson Location [Version 2+]
       Offset
       Size
    Flags [Version 2+]
- - - - - - Manifest Entries - - - - - - - - - - -
    Series of FileEntries (for each embedded file)
    [File Type, Name, Offset, Size information]



_________________________________________________

从上面的文件结构中，我们可以非常清晰的看到，单文件程序的结构一共分为三大部分，分别是：

文件头信息的查看

我们可以通过一些工具去查看已经打包好的文件，在 Linux 下，可以使用 readelf/objdump 等程序来获取 PreviewWebApplication 文件的信息。在 Windows 下，可以使用 PE Tools 等工具

Linux 下 readelf 读取文件头信息

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

从图中我们可以看到 Type:DYN (Shared object file) 这是一个标准的共享对象文件，关于 ELF 头部信息的内容不再展开，有兴趣的同学可以自行学习相关内容。

Windows下 PE Tools 读取文件头信息

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

已经打包好的程序内部包含了 319（Linux）、Windows（359）个文件，Windows 版本在未打包前是 84.3MB，打包后是 69.8MB，最重要的是在运行时无需解压缩，直接从 Bundle 中运行文件。

文件中的第三部分，也就是 “实体清单（Manifest Entries）的写入代码在 Bundle\Bundler.cs\AddToBundle

long AddToBundle(Stream bundle, Stream file, FileType type)
{
    if (type == FileType.Assembly)
    {
        long misalignment = (bundle.Position % AssemblyAlignment);
        if (misalignment != 0)
        {
            long padding = AssemblyAlignment - misalignment;
            bundle.Position += padding;
        }
    }
    file.Position = 0;
    long startOffset = bundle.Position;
    file.CopyTo(bundle);
    return startOffset;
}

在成员方法 GenerateBundle(IReadOnlyList fileSpecs) 内部迭代调用了 AddToBundle 方法，完成了实体清单文件的写入。

// 代码片段

public string GenerateBundle(IReadOnlyList<FileSpec> fileSpecs)
{
  ...
 foreach (var fileSpec in fileSpecs)
  {
      string relativePath = fileSpec.BundleRelativePath;
      ...
      using (FileStream file = File.OpenRead(fileSpec.SourcePath))
      {
          FileType targetType = Target.TargetSpecificFileType(type);
          long startOffset = AddToBundle(bundle, file, targetType);
          FileEntry entry = BundleManifest.AddEntry(targetType, relativePath, startOffset, file.Length);
          Tracer.Log($"Embed: {entry}");
      }
  }

  // Write the bundle manifest
  headerOffset = BundleManifest.Write(writer);
  ...
}

因为解压器的实现已经转移到了 HostFxr 和 HostPolicy 中，以静态链接库的方式链接到打包器中，且该部分代码由 C++ 进行编写，鉴于 C++ 水平有限，在这里不作介绍。

结束语

编写这篇文章耗费了我大量的时间，期间大量阅读海量的参考资料、文献、标准文档、制作文章配图等等，写干货文章真的需要投入巨大的精力和时间，希望你们喜欢。

文章进行到这里，我知道肯定还有很多同学没看过瘾，但是我们可以通过回顾打包器的开发进度表来体验一下 .NET 团队的开发热情。

.NET5.0 单文件发布打包操作深度剖析-LMLPHP

主要参考资料

.NET团队计划经理 Richard Lander 的博客：https://devblogs.microsoft.com/dotnet/announcing-net-5-0-preview-8/Bundler 进度表：https://github.com/dotnet/runtime/issues/36590single-file：https://github.com/dotnet/designs/tree/master/accepted/2020/single-fileELF文档：https://refspecs.linuxbase.org/elf/elf.pdfELF维基百科：https://en.wikipedia.org/wiki/Executable_and_Linkable_FormatReadelf：https://sourceware.org/binutils/docs/binutils/readelf.htmlPE文档：https://docs.microsoft.com/en-us/windows/win32/debug/pe-formatPE Tools：https://github.com/petoolse/petools

Ron.liang