.NET 运行时配置设置

2025-06-19

.NET 提供以下机制来配置 .NET 运行时的行为：

机制	注释
runtimeconfig.json 文件	将设置应用于特定应用。如果应用多个实例同时在单个系统上运行，并且想要为每个实例配置最佳性能，请使用此文件。
MSBuild 属性	将设置应用于特定应用。 MSBuild 属性优先于 runtimeconfig.json中的设置。
环境变量	将设置应用于所有 .NET 应用。

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

注释

本节中的文章涉及 .NET 运行时本身的配置。如果要将应用从 .NET Framework 迁移到 .NET 并正在寻找 app.config 文件的替代项，请参阅升级到 .NET 后的现代化。有关向 .NET 应用提供自定义配置值的信息，请参阅 .NET 中的配置。

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

runtimeconfig.json

生成项目后，会在输出目录中生成 [appname].runtimeconfig.json 文件。如果 runtimeconfig.template.json 文件与项目文件位于同一文件夹中，则它包含的任何配置选项将插入 [appname].runtimeconfig.json 文件中。如果要自行生成应用，请将任何配置选项放在 runtimeconfig.template.json 文件中。如果只是运行应用，请将它们直接插入 [appname].runtimeconfig.json 文件中。

注释

[appname].runtimeconfig.json 文件将在后续构建时被覆盖。
如果你的应用的OutputType不是Exe，并且你希望将配置选项从 runtimeconfig.template.json 复制到 [appname].runtimeconfig.json，则必须在项目文件中显式设置GenerateRuntimeConfigurationFiles为true。对于需要 runtimeconfig.json 文件的应用，此属性默认为 true。

在 runtimeconfig.json 或 runtimeconfig.template.json 文件的 configProperties 节中指定运行时配置选项。本部分采用以下格式：

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

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

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

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

示例 runtimeconfig.template.json 文件

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

{
  "configProperties": {
    "System.Globalization.UseNls": true,
    "System.Net.DisableIPv6": true,
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

MSBuild 属性

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

对于没有特定 MSBuild 属性的运行时配置设置，可以改用 RuntimeHostConfigurationOption MSBuild 项。将 runtimeconfig.json 设置名称用作特性的值。Include

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

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

环境变量

环境变量可用于提供某些运行时配置信息。指定为环境变量的配置旋钮通常具有前缀 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 环境变量

通过