深刻理解.NET Core的基元: deps.json, runtimeconfig.json, dll文件

原文连接： Deep-dive into .NET Core primitives: deps.json, runtimeconfig.json, and dll's
做者： Nate McMaster

C#编译器(The C# Compiler)

C#的编译器能够将cs文件转换为dll文件, 即程序集文件。程序集文件是一个便携的可执行格式文件, 借助.NET Core,它能够运行在Windows, MacOS和Linux系统中。

在Windows系统中, .NET Core的编译器文件csc.dll存放在如下目录中

C:\Program Files\dotnet\sdk\[.NET Core 版本号]\Roslyn\bincore

笔者使用了2.1.400版本，因此编译器存放目录是C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore

.NET Core编译器文件csc.dll也是一个.NET Core应用程序，因此你可使用dotnet命令直接执行编译器

C:\test>dotnet C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore\csc.dll --help

下面咱们尝试手动编译一个cs文件。
首先咱们先建立一个Program.cs文件，内容以下：

/* Program.cs */
class Program
{
    static void Main(string[] args)
        => System.Console.WriteLine("Hello World!");
}

而后咱们使用命令行命令将其编译

C:\test>dotnet "C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore\csc.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Runtime.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Console.dll" 
-out:Program.dll 
Program.cs

参数说明

• "C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore\csc.dll"是编译器所在的路径
• -reference参数表示编译中须要引用的dll, 该参数能够指定多个dll , 例子中咱们引用了System.Runtime.dll和System.Console.dll
• -out参数表示编译生成的dll路径
• Program.cs表示编译的源文件地址

Program.cs编译成功, Program.dll生成完毕。

runtimeconfig.json

对于.NET Core应用程序来讲runtimeconfig.json是不可或缺的。它是用来配置运行时的。

若是缺乏了这个文件，运行dll文件的时候会产生如下异常。

C:\test>dotnet Program.dll
A fatal error was encountered. The library 'hostpolicy.dll' required to execute the application was not found in '........'

这句话的意思是.NET Core缺乏指定组件来运行程序。
为了解决这个问题，咱们能够添加一个Program.runtimeconfig.json, 其内容以下

{
  "runtimeOptions": {
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "2.1.2"
    }
  }
}

这里的配置dotnet命令将使用Microsoft.NETCore.App做为共享框架(Shared Framework)。当dotnet命令运行的时候，它会去runtimeconfig.json中读取版本号，而后去C:\Program Files\dotnet\shared\[库名]\[版本号]目录下，搜索对应的dll文件

如今咱们从新运行上面的命令，结果以下：

C:\test>dotnet Program.dll
Hello world!

Hello World被正确输出了。

包(Package)

包(Package)是.NET中共享代码的一种方式。在.NET中，包的格式是nupkg, nupkg文件是一个ZIP压缩文件, 里面包含了.NET程序集和一个包含元数据的xml文件
。

在.NET中，最著名的包是JSON.NET, 又称Newtonsoft.Json.它提供了一个JSON序列化和反序列化的API。咱们能够从NuGet.org中下载最新版本11.0.2的nupkg文件，并解压放置在咱们当前的代码目录的packages\Newtownsoft.Json\11.0.2子目录下。

为了演示如何手动导入包来编译项目, 咱们修改Program.cs, 输出一个序列化以后的对象, 代码以下：

class Program
{
    static void Main(string[] args)
      => System.Console.WriteLine(
          Newtonsoft.Json.JsonConvert.SerializeObject(new { greeting = "Hello World!" }));
}

而后咱们使用以下命令，编译Program.cs

C:\test>dotnet "C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore\csc.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Runtime.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Console.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Collections.dll" 
-reference:.\packages\Newtonsoft.Json\11.0.2\lib\netstandard1.3\Newtonsoft.Json.dll 
-out:Program.dll 
Program.cs

这里为何要引入System.Collections.dll呢?
缘由是咱们在代码中使用了匿名类型new { greeting = "Hello World!" }, 对于匿名类型， C#编译器会为其生成一个.Equals的方法, 这个方法调用了定义在System.Collections.dll中 的System.Collections.Generic.EqualityComparer 方法

编译成功，可是会出现一些警告(Warning)

Program.cs(4,35): warning CS1701: Assuming assembly reference 'System.Runtime, Version=4.0.20.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' used by 'Newtonsoft.Json' matches identity 'System.Runtime, Version=4.2.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' of 'System.Runtime', you may need to supply runtime policy

这意味着.Newtonsoft.Json的做者建立Newtonsoft.Json.dll时，是使用4.0.20.0的System.Runtime程序集, 可是系统当前使用的System.Runtime程序集是4.2.0.0版本的。编译器警告你4.0.20.0和4.2.0.0版本能够有很大的差别。不过幸运的是，这些差别都是向后兼容的(all backwards comptible), 因此Newtonsoft.Json.dll能够正常工做。若是想去除这个警告，咱们可使用-nowarn:CS1701

C:\test>dotnet "C:\Program Files\dotnet\sdk\2.1.400\Roslyn\bincore\csc.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Runtime.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Console.dll" 
-reference:"C:\Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.0\ref\netcoreapp2.1\System.Collections.dll" 
-reference:.\packages\Newtonsoft.Json\11.0.2\lib\netstandard1.3\Newtonsoft.Json.dll 
-nowarn:CS1701 
-out:Program.dll 
Program.cs

动态连接(Dynamic Link)

在上一步中，咱们编译了一个引用了Newtonsoft.Json.dll的.NET Core程序，在引用Newtonsoft.Json.dll以前，代码能够正常运行，可是引用Newtownsoft.Json.dll以后，程序运行失败。

C:\test> dotnet Program.dll
Unhandled Exception: System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=10.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed'. The system cannot find the file specified.

.NET是一个动态连接的运行时。编译器会为Program.dll程序集添加Newtonsoft.Json.dll的引用，可是不会复制它的代码。.NET Core运行时指望在Program.dll运行的时候，动态查找并加载一个Newtonsoft.Json.dll文件。这一点对于System.Runtime.dll, System.Console.dll以及其余System.*的程序集也是同样。

.NET Core能够配置查找Newtonsoft.Json.dll文件的目录范围，这里咱们先简单的将Newtownsoft.Json.dll拷贝到与Program.dll相同的目录中, 而后从新运行Program.dll

C:\test>copy .\packages\Newtonsoft.Json\11.0.2\lib\netstandard1.3\Newtonsoft.Json.dll Newtonsoft.Json.dll
C:\test>dotnet Program.dll
{"greeting":"Hello World!"}

咱们预期的结果出现了。

注意：这里不须要拷贝System.Runtime.dll和System.Console.dll, 缘由是他们存在于Microsoft.NETCore.App共享框架中，咱们已经在runtimeconfig.json中配置过了。

deps.json

正如上一节所说的.NET Core能够配置查找动态连接程序集的位置。
这些位置包括：

• 应用程序根目录（这个不须要配置）
• 包缓存目录
• 优化过的的包缓存或者运行时包商店
• 服务索引
• 共享框架（配置在runtimeocnfig.json中）

deps.json是一个记录.NET Core中依赖清单的文件。它能够用来配置动态连接的程序集。

deps.json文件中定义了动态连接的依赖列表。一般这个文件在Visual Studio中是自动生成，并且在生产环境中也会很是的大。可是它确实是一个纯文本文件，因此咱们可使用任何编辑器编写它。

下面咱们手动添加一个Program.deps.json, 代码以下：

{
  "runtimeTarget": {
    "name": ".NETCoreApp,Version=v2.1"
  },
  "targets": {
    ".NETCoreApp,Version=v2.1": {
      "Newtonsoft.Json/11.0.2": {
        "runtime": {
          "lib/netstandard1.3/Newtonsoft.Json.dll": {}
        }
      }
    }
  },
  "libraries": {
    "Newtonsoft.Json/11.0.2": {
      "type": "package",
      "serviceable": false,
      "sha512": ""
    }
  }
}

如今咱们删除以前拷贝过来的Newtonsoft.Json.dll, 而后从新运行Program.dll

C:\test>del Newtonsoft.Json.dll
C:\test>dotnet Program.dll
Error:
  An assembly specified in the application dependencies manifest (Program.deps.json) was not found:
    package: 'Newtonsoft.Json', version: '11.0.2'
    path: 'lib/netstandard1.3/Newtonsoft.Json.dll'

因而可知，尽管咱们添加了deps.json, .NET Core依然须要一些其余的信息来探测deps.json中定义的动态程序集。
这里有3种方式来设置，你能够选中一行任意一种方式设置搜索动态连接库的目录路径，修改以后，{"greeting":"Hello World!"}就会正常输出出来。

*.runtimeconfig.dev.json

这种一种方式是最佳的实现方式.咱们能够添加一个Program.runtimeconfig.dev.json,并在其中添加动态连接搜索目录字段additionalProbingPaths

{
   "runtimeOptions": {
     "additionalProbingPaths": [
       "/Users/nmcmaster/code/packages/"
     ]
   }
 }

注解：这里的配置相似于Transformed Config, 若是指定当前的环境是dev,它就会读取Program.runtimeconfig.json, 并将Program.runtimeconfig.dev.json的内容覆盖进去

命令行

咱们仍是可使用dotnet exec命令并指定--additionalprobingpath参数来配置检索的目录。

C:\test> dotnet exec --additionalprobingpath ./packages/ Program.dll

*.runtimeconfig.json

固然你也能够直接在*.runtimeconfig.json中添加additionalProbingPaths字段

{
   "runtimeOptions": {
     "framework": {
       "name": "Microsoft.NETCore.App",
       "version": "2.1.2"
     },
     "additionalProbingPaths": [
       "./packages/"
     ]
   }
 }

本篇源代码

参考文献

• Specs on runtimeconfig.json and deps.json
• Packages, metapackages and frameworks
• .NET Core application deployment
• The implementation of the shared framework lookup