ASP.NET Core Blazor 設定

本文說明如何設定 Blazor 應用程式，包括應用程式設定、驗證和記錄設定。

本指導適用於 Blazor Web App 或獨立 Blazor WebAssembly 應用程式中的用戶端專案設定。

在 Blazor Web App中的預設行為：

• 針對伺服器端設定：
  • 如需指導，請參閱 ASP.NET Core 中的設定。
  • 僅會載入專案根應用程式設定檔案中的設定。
  • 本文的其餘部分僅適用於 .Client 專案中的用戶端設定。
• 針對用戶端設定（.Client 專案），會從下列應用程式設定檔案載入設定：
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json，其中 {ENVIRONMENT} 預留位置是應用程式的執行階段環境。

在獨立 Blazor WebAssembly 應用程式中，會從下列應用程式設定檔案載入設定：

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json，其中 {ENVIRONMENT} 預留位置是應用程式的執行階段環境。

注意

預設不會載入在 wwwroot 中放入應用程式設定檔的記錄設定。 如需詳細資訊，請參閱本文稍後的記錄設定一節。

在某些情況下，例如使用 Azure 服務，請務必使用與環境名稱完全相符的環境檔案名稱區段。 例如，針對 Staging 環境使用具有大寫「S」的檔案名稱 appsettings.Staging.json。 如需建議的慣例，請參閱 ASP.NET Core Blazor 環境的開頭備註。

應用程式註冊的其他設定提供者也可以提供設定，但並非所有提供者或提供者功能都適用：

• Azure Key Vault 設定提供者：用戶端密碼情節不支援受控的 identity 和應用程式識別碼 (用戶端識別碼) 的提供者。 不建議將任何具有用戶端密碼的應用程式識別碼用於任何 ASP.NET Core 應用程式，尤其是用戶端應用程式，因為用戶端密碼不是在用戶端存取 Azure Key Vault 服務的安全選擇。
• Azure 應用程式組態提供者：提供者不適用於用戶端應用程式，因為其不會在 Azure 中的伺服器上執行。

如需設定提供者的詳細資訊，請參閱 ASP.NET Core 中的設定。

警告

用戶端上的使用者可以看到 Web 根目錄 (wwwroot 資料夾) 中的組態和設定檔，而且使用者可以竄改資料。 請勿將應用程式的秘密、認證或任何其他敏感性資料儲存在任何 Web 根目錄檔案中。

應用程式設定

預設會載入應用程式設定檔中的設定。 在下列範例中，UI 設定值會儲存在應用程式設定檔中，並由 Blazor 架構自動載入。 元件會讀取此值。

wwwroot/appsettings.json：

{
    "h1FontSize": "50px"
}

將 IConfiguration 執行個體插入元件以存取設定資料。

ConfigExample.razor：

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

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

用戶端安全性限制可防止透過使用者程式碼直接存取檔案，包括應用程式設定的設定檔。 若要將 appsettings.json/appsettings.{ENVIRONMENT}.json 以外的設定檔從 wwwroot 資料夾讀取到設定，請使用 HttpClient。

警告

用戶端上的使用者可以看到 Web 根目錄 (wwwroot 資料夾) 中的組態和設定檔，而且使用者可以竄改資料。 請勿將應用程式的秘密、認證或任何其他敏感性資料儲存在任何 Web 根目錄檔案中。

下列範例會將設定檔 (cars.json) 讀入應用程式的設定。

wwwroot/cars.json：

{
    "size": "tiny"
}

將 Microsoft.Extensions.Configuration 命名空間新增至 Program 檔案：

using Microsoft.Extensions.Configuration;

修改現有的 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);

上述範例會使用 builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress) 設定基底位址 (Base Address)，其會取得應用程式的基底位址 (Base Address)，而且通常衍生自主頁面中 <base> href 標籤的值。

記憶體設定來源

下列範例使用 Program 檔案中的 MemoryConfigurationSource 來提供其他設定。

將 Microsoft.Extensions.Configuration.Memory 命名空間新增至 Program 檔案：

using Microsoft.Extensions.Configuration.Memory;

在 Program 檔案中：

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 執行個體插入元件以存取設定資料。

MemoryConfig.razor：

@page "/memory-config"
@inject IConfiguration Configuration

<PageTitle>Memory Configuration</PageTitle>

<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 檔案中使用 ConfigurationBinder.Bind 載入 Identity 提供者的設定。 下列範例會載入 OIDC 提供者的設定：

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

警告

用戶端上的使用者可以看到 Web 根目錄 (wwwroot 資料夾) 中的組態和設定檔，而且使用者可以竄改資料。 請勿將應用程式的秘密、認證或任何其他敏感性資料儲存在任何 Web 根目錄檔案中。

記錄設定

本節適用於透過 wwwroot 資料夾中應用程式設定檔，來設定記錄的應用程式。

將 Microsoft.Extensions.Logging.Configuration 套件新增至應用程式。

注意

如需將套件新增至 .NET 應用程式的指引，請參閱在套件取用工作流程 (NuGet 文件) 的安裝及管理套件底下的文章。 在 NuGet.org 確認正確的套件版本。

在應用程式設定檔中，提供記錄設定。 會在 Program 檔案中載入記錄設定。

wwwroot/appsettings.json：

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

在 Program 檔案中：

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

主機產生器設定

在 Program 檔案中從 WebAssemblyHostBuilder.Configuration 讀取主機產生器設定：

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

快取的設定

設定檔會快取以供離線使用。 使用漸進式 Web 應用程式 (PWA) 時，您只能在建立新的部署時更新設定檔。 編輯部署之間的設定檔沒有任何作用，因為：

• 使用者已快取他們繼續使用的檔案版本。
• PWA 的 service-worker.js 和 service-worker-assets.js 檔案必須在編譯時重建，這會在使用者下一次線上瀏覽向應用程式發出訊號，指出應用程式已重新部署。

如需 PWA 如何處理背景更新的詳細資訊，請參閱 ASP.NET Core Blazor 漸進式 Web 應用程式 (PWA)。

選項設定

選項設定需要為 Microsoft.Extensions.Options.ConfigurationExtensions NuGet 套件新增套件參考。

注意

如需將套件新增至 .NET 應用程式的指引，請參閱在套件取用工作流程 (NuGet 文件) 的安裝及管理套件底下的文章。 在 NuGet.org 確認正確的套件版本。

範例：

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

並非所有 ASP.NET Core 選項功能在 Razor 元件中都是受支援的。 例如，IOptionsSnapshot<TOptions> 和 IOptionsMonitor<TOptions> 設定是受支援的，但是除了透過在新的瀏覽器索引標籤中要求應用程式，或選取瀏覽器的重載按鈕，來重新載入應用程式外，並不支援重新計算這些介面的選項值。 當基礎設定變更時，只呼叫 StateHasChanged 並不會更新快照集或受監視的選項值。