.NET Core run-time configuration settings

.NET Core supports the use of configuration files and environment variables to configure the behavior of .NET Core applications at run time. Run-time configuration is an attractive option if:

  • You don't own or control the source code for an application and therefore are unable to configure it programmatically.

  • Multiple instances of your application run at the same time on a single system, and you want to configure each for optimum performance.

Note

This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either open an issue to let us know about it, or submit a pull request to address the issue. For information about submitting pull requests for the dotnet/docs repository, see the contributor's guide.

.NET Core provides the following mechanisms for configuring run-time application behavior:

Some configuration values can also be set programmatically by calling the AppContext.SetSwitch method.

The articles in this section of the documentation are organized by category, for example, debugging and garbage collection. Where applicable, configuration options are shown for runtimeconfig.json files, MSBuild properties, environment variables, and, for cross-reference, app.config files for .NET Framework projects.

runtimeconfig.json

When a project is built, an [appname].runtimeconfig.json file is generated in the output directory. If a runtimeconfig.template.json file exists in the same folder as the project file, any configuration options it contains are merged into the [appname].runtimeconfig.json file. If you're building the app yourself, put any configuration options in the runtimeconfig.template.json file. If you're just running the app, insert them directly into the [appname].runtimeconfig.json file.

Note

The [appname].runtimeconfig.json file will get overwritten on subsequent builds.

Specify run-time configuration options in the configProperties section of the runtimeconfig.json files. This section has the form:

"configProperties": {
  "config-property-name1": "config-value1",
  "config-property-name2": "config-value2"
}

Example [appname].runtimeconfig.json file

If you're placing the options in the output JSON file, nest them under the runtimeOptions property.

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "3.1.0"
    },
    "configProperties": {
      "System.GC.Concurrent": false,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

Example runtimeconfig.template.json file

If you're placing the options in the template JSON file, omit the runtimeOptions property.

{
  "configProperties": {
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

MSBuild properties

Some run-time configuration options can be set using MSBuild properties in the .csproj or .vbproj file of SDK-style .NET Core projects. MSBuild properties take precedence over options set in the runtimeconfig.template.json file. They also overwrite any options you set in the [appname].runtimeconfig.json file at build time.

Here is an example SDK-style project file with MSBuild properties for configuring run-time behavior:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
    <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
    <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
  </PropertyGroup>

</Project>

MSBuild properties for configuring run-time behavior are noted in the individual articles for each area, for example, garbage collection.

Environment variables

Environment variables can be used to supply some run-time configuration information. Configuration knobs specified as environment variables generally have the prefix COMPlus_.

You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling the Environment.SetEnvironmentVariable(String, String) method on both Windows and Unix-based systems.

The following examples show how to set an environment variable at the command line:

# Windows
set COMPlus_GCRetainVM=1

# Powershell
$env:COMPlus_GCRetainVM="1"

# Unix
export COMPlus_GCRetainVM=1