原文:Deep-dive into .NET Core primitives, part 3: runtimeconfig.json in depth
作者:Nate McMaster[1]
前情回顾
- 深入理解.NET Core 的基元(一):deps.json, runtimeconfig.json, dll 文件[2]
- 深入理解.NET Core 的基元(二):共享框架[3]
简介
每个.NET Core 应用都包含了一个名为xxxx.runtimeconfig.json
的文件。这个文件可以用来控制多种配置。大多数的开发人员其实并不太关心这个文件,因为它是由 SDK 生成的文件,但是我认为它还是值得我们去学习理解一下的。这个文件常用来控制一些不会在 Visual Studio 中表现出来的配置,例如在使用更高版本的.NET Core 运行你的应用程序,调整线程池和垃圾回收等。
文件的作用
从技术上讲,runtimeconfig.json
文件并不是必须的,但是由于一些实践性的因素,所以每个真实世界中的.NET Core 应用都有持有一个runtimeconfig.json
文件。这个文件是可以手动编辑的。与deps.json
文件不同,runtimeconfig.json
是易于理解的。这个文件的主要作用是定义程序所需的共享框架(只针对 FDD - framework-dependency deployment
),以及一些其他的运行时选项,我会在后面一一列举。
一个简单的例子
以下是一个最典型的runtimeconfig.json
的文件内容。
{
"runtimeOptions": {
"tfm": "netcoreapp2.1",
"framework": {
"name": "Microsoft.NETCore.App",
"version": "2.1.0"
}
}
}
我已经编写了一个完整结构的runtimeconfig.json
文件,如果有兴趣你可以查看[5]。
runtimeconfig.template.json
在.NET Core 中,有一些配置选项,你是不能在项目文件.csproj
中设置的。如果你想对这些配置选项进行设置,这里有两种方案,一种是在项目编译之后,手动编辑runtimeconfig.json
文件,另外一种是使用runtimeconfig.template.json
文件。当然,如果你希望持久化配置, 我还是推荐你使用模板的方式。
当项目构建(build)的时候,SDK 会从在.csproj
文件的基础上,通过读取模板扩充配置。下面我们就通过简单的几个步骤来使用模板。
- 创建一个新项目(
dotnet new console -n MyApp
) - 在当前项目目录中,创建一个名为
runtimeconfig.template.json
的文件。 - 配置文件内容如下
{
"rollForwardOnNoCandidateFx": 2
}
- 执行
dotnet build
瞧,仅此而已。现在我们可以查看一下bin/Debug/netacoreapp.21/MyApp.runtimeconfig.json
,以确保模板正常工作。
Visual Studio 的智能感知
针对 Visual Studio 编辑器,我已经编写了一个 JSON 结构,你可以直接使用。你需要做的,只是将如下代码加入到你当前项目的runtimeconfig.template.json
文件中即可。
{
"$schema": "https://gist.githubusercontent.com/natemcmaster/0bdee16450f8ec1823f2c11af880ceeb/raw/runtimeconfig.template.schema.json"
}
运行时配置选项
框架、版本、先前滚动机制
.NET Core 共享框架支持安装并行版本,因此,当一个.NET Core 应用程序启动时候,必须选择一个版本。以下配置选项常用于配置应用应该加载哪些共享框架,以及加载哪个版本的共享框架。
注意:通常来说 SDK 默认生成的配置就已经够用了,但是有时候我们还是需要更改他们的,以解决.NET Core 启动时常见问题。
It was not possible to find any compatible framework version. The specified framework ‘Microsoft.NETCore.App’, version ‘X.Y.Z’ was not found.
共享框架
.NET Core 是通过指定共享框架的名称来指定共享框架的。配置中指定的框架版本,是当前应用使用的最低版本。如果你想不通过更改文件覆盖这个最小值配置,唯一的方式是使用dotnet exec --fx-version
命令。
在.NET Core 3.0 以下版本中,一次只能指定一个共享框架。
JSON
{
"runtimeOptions": {
"framework": {
"name": "Microsoft.AspNetCore.App",
"version": "2.2.0"
}
}
}
.csproj
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" Version="2.2.0" />
ItemGroup>
对于.NET Core 3.0 及以上版本中已经支持多共享框架,所以额外的共享框架不再需要作为包来引用了。
JSON
{
"runtimeOptions": {
"frameworks": [
{
"name": "Microsoft.AspNetCore.App",
"version": "3.0.0"
},
{
"name": "Microsoft.WindowsDesktop.App",
"version": "3.0.0"
}
]
}
}
.csproj
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
<FrameworkReference Include="Microsoft.WindowsDesktop.App" />
ItemGroup>
自动使用更高版本.NET Core 运行程序
这个是.NET Core 3.0 中的一个新配置选项。
默认,.NET Core 会去尝试寻找当前共享框架的,最高修补版本。如果找不到这个版本,它会使用前滚
(roll-forward)特性,来查找较新的版本。这个选项受前滚
策略的控制。
JSON
{
"runtimeOptions": {
"rollForward": "Major"
}
}
.csproj
当前.csproj
项目文件中还没有实现这个配置。
你可以在https://github.com/dotnet/designs/blob/master/accepted/runtime-binding.md[6]中找到这个配置的规范。针对这个配置,官方设计文档中,做了如下描述
RollForward
参数有以下几个可选值:
LatestPatch
- 前滚到最高修补版本,这个配置会禁用前滚特性的最小版本配置。Minor
- 如果缺少所需的次要版本,就前滚到最低的次要版本。如果请求的次要版本存在,则使用LatestPatch
策略Major
- 如果缺少所需的主要版本,则前滚到最低的主要版本,和最低的次要版本。如果请求的主要版本存在,则使用Minor
策略LatestMinor
- 前滚到最高次要版本,即使当前请求的次要版本存在LatestMajor
- 前滚到最高主要版本和最高次要版本,即使当前请求的主要版本存在Disable
- 不适用前滚特性。只绑定指定版本。在大多数场景下,这个策略都是不推荐的,因为它会禁用前滚到最新修补版本的能力。这种方式仅推荐来做测试工作。
Minor
是当前配置的默认值。如果希望了解更多信息,可以参阅官方文档[7]。在以上配置值中,除了
Disable
选项之外,其他的选项都是会去选择最高的可用修补版本。注意:
LatestMinor
和LatestMajor
适用于托管和非托管中主机的组件托管(例如托管 COM 组件)
自动使用更高的补丁版本运行项目(.NET Core 3.0 之前的版本)
正如上面所描述的,在.NET Core 3.0 中不推荐使用此策略,而推荐使用更简单的"前滚"选项。
默认情况下,.NET Core 会使用安装在目标机器中最高修补版本的共享框架运行程序。你可以使用applyPatches
参数禁用此功能。
JSON
{
"runtimeOptions": {
"applyPatches": false
}
}
.csproj
当前.csproj
项目文件中还没有实现这个配置。
自动使用最高主版本或次要版本来运行项目(.NET Core 3.0 之前的版本)
正如上面所描述的,在.NET Core 3.0 中不推荐使用此策略,而推荐使用更简单的"前滚"选项。
默认情况下,.NET Core 会尝试自动查找共享框架的最高补丁版本,该版本的主版本和次要版本和你当前运行的应用所指定的版本相同。但是,如果找不到,它会自动前滚到最新版本。此配置受前滚策略控制。
JSON
{
"runtimeOptions": {
"rollForwardOnNoCandidateFx": 1
}
}
.csproj
当前.csproj
项目文件中还没有实现这个配置。
这个参数的值,可以设置为 0,1,2。你可以查看详细的设计文档[8],了解更多详情。
例如,当指定的框架版本是 2.1.0 时,.NET Core 会根据这个参数的值,决定使用如下的兼容框架版本。
rollForwardOnNoCandidateFx | 兼容的框架版本 |
0 |
|
1 (默认) |
|
2 |
|
目标框架名称
这是一个运行时程序包存储的实现细节。
JSON
{
"runtimeOptions": {
"tfm": "netcoreapp2.1"
}
}
.csproj
<PropertyGroup>
<TargetFramework>netcoreapp2.1TargetFramework>
PropertyGroup>
程序集探测路径
宿主程序可以使用这个参数来指定额外的文件夹,以查找.deps.json
文件中列举的程序集文件。你可以查看系列文章的第一篇[9]来查看这个参数是如何工作的。
JSON
{
"runtimeOptions": {
"additionalProbingPaths": [
"C:\\Users\\nmcmaster\\.nuget\\packages\\"
]
}
}
.csproj
<ItemGroup>
<AdditionalProbingPath Include="$(USERPROFILE)\.nuget\packages" />
ItemGroup>
注意:
.csproj
中的配置项最终只会出现在runtimeconfig.dev.json
文件中,该文件仅在开发过程中使用,而不会在生产环境中使用。针对生产环境,你可以使用模板文件来设置runtimeconfig.json
。
运行时配置
configProperties
属性是提供给运行时的键/值对列表。基本上你能想到的配置,在这里都设置,但是最常使用的配置一般是如下几个。
JSON
{
"runtimeOptions": {
"configProperties": {
"key": "value"
}
}
}
常用的运行时配置
配置名称 | 类型 | 描述 |
System.GC.Server | 布尔 | 是否启用服务器垃圾回收 |
System.GC.Concurrent | 布尔 | 是否启用并发垃圾回收 |
System.GC.RetainVM | 布尔 | 是否将应删除的段放入一个备用列表中以备将来使用,而不是将其释放回操作系统。 |
System.Runtime.TieredCompilation | 布尔 | 是否启用分层编译 |
System.Threading.ThreadPool.MinThreads | 整型 | 覆盖线程池的最小线程数 |
System.Threading.ThreadPool.MaxThreads | 整型 | 覆盖线程池的最大线程数 |
System.Globalization.Invariant | 布尔 | 是否启用不变模式,禁用全球化行为 |
以下是一些针对上述配置的文档说明
- 主机配置开关(Host Configuration Knobs)[10]
- 全球化不变模式[11]
- 分层编译[12]
这些配置,你都可以放在你的.csproj
文件中。如果你想了解更多相关配置,最好的方案就是去查看Microsoft.NET.Sdk.targets
文件。
<PropertyGroup>
<ConcurrentGarbageCollection>trueConcurrentGarbageCollection>
<ServerGarbageCollection>trueServerGarbageCollection>
<RetainVMGarbageCollection>trueRetainVMGarbageCollection>
<ThreadPoolMinThreads>1ThreadPoolMinThreads>
<ThreadPoolMaxThreads>100ThreadPoolMaxThreads>
<TieredCompilation>trueTieredCompilation>
<InvariantGlobalization>trueInvariantGlobalization>
PropertyGroup>
其他运行时配置
除了框架提供的配置,.NET Core 还允许开发人员指定自己的配置。你可以通过System.AppContext.GetData
方法来获取这些值。
注意:相较于配置构建器(Configuration Builders), 这个方式并不是特别推荐。
JSON
{
"runtimeOptions": {
"configProperties": {
"ArbitraryNumberSetting": 2,
"ArbitraryStringSetting": "red",
"ArbitraryBoolSetting": true
}
}
}
.csproj
<ItemGroup>
<RuntimeHostConfigurationOption Include="ArbitraryNumberSetting" Value="2" />
<RuntimeHostConfigurationOption Include="ArbitraryStringSetting" Value="red" />
<RuntimeHostConfigurationOption Include="ArbitraryBoolSetting" Value="true" />
ItemGroup>
在 C#中,通过System.AppContext.GetData
方法来获取指定参数的值
// "red"
var color = System.AppContext.GetData("ArbitraryStringSetting") as string;
更多信息
你可以通过查看本系列的第一章[13]来了解runtimeconfig.json
文件的更多详情,以及如何使用它。同样,我也推荐你通过官方的文档文件[14]来了解一下这些变量配置是如何使用的。