.NET 运行时配置设置

  • 项目

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

备注

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

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

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

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

提示

通过使用环境变量来配置某个选项会将设置应用于所有的 .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

另请参阅