.NET 运行时配置设置

项目
09/22/2022

.NET 5+（包括 .NET Core 版本）支持使用配置文件和环境变量在运行时配置 .NET 应用程序的行为。

备注

本节中的文章涉及 .NET 运行时本身的配置。如果要迁移到 .NET Core 3.1 或更高版本，并且想找到 app.config 文件的替代项，或者，如果只是需要在 .NET 应用中使用自定义配置值的方式，请参阅 Microsoft.Extensions.Configuration.ConfigurationBuilder 类和 .NET 中的配置。

这些设置比较适用于以下情形：

你不拥有或控制应用程序的源代码，因此无法以编程方式对其进行配置。
应用程序的多个实例在单个系统上同时运行，并且你想要将每个实例配置为获得最佳性能。

.NET 提供了以下机制用于配置 .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

另请参阅

.NET 环境变量

通过