.NET Runtime configuration settings
.NET 5+ (including .NET Core versions) supports the use of configuration files and environment variables to configure the behavior of .NET applications.
Note
The articles in this section concern configuration of the .NET Runtime itself. If you're migrating an app from .NET Framework to .NET and are looking for a replacement for the app.config file, or if you simply want a way to use custom configuration values in your .NET app, see the Microsoft.Extensions.Configuration.ConfigurationBuilder class and Configuration in .NET.
Using these settings 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.
.NET provides the following mechanisms for configuring behavior of the .NET runtime:
Tip
Configuring an option by using an environment variable applies the setting to all .NET apps. Configuring an option in the runtimeconfig.json or project file applies the setting to that application only.
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 inserted 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.
- If your app's
OutputType
is notExe
and you want configuration options to be copied from runtimeconfig.template.json to [appname].runtimeconfig.json, you must explicitly setGenerateRuntimeConfigurationFiles
totrue
in your project file. For apps that require a runtimeconfig.json file, this property defaults totrue
.
Specify runtime configuration options in the configProperties section of the runtimeconfig.json or runtimeconfig.template.json file. 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": "net8.0",
"framework": {
"name": "Microsoft.NETCore.App",
"version": "8.0.0"
},
"configProperties": {
"System.Globalization.UseNls": true,
"System.Net.DisableIPv6": true,
"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.Globalization.UseNls": true,
"System.Net.DisableIPv6": true,
"System.GC.Concurrent": false,
"System.Threading.ThreadPool.MinThreads": "4",
"System.Threading.ThreadPool.MaxThreads": "25"
}
}
MSBuild properties
Some runtime configuration options can be set using MSBuild properties in the .csproj or .vbproj file of SDK-style .NET projects. MSBuild properties take precedence over options set in the runtimeconfig.template.json file.
For runtime configuration settings that don't have a specific MSBuild property, you can use the RuntimeHostConfigurationOption
MSBuild item instead. Use the runtimeconfig.json setting name as the value of the Include
attribute.
Here is an example SDK-style project file with MSBuild properties for configuring the behavior of the .NET runtime:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
<PropertyGroup>
<ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
<ThreadPoolMinThreads>4</ThreadPoolMinThreads>
<ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
</PropertyGroup>
<ItemGroup>
<RuntimeHostConfigurationOption Include="System.Globalization.UseNls" Value="true" />
<RuntimeHostConfigurationOption Include="System.Net.DisableIPv6" Value="true" />
</ItemGroup>
</Project>
MSBuild properties for configuring the behavior of the runtime are noted in the individual articles for each area, for example, garbage collection. They're also listed in the Runtime configuration section of the MSBuild properties reference for SDK-style projects.
Environment variables
Environment variables can be used to supply some runtime configuration information. Configuration knobs specified as environment variables generally have the prefix DOTNET_.
Note
.NET 6 standardizes on the prefix DOTNET_
instead of COMPlus_
for environment variables that configure .NET run-time behavior. However, the COMPlus_
prefix will continue to work. If you're using a previous version of the .NET runtime, you should still use the COMPlus_
prefix for environment variables.
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 DOTNET_GCRetainVM=1
# Powershell
$env:DOTNET_GCRetainVM="1"
# Unix
export DOTNET_GCRetainVM=1
See also
Atsauksmes
https://aka.ms/ContentUserFeedback.
Drīzumā: 2024. gada laikā mēs pakāpeniski pārtrauksim izmantot “GitHub problēmas” kā atsauksmju par saturu mehānismu un aizstāsim to ar jaunu atsauksmju sistēmu. Papildinformāciju skatiet:Iesniegt un skatīt atsauksmes par