In-depth understanding of .NET Core primitives (three) - in-depth understanding of runtimeconfig.json

Original: Deep-dive into .NET Core primitives , part 3: runtimeconfig.json in depth
Author: Nate McMaster
translation: in-depth understanding of primitive .NET Core (c) - deeply runtimeconfig.json
Translator: Lamond Lu

Antecedent Review

• In-depth understanding of .NET Core primitives (a): deps.json, runtimeconfig.json, dll file
• .NET Core depth understanding of primitives (II): sharing framework
• In-depth understanding of .NET Core primitives (III): in-depth understanding of runtimeconfig.json

Brief introduction

Each .NET Core applications include a named xxxx.runtimeconfig.jsonfile. This file can be used to control a variety of configurations. Most of the developers really not too concerned about this file, because it is generated by the SDK file, but I think it is worth us to learn to understand what the. This file is used to control not show up in Visual Studio in some configurations, such as running your application is using a later version of .NET Core, adjust the thread pool and garbage collection.

The role of file

Technically, runtimeconfig.jsonthe file is not required, but due to some practical factors, so .NET Core applications for each real world has to hold a runtimeconfig.jsonfile. This file can be manually edited. And deps.jsonfile different, runtimeconfig.jsonis easy to understand. The main role of this document is shared framework needed to define the program (only for FDD - framework-dependency deployment), as well as some other options for running, I will list them below.

A simple example

The following is one of the most typical of runtimeconfig.jsonthe contents of the file.

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "2.1.0"
    }
  }
}

I have written a complete structure of the runtimeconfig.jsonfile, if you are interested you can check <https://gist.github.com/natemcmaster/0bdee16450f8ec1823f2c11af880ceeb> .

runtimeconfig.template.json

In .NET Core, there are some configuration options, you are not in the project file .csprojsettings. If you want to configure these options are set, there are two options, one is after the project is compiled, manually edit the runtimeconfig.jsonfile, another is to use the runtimeconfig.template.jsonfile. Of course, if you want to configure persistence, I recommend the way you use the template.

When the project build (build) of, SDK will be from the .csprojconfiguration file on the basis of, by reading the template expansion. Here we have to use the template through a few simple steps.

1. Create a new project dotnet new console -n MyApp( )

2. In the current project directory, create a named runtimeconfig.template.jsonfile.

3. Configuration file as follows

   {
      "rollForwardOnNoCandidateFx": 2
   }

4. carried outdotnet build

Look, nothing more. Now we can look at bin/Debug/netacoreapp.21/MyApp.runtimeconfig.jsonto make sure the template work properly.

Visual Studio IntelliSense

For Visual Studio editor, I have written a JSON structure, you can directly use. You need to do is put the following code into your current project runtimeconfig.template.jsonfile can be.

{
  "$schema": "https://gist.githubusercontent.com/natemcmaster/0bdee16450f8ec1823f2c11af880ceeb/raw/runtimeconfig.template.schema.json"
}

Runtime Configuration Options

Framework, version, previously scrolling mechanism

.NET Core Framework supports shared install a parallel version, therefore, when a .NET Core application starts, you must choose a version. The following configuration options are commonly used to configure the application sharing framework which should be loaded, and which version of the shared framework to load.

Note: In general, the default SDK generated configuration has been good enough, but sometimes we need to change them in order to solve common problems when .NET Core start.

It was not possible to find any compatible framework version. The specified framework ‘Microsoft.NETCore.App’, version ‘X.Y.Z’ was not found.

Sharing framework

.NET Core is to specify a shared framework by specifying the name of the shared frame. Specified in the configuration framework version is the lowest version of the current application in use. If you can not figure it changed to cover this minimum configuration file, the only way is to use the dotnet exec --fx-versioncommand.

In the following version 3.0 of the .NET Core, you can only specify a shared framework.

JSON

{
  "runtimeOptions": {
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "2.2.0"
    }
  }
}

.csproj

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

For .NET Core 3.0 and above has support for multi-sharing framework, so additional shared framework is no longer needed as a reference to the package.

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>

Automatically run the program later .NET Core

This is a .NET Core 3.0 is a new configuration option.

By default, .NET Core will go to try to find the highest share patched version of the current framework. If you can not find this version, it will use 前滚(roll-forward) feature to check for a newer version. This option is subject to 前滚the control strategy.

JSON

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

.csproj

The current .csprojproject file is not implemented in this configuration.

You can https://github.com/dotnet/designs/blob/master/accepted/runtime-binding.md find this specification configuration. For this configuration, the official design documents, made the following description

RollForwardThere are several optional parameters about the value:

• LatestPatch - Former rolled up to a patched version, the smallest version of the roll characteristics of this configuration will be disabled before configuration.
• Minor- In the absence of minor version required to roll forward to the lowest minor version. If the minor version of the request exist, the LatestPatchpolicy
• Major- If the main version of the required missing, then roll forward to the minimum major version, minor version and the lowest. If the major version request exist, the Minorpolicy
• LatestMinor - roll forward to the highest minor version, minor version exists even if the current request
• LatestMajor - Former major version and rolled up to the highest minor version, major versions exist even if the current request
• Disable- Former NA roll characteristics. Bind only the specified version. In most scenarios, this strategy is not recommended, because the ability to roll the latest version of the patch before it disables. This is recommended only way to do the testing.

MinorThe default value is currently configured. If you want more information, you can refer to the official documentation .

In the above configuration values, in addition Disableto the options, other options are going to choose the highest patched version is available.

Note: LatestMinorand LatestMajorComponent Managed (e.g. managed COM component) is applied to the non-managed and hosting

Automatically use higher version of the patch to run the project (versions prior to 3.0 .NET Core)

As described above, using this policy in .NET Core 3.0 is not recommended, but recommended a more simple "roll forward" option.

By default, .NET Core will be installed on the target machine using the highest patched version of the shared framework to run the program. You can use applyPatchesthe parameters to disable this feature.

JSON

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

.csproj

The current .csprojproject file is not implemented in this configuration.

Automatic highest major version or a minor version to run the project (versions prior to 3.0 .NET Core)

As described above, using this policy in .NET Core 3.0 is not recommended, but recommended a more simple "roll forward" option.

By default, .NET Core attempts to automatically find the highest patch version of a shared framework, the same version of the main and minor versions and applications you are currently running the specified version. But, if not, it will automatically roll forward to the latest version. This configuration is controlled by the roll-forward strategy.

JSON

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

.csproj

The current .csprojproject file is not implemented in this configuration.

The value of this parameter can be set to 0,1,2. You can view the detailed design document for more details.

For example, when the specified time frame version 2.1.0, .NET Core The value of this parameter will be determined using the following framework compatible version.

rollForwardOnNoCandidateFx	Compatible version of the framework
0	>=2.1.0, < 2.2.0
1 (default)	>=2.1.0, < 3.0.0
2	>=2.1.0

Target Frame Name

This is the implementation details of a package store runtime.

JSON

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.1"
  }
}

.csproj

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

Assembly detection path

The host can use this parameter to specify additional folders to find the .deps.jsonfile listed in the assembly file. You can view a series of articles of the first chapter to see how this argument works.

JSON

{
  "runtimeOptions": {
    "additionalProbingPaths": [
      "C:\\Users\\nmcmaster\\.nuget\\packages\\"
    ]
  }
}

.csproj

<ItemGroup>
  <AdditionalProbingPath Include="$(USERPROFILE)\.nuget\packages" />
</ItemGroup>

Note: The .csprojconfiguration items will eventually appear in the runtimeconfig.dev.jsonfile, the file is used only during development, but will not be used in a production environment. For a production environment, you can use the template file to set runtimeconfig.json.

Runtime Configuration

configPropertiesProperties are key / value pairs list to run. Basically you can think of configuration settings here, but the most commonly used configuration is generally a few below.

JSON

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

Common runtime configuration

Configuration Name	Types of	description
System.GC.Server	Boolean	Whether to enable server garbage collection
System.GC.Concurrent	Boolean	Whether to enable concurrent garbage collection
System.GC.RetainVM	Boolean	Whether that should be deleted segment into a standby list for future use, instead of releasing it back to the operating system.
System.Runtime.TieredCompilation	Boolean	Are hierarchical compilation enabled
System.Threading.ThreadPool.MinThreads	Integer	Minimum number of threads in the thread pool cover
System.Threading.ThreadPool.MaxThreads	Integer	The maximum number of threads in the thread pool cover
System.Globalization.Invariant	Boolean	Constant mode is enabled, disabled globalization behavior

The following are some of the documentation for the above configuration

• Host Configuration Switch (Host Configuration Knobs)
• Globalization constant mode
• Hierarchical compilation

These configurations, you can put your .csprojfiles. If you want more configuration, the best solution is to view the Microsoft.NET.Sdk.targetsfile.

<PropertyGroup>
  <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
  <ServerGarbageCollection>true</ServerGarbageCollection>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
  <ThreadPoolMinThreads>1</ThreadPoolMinThreads>
  <ThreadPoolMaxThreads>100</ThreadPoolMaxThreads>
  <!-- Supported as of .NET Core SDK 3.0 Preview 1 -->
  <TieredCompilation>true</TieredCompilation>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

Other running configuration time

In addition to the configuration provided by the framework, .NET Core also allows developers to specify your own configuration. You can System.AppContext.GetDataacquire these values method.

Note: Compared to the Configuration Builder (Configuration Builders), this approach is not particularly recommended.

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>

In C #, by System.AppContext.GetDataacquiring the value of the designated parameter method

// "red"
var color = System.AppContext.GetData("ArbitraryStringSetting") as string;

More information

You can view this series first chapter to learn runtimeconfig.jsonmore details of the file, and how to use it. Likewise, I recommend you go through the official document file to find out how to configure these variables to use.