.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

09-04 15:23