ASP.NET Core Blazor 配置

备注

本主题适用于 Blazor WebAssembly。 若要获取 ASP.NET Core 应用配置的通用指南,请参阅 ASP.NET Core 中的配置

默认情况下,Blazor WebAssembly 会从以下应用设置文件加载配置:

  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json,其中 {ENVIRONMENT} 占位符是应用的运行时环境

应用注册的其他配置提供程序也可提供配置,但并非所有提供程序或提供程序功能都适用于 Blazor WebAssembly 应用:

  • Azure Key Vault 配置提供程序:具有客户端密码方案的托管标识和应用程序 ID(客户端 ID)不支持该提供程序。 不建议将具有客户端密码的应用程序 ID 用于任何 ASP.NET Core 应用(尤其是 Blazor WebAssembly 应用),因为无法在客户端保护客户端密码来访问 Azure Key Vault 服务。
  • Azure 应用配置提供程序:该提供程序不适用于 Blazor WebAssembly 应用,因为 Blazor WebAssembly 应用不会在 Azure 中的服务器上运行。

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

有关配置提供程序的详细信息,请参阅 ASP.NET Core 中的配置

应用设置配置

会默认加载应用设置文件中的配置。 在下述示例中,UI 配置值存储在应用设置文件中,由 Blazor 框架自动加载。 该值由组件读取。

wwwroot/appsettings.json:

{
  "h1FontSize": "50px"
}

IConfiguration 实例注入到组件中来访问配置数据。

Pages/ConfigurationExample.razor:

@page "/configuration-example"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example
</h1>

客户端安全限制阻止对文件(包括应用配置的设置文件)的直接访问。 若除了 appsettings.json/appsettings.{ENVIRONMENT}.json 之外,还要将 wwwroot 文件夹中的配置文件读入配置,请使用 HttpClient

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

以下示例会将配置文件 (cars.json) 读取到应用的配置中。

wwwroot/cars.json:

{
    "size": "tiny"
}

Program.cs 添加 Microsoft.Extensions.Configuration 的命名空间:

using Microsoft.Extensions.Configuration;

Program.cs 中,修改现有 HttpClient 服务注册,以使用客户端读取文件:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

内存配置源

以下示例使用 Program.cs 中的 MemoryConfigurationSource 来提供其他配置。

Program.cs 添加 Microsoft.Extensions.Configuration.Memory 的命名空间:

using Microsoft.Extensions.Configuration.Memory;

Program.cs中:

var vehicleData = new Dictionary<string, string>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

IConfiguration 实例注入到组件中来访问配置数据。

Pages/MemoryConfig.razor:

@page "/memory-config"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1>Memory configuration example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

使用 IConfiguration.GetSection 在 C# 代码中获取配置的一部分。 以下示例会获取上一示例中的配置的 wheels 部分:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

身份验证配置

在应用设置文件中提供身份验证配置。

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

使用 Program.cs 中的 ConfigurationBinder.Bind 来加载 Identity 提供程序的配置。 以下示例会加载 OIDC 提供程序的配置。

Program.cs:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

日志记录配置

向应用的项目文件添加 Microsoft.Extensions.Logging.Configuration 的包引用:

<PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="{VERSION}" />

在前面的示例中,{VERSION} 占位符是包的版本。 包版本位于 NuGet.org 中。

在应用设置文件中,提供日志记录配置。 日志记录配置在 Program.cs中加载。

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Program.cs 添加 Microsoft.Extensions.Logging 的命名空间:

using Microsoft.Extensions.Logging;

Program.cs中:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

主机生成器配置

Program.cs 中的 WebAssemblyHostBuilder.Configuration 读取主机生成器配置。

Program.cs中:

var hostname = builder.Configuration["HostName"];

缓存的配置

配置文件会缓存以供脱机使用。 使用渐进式 Web 应用程序 (PWA) 时,只能在创建新部署时更新配置文件。 在部署之间编辑配置文件不起作用,原因如下:

  • 用户已拥有继续使用的文件的缓存版本。
  • PWA 的 service-worker.jsservice-worker-assets.js 文件必须在编译时重新生成,这会在用户下一次联机访问时通知应用,指示应用已重新部署。

有关 PWA 如何处理后台更新的详细信息,请参阅 利用 ASP.NET Core Blazor WebAssembly 生成渐进式 Web 应用程序

备注

本主题适用于 Blazor WebAssembly。 若要获取 ASP.NET Core 应用配置的通用指南,请参阅 ASP.NET Core 中的配置

默认情况下,Blazor WebAssembly 会从以下应用设置文件加载配置:

  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json,其中 {ENVIRONMENT} 占位符是应用的运行时环境

应用注册的其他配置提供程序也可提供配置,但并非所有提供程序或提供程序功能都适用于 Blazor WebAssembly 应用:

  • Azure Key Vault 配置提供程序:具有客户端密码方案的托管标识和应用程序 ID(客户端 ID)不支持该提供程序。 不建议将具有客户端密码的应用程序 ID 用于任何 ASP.NET Core 应用(尤其是 Blazor WebAssembly 应用),因为无法在客户端保护客户端密码来访问 Azure Key Vault 服务。
  • Azure 应用配置提供程序:该提供程序不适用于 Blazor WebAssembly 应用,因为 Blazor WebAssembly 应用不会在 Azure 中的服务器上运行。

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

有关配置提供程序的详细信息,请参阅 ASP.NET Core 中的配置

应用设置配置

会默认加载应用设置文件中的配置。 在下述示例中,UI 配置值存储在应用设置文件中,由 Blazor 框架自动加载。 该值由组件读取。

wwwroot/appsettings.json:

{
  "h1FontSize": "50px"
}

IConfiguration 实例注入到组件中来访问配置数据。

Pages/ConfigurationExample.razor:

@page "/configuration-example"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example
</h1>

客户端安全限制阻止对文件(包括应用配置的设置文件)的直接访问。 若除了 appsettings.json/appsettings.{ENVIRONMENT}.json 之外,还要将 wwwroot 文件夹中的配置文件读入配置,请使用 HttpClient

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

以下示例会将配置文件 (cars.json) 读取到应用的配置中。

wwwroot/cars.json:

{
    "size": "tiny"
}

Program.cs 添加 Microsoft.Extensions.Configuration 的命名空间:

using Microsoft.Extensions.Configuration;

Program.cs 中,修改现有 HttpClient 服务注册,以使用客户端读取文件:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

内存配置源

以下示例使用 Program.cs 中的 MemoryConfigurationSource 来提供其他配置。

Program.cs 添加 Microsoft.Extensions.Configuration.Memory 的命名空间:

using Microsoft.Extensions.Configuration.Memory;

Program.cs中:

var vehicleData = new Dictionary<string, string>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

IConfiguration 实例注入到组件中来访问配置数据。

Pages/MemoryConfig.razor:

@page "/memory-config"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1>Memory configuration example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

使用 IConfiguration.GetSection 在 C# 代码中获取配置的一部分。 以下示例会获取上一示例中的配置的 wheels 部分:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

身份验证配置

在应用设置文件中提供身份验证配置。

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

使用 Program.cs 中的 ConfigurationBinder.Bind 来加载 Identity 提供程序的配置。 以下示例会加载 OIDC 提供程序的配置。

Program.cs:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

日志记录配置

向应用的项目文件添加 Microsoft.Extensions.Logging.Configuration 的包引用:

<PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="{VERSION}" />

在前面的示例中,{VERSION} 占位符是包的版本。 包版本位于 NuGet.org 中。

在应用设置文件中,提供日志记录配置。 日志记录配置在 Program.cs中加载。

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Program.cs 添加 Microsoft.Extensions.Logging 的命名空间:

using Microsoft.Extensions.Logging;

Program.cs中:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

主机生成器配置

Program.cs 中的 WebAssemblyHostBuilder.Configuration 读取主机生成器配置。

Program.cs中:

var hostname = builder.Configuration["HostName"];

缓存的配置

配置文件会缓存以供脱机使用。 使用渐进式 Web 应用程序 (PWA) 时,只能在创建新部署时更新配置文件。 在部署之间编辑配置文件不起作用,原因如下:

  • 用户已拥有继续使用的文件的缓存版本。
  • PWA 的 service-worker.jsservice-worker-assets.js 文件必须在编译时重新生成,这会在用户下一次联机访问时通知应用,指示应用已重新部署。

有关 PWA 如何处理后台更新的详细信息,请参阅 利用 ASP.NET Core Blazor WebAssembly 生成渐进式 Web 应用程序

备注

本主题适用于 Blazor WebAssembly。 若要获取 ASP.NET Core 应用配置的通用指南,请参阅 ASP.NET Core 中的配置

默认情况下,Blazor WebAssembly 会从以下应用设置文件加载配置:

  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json,其中 {ENVIRONMENT} 占位符是应用的运行时环境

应用注册的其他配置提供程序也可提供配置,但并非所有提供程序或提供程序功能都适用于 Blazor WebAssembly 应用:

  • Azure Key Vault 配置提供程序:具有客户端密码方案的托管标识和应用程序 ID(客户端 ID)不支持该提供程序。 不建议将具有客户端密码的应用程序 ID 用于任何 ASP.NET Core 应用(尤其是 Blazor WebAssembly 应用),因为无法在客户端保护客户端密码来访问 Azure Key Vault 服务。
  • Azure 应用配置提供程序:该提供程序不适用于 Blazor WebAssembly 应用,因为 Blazor WebAssembly 应用不会在 Azure 中的服务器上运行。

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

有关配置提供程序的详细信息,请参阅 ASP.NET Core 中的配置

应用设置配置

会默认加载应用设置文件中的配置。 在下述示例中,UI 配置值存储在应用设置文件中,由 Blazor 框架自动加载。 该值由组件读取。

wwwroot/appsettings.json:

{
  "h1FontSize": "50px"
}

IConfiguration 实例注入到组件中来访问配置数据。

Pages/ConfigurationExample.razor:

@page "/configuration-example"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example
</h1>

客户端安全限制阻止对文件(包括应用配置的设置文件)的直接访问。 若除了 appsettings.json/appsettings.{ENVIRONMENT}.json 之外,还要将 wwwroot 文件夹中的配置文件读入配置,请使用 HttpClient

警告

Blazor WebAssembly 应用中的配置和设置文件对用户可见。 请勿在 Blazor WebAssembly 应用的配置或文件中存储应用机密、凭据或任何其他敏感数据。

以下示例会将配置文件 (cars.json) 读取到应用的配置中。

wwwroot/cars.json:

{
    "size": "tiny"
}

Program.cs 添加 Microsoft.Extensions.Configuration 的命名空间:

using Microsoft.Extensions.Configuration;

Program.cs 中,修改现有 HttpClient 服务注册,以使用客户端读取文件:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

内存配置源

以下示例使用 Program.cs 中的 MemoryConfigurationSource 来提供其他配置。

Program.cs 添加 Microsoft.Extensions.Configuration.Memory 的命名空间:

using Microsoft.Extensions.Configuration.Memory;

Program.cs中:

var vehicleData = new Dictionary<string, string>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

IConfiguration 实例注入到组件中来访问配置数据。

Pages/MemoryConfig.razor:

@page "/memory-config"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1>Memory configuration example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

使用 IConfiguration.GetSection 在 C# 代码中获取配置的一部分。 以下示例会获取上一示例中的配置的 wheels 部分:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

身份验证配置

在应用设置文件中提供身份验证配置。

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

使用 Program.cs 中的 ConfigurationBinder.Bind 来加载 Identity 提供程序的配置。 以下示例会加载 OIDC 提供程序的配置。

Program.cs:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

日志记录配置

向应用的项目文件添加 Microsoft.Extensions.Logging.Configuration 的包引用:

<PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="{VERSION}" />

在前面的示例中,{VERSION} 占位符是包的版本。 包版本位于 NuGet.org 中。

在应用设置文件中,提供日志记录配置。 日志记录配置在 Program.cs中加载。

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Program.cs 添加 Microsoft.Extensions.Logging 的命名空间:

using Microsoft.Extensions.Logging;

Program.cs中:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

主机生成器配置

Program.cs 中的 WebAssemblyHostBuilder.Configuration 读取主机生成器配置。

Program.cs中:

var hostname = builder.Configuration["HostName"];

缓存的配置

配置文件会缓存以供脱机使用。 使用渐进式 Web 应用程序 (PWA) 时,只能在创建新部署时更新配置文件。 在部署之间编辑配置文件不起作用,原因如下:

  • 用户已拥有继续使用的文件的缓存版本。
  • PWA 的 service-worker.jsservice-worker-assets.js 文件必须在编译时重新生成,这会在用户下一次联机访问时通知应用,指示应用已重新部署。

有关 PWA 如何处理后台更新的详细信息,请参阅 利用 ASP.NET Core Blazor WebAssembly 生成渐进式 Web 应用程序