關於 .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;