.NET 运行时设置

.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