.NET 运行时设置

.NET 5+（包括 .NET Core 版本）支持使用配置文件和环境变量在运行时配置 .NET 应用程序的行为。如果出现以下情况，则运行时配置是一个不错的选择：

• 你不拥有或控制应用程序的源代码，因此无法以编程方式对其进行配置。

• 应用程序的多个实例在单个系统上同时运行，并且你想要将每个实例配置为获得最佳性能。

备注



本文档正在编写中。如果你注意到此处提供的信息不完整或不准确，可以创建一个问题告知我们，或提交拉取请求以解决问题。要了解如何提交 dotnet/docs 存储库的拉取请求，请参阅参与者指南.

”

.NET 提供以下机制，它们用于配置运行时应用程序行为：

• runtimeconfig.json 文件

• MSBuild 属性

• 环境变量

提示



如果使用环境变量配置运行时选项，会将设置应用于所有 .NET 应用。如果在 runtimeconfig.json 或项目文件中配置运行时选择，则仅将设置应用于此应用程序。

”

某些配置值还可以通过调用 AppContext.SetSwitch 方法以编程方式进行设置。

文档此部分的文章按类别组织，例如调试和垃圾回收。如果适用，将显示 runtimeconfig.json 文件、MSBuild 属性、环境变量的配置选项；对于 .NET Framework 项目，还会显示 app.config 文件的配置选项以便交叉引用。

runtimeconfig.json

构建项目时，将在输出目录中生成 [appname].runtimeconfig.json 文件。如果项目文件所在的文件夹中存在 runtimeconfig.template.json 文件，它包含的任何配置选项都将插入到 [appname].runtimeconfig.json 文件中。如果自行构建应用，请将所有配置选项放在 runtimeconfig.template.json 文件中。如果只是运行应用，请将其直接插入 [appname].runtimeconfig.template.json 文件中。

备注



后续生成中将覆盖 [appname].runtimeconfig.template.json 文件。如果应用的 OutputType 不是 Exe，但你想将配置选项从 runtimeconfig.template.json 复制到 [应用名称].runtimeconfig.json，则必须在项目文件中将 GenerateRuntimeConfigurationFiles 显式设置为 true 。对于需要 runtimeconfig.json 文件的应用，此属性默认设置为 true。在 runtimeconfig.json 文件的 configProperties 部分指定运行时配置选项。如下：

”

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

示例 [appname].runtimeconfig.template.json 文件

如果要将这些选项放在输出 JSON 文件中，请将它们嵌套在 runtimeOptions 属性下。

{"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}}
}

示例 runtimeconfig.template.json 文件

如果要将这些选项放在模板 JSON 文件中，请省略 runtimeOptions 属性。

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

MSBuild 属性

可使用 SDK 样式 .NET Core 项目的 .csproj 或 .vbproj 文件中的 MSBuild 属性设置某些运行时配置选项。MSBuild 属性优先于在 runtimeconfig.template.json 文件中设置的选项。

下面是一个示例 SDK 样式项目文件，其中包含用于配置运行时行为的 MSBuild 属性：

<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 属性记录在每个区域各自的文章中，例如垃圾回收。它们还在 SDK 样式项目的 MSBuild 属性参考的运行时配置部分中列出。

环境变量

环境变量可用于提供一些运行时配置信息。如果使用环境变量配置运行时选项，会将设置应用于所有 .NET Core 应用。指定为环境变量的配置旋钮通常带有 DOTNET_ 前缀。

备注



.NET 6 为用于配置 .NET 运行时行为的环境变量标准化前缀 DOTNET_ 而不是 COMPlus_。但是，COMPlus_ 前缀仍将继续正常工作。如果使用的是早期版本的 .NET 运行时，则环境变量仍应该使用 COMPlus_ 前缀。

”

可以使用 Windows 控制面板、命令行或通过在 Windows 和 Unix 系统上调用 Environment.SetEnvironmentVariable(String, String) 方法以编程方式定义环境变量。

下面的示例演示如何在命令行中设置环境变量：

# Windows
set DOTNET_GCRetainVM=1# Powershell
$env:DOTNET_GCRetainVM="1"# Unix
export DOTNET_GCRetainVM=1