关于 .Net Core runtimeconfig 文件说明

  在项目的bin\debug\netcoreapp${Version}下面能够找到这个${AppName}.runtimeconfig.json文件，简单来说，它就是用来定义应用程序所用的共享框架（.Net Core App）以及运行时选项 的一个文件。

   一个简单的例子

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.2",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "2.2.0"
    }
  }
}

1、用来决定以哪个版本的.net core 来启动应用程序的参数

runtimeconfig.json

{
  "runtimeOptions": {
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "2.2.0"  //指的是可运行的最低版本
    }
  }
}

.csproj 文件中

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" Version="2.2.0" />
</ItemGroup>

覆盖最小值（不更改文件）的方法是使用dotnet exec --fx--version

 

到.Net Core >= 3.0 的时候， 可以使用多个共享框架，并且不再作为Nuget包引用，原先做为Nuget包显示，但实际上并不由Nuget来管理，有可能是开发团队设计上的一个失误。

runtimeconfig.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 3.0 会自动在更高的版本上运行

默认情况下， 会自动匹配主要和次要版本号，在其中找到最高的版本来运行，但如果找不到的话，它就有可能会去找更高的版本来运行，也可以回退以适应缺少特定运行时环境，下面的rollForward选项可以配置策略，在 这儿 可以找到一些说明

runtimeconfig.json

{
  "runtimeOptions": {
    "rollForward": "Major" 
  }
}

 rollForward 可用的值

LatestPatch	前滚到最高的补丁版本，但这会禁用次要版本前滚
Minor	默认使用的值，如果缺少请求的次要版本，请前滚到最低的较高次要版本； 如果存在请求的次要版本，则使用 LatestPatch 策略。
Major	如果请求主要版本缺失，则前滚至最低的较高主要版本和最低次要版本。 如果存在请求的主要版本，则使用 Minor 策略。
LatestMinor	即使请求的次要版本存在，也可以前滚到最高次要版本。
LatestMajor	即使请求主要版本存在，也可以前滚到最高主要和最高次要版本。
Disable	不要向前滚动，仅绑定到指定的版本，不建议将此策略用于正常用途， 因为它禁用前滚到最新修补程序的功能，建议仅用于测试。

 

在.NET Core 3.0之前，默认情况下会使用安装在计算机上的最高补丁版本的 .Net Core 运行，可以使用如下配置来禁用

注意，此配置在.Net Core 3.0之后已经被废弃

runtimeconfig.json

{
  "runtimeOptions": {
    "applyPatches": false
  }
}

 

在.NET Core 3.0之前，如果在计算机上找不适合的 .Net Core 版本（匹配主要和次要版本号，默认情况下最高补丁版本），他有可能会使用计算机上安装的最新版本，通过以下配置来控制

注意，此配置在.Net Core 3.0之后已经被废弃

runtimeconfig.json

  {

  "runtimeOptions": {
    "rollForwardOnNoCandidateFx": 1
  }
}

举个例子说明下，如果当前 .Net Core Version = 2.10

rollForwardOnNoCandidateFx的值	可兼容的.Net Core版本
0	>=2.1.0, < 2.2.0
1	默认的 >=2.1.0, < 3.0.0
2	>=2.1.0

 

 

详细说明可参考这篇文章 Roll Forward On No Candidate Fx

 

2：运行时包存储区

这是包在磁盘上的存储目录（通常情况下，在 macOS/Linux 上是 /usr/local/share/dotnet/store，在 Windows 上是 C:/Program Files/dotnet/store）

runtimeconfig.json

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.1"  //tfm: target framework
  }
}

.csproj

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>

 

 3：从其他地方加载Assembly的路径（类似于PrivatePath）

runtimeconfig.json

{
  "runtimeOptions": {
    "additionalProbingPaths": [
      "D:\\Project\\XXXX"
    ]
  }
}

.csproj

<ItemGroup>
  <AdditionalProbingPath Include="D:\Project\XXX" />
</ItemGroup>

.csproj只会影响到runtimeconfig.dev.json，这个文件只会在开发的时候有用，到生产环境无效了，这儿要注意

 

4：运行时设置

这是一个Key Value 键值对的设置，可以用来配Thread Pool Size， AppDomain ，Globalization 等的行为 ，详细可以参考 CLR-Configuration-knobs

runtimeconfig.json

{
  "runtimeOptions": {
    "configProperties": {
      "key": "value"
    }
  }
}

 

 

除了Net Core 中已定义的，如果需要，也可以配置一些自定义的项，参考如下

runtimeconfig.json

{
  "runtimeOptions": {
    "configProperties": {
      "DefaultTheme": "blue",
      "DefaultLanguage": "zh-CN",
      "IsEnableJwt" : true
    }
  }
}

.csproj 

<ItemGroup>
  <RuntimeHostConfigurationOption Include="DefaultTheme" Value="blue" />
  <RuntimeHostConfigurationOption Include="DefaultLanguage" Value="zh-CN" />
  <RuntimeHostConfigurationOption Include="IsEnableJwt" Value="true" />
</ItemGroup>

C# 获取自定义的值

var defaultTheme = System.AppContext.GetData("DefaultTheme") as string;