应用程序配置

2025-06-22

小窍门

此内容摘自电子书《面向 Azure ASP.NET Web Forms 开发人员的 Blazor》，可在 .NET 文档上获取，也可作为免费可下载的 PDF 脱机阅读。

在 Web Forms 中加载应用配置的主要方法是使用服务器上的 web.config 文件中的条目，或者通过 web.config 引用的相关配置文件。可以使用静态 ConfigurationManager 对象来与应用设置、数据存储库连接字符串以及添加到应用中的扩展配置提供程序进行交互。通常可以看到与应用配置的交互，如以下代码所示：

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

使用 ASP.NET Core 和服务器端 Blazor时，如果应用托管在 Windows IIS 服务器上，则可能存在 web.config 文件。但是 ConfigurationManager 与此配置没有交互，你可以接收更多来自其他源的结构化应用配置。让我们看看如何收集配置，以及如何从 web.config 文件访问配置信息。

配置源

ASP.NET Core 可识别许多可能要用于应用的配置源。默认情况下，框架会尝试为你提供最好的这些功能。配置通过 ASP.NET Core 从这些各种源读取和聚合。之后为同一配置键加载的值优先于早期值。

ASP.NET Core 旨在实现云感知，并使作员和开发人员更轻松地配置应用。 ASP.NET Core 具有环境感知性，并且知道它是否运行在 Production 环境或 Development 环境中。环境指示器在系统环境变量中 ASPNETCORE_ENVIRONMENT 设置。如果未配置任何值，则应用默认在 Production 环境中运行。

应用可以根据环境名称从多个源触发和添加配置。默认情况下，按列出的顺序从以下资源加载配置：

appsettings.json 文件（如果存在）
appsettings。{ENVIRONMENT_NAME}.json 文件（如果存在）
磁盘上的用户机密文件（如果存在）
环境变量
命令行参数

appsettings.json 格式和访问

appsettings.json 文件可以分层，其结构类似于以下 JSON 的值：

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

出现上述 JSON 时，配置系统合并子值，并引用其完全限定的分层路径。冒号（:）字符分隔层次结构中的每个属性。例如，配置键 section1:key0 访问 section1 对象文本 key0 的值。

用户机密

用户机密包括：

在应用开发文件夹外部的开发人员工作站上的 JSON 文件中存储的配置值。
仅在Development环境中运行时加载。
与特定应用关联。
使用 .NET CLI 的 user-secrets 命令进行管理。

将您的应用配置为机密存储，并执行命令 user-secrets。

dotnet user-secrets init

上述命令将元素 UserSecretsId 添加到项目文件。该元素包含 GUID，该 GUID 用于将机密与应用相关联。然后，可以使用命令定义机密 set 。例如：

dotnet user-secrets set "Parent:ApiKey" "12345"

上述命令使 Parent:ApiKey 配置密钥在开发人员的工作站上可用，其值为 12345。

有关创建、存储和管理用户机密的详细信息，请参阅 ASP.NET Core 文档中开发中的应用机密的安全存储。

环境变量

加载到应用配置中的下一组值是系统的环境变量。现在可以通过配置 API 访问系统的所有环境变量设置。在应用中读取分层值时，将合并分层值并用冒号分隔。但是，某些操作系统不允许冒号字符作为环境变量名称。 ASP.NET Core 通过将具有双下划线（__）的值转换为冒号（在访问它们时）来解决此限制。用户机密部分中的Parent:ApiKey值可以使用环境变量Parent__ApiKey覆盖。

命令行参数

启动应用时，还可以将配置作为命令行参数提供。使用双划线（--）或正斜杠（/）表示法来指示要设置的配置值的名称和要配置的值。语法类似于以下命令：

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

web.config 的回归

如果将应用部署到 IIS 上的 Windows， web.config 文件仍会配置 IIS 来管理应用。默认情况下，IIS 添加对 ASP.NET 核心模块（ANCM）的引用。 ANCM 是一个本机 IIS 模块，用于托管应用代替 Kestrel Web 服务器。此 web.config 部分类似于以下 XML 标记：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

可以通过将environmentVariables元素嵌套在aspNetCore元素中来定义应用特定的配置。本节中定义的值以环境变量的形式呈现给 ASP.NET Core 应用。在应用启动期间，环境变量会适当加载。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

读取应用中的配置

ASP.NET Core 通过 IConfiguration 接口提供应用配置。此配置接口应由 Blazor 组件、Blazor 页面以及需要访问配置的其他任何 ASP.NET Core 托管的类请求。 ASP.NET Core 框架使用先前配置的解析配置自动填充此接口。在Blazor页面或组件的 Razor 标记中，可以在IConfiguration文件顶部使用@inject指令来注入对象，如下所示：

@inject IConfiguration Configuration

上述语句使 IConfiguration 对象在整个 Razor 模板的其余部分都可用作 Configuration 变量。

可以通过指定作为索引器参数寻求的配置设置层次结构来读取单个配置设置：

var mySetting = Configuration["section1:key0"];

你可通过使用 GetSection 方法检索特定位置的键集合来提取整个配置部分，该方法的语法与前面的示例中检索 section1 的配置的 GetSection("section1") 类似。

强类型配置

通过 Web Forms，可以创建继承自 ConfigurationSection 类型和关联类型的强类型配置类型。 ConfigurationSection允许为这些配置值配置一些业务规则和处理。

在 ASP.NET Core 中，可以指定将接收配置值的类层次结构。这些类：

无需继承自父类。
应包含与您希望捕获的配置结构的属性和类型引用相匹配的public属性。

对于前面的 appsettings.json 示例，可以定义以下类来捕获值：

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

通过在Startup.ConfigureServices方法（或适当位置，如在Program.cs中使用builder.Services属性代替services）添加以下行，可以填充此类层次结构。

services.Configure<MyConfig>(Configuration);

在应用的其余部分，可将输入参数添加到 @inject 类型的 Razor 模板中的类或 IOptions<MyConfig> 指令，来接收强类型配置设置。 IOptions<MyConfig>.Value 属性将提供由配置设置填充的 MyConfig 值。

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

有关“选项”功能的详细信息，请参阅 ASP.NET Core 文档中的“选项”模式。

通过