Конфигурация Blazor ASP.NET Core

В этой статье объясняется, как настроить Blazor приложения, включая параметры приложения, проверку подлинности и конфигурацию ведения журнала.

Это руководство относится к конфигурации проекта на стороне клиента в Blazor Web App автономном приложении или автономном Blazor WebAssembly приложении.

Поведение по умолчанию в Blazor Web Apps:

• Для конфигурации на стороне сервера:
  • Дополнительные сведения см . в разделе "Конфигурация" в 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, важно использовать сегмент имени файла среды, который точно соответствует имени среды. Например, используйте имя appsettings.Staging.json файла с заглавной буквой "S" для Staging среды. Дополнительные сведения о рекомендуемых соглашениях см. в начальных замечаниях ASP.NET основных Blazor средах.

Другие поставщики конфигурации, зарегистрированные приложением, также могут предоставлять конфигурацию, но не все поставщики или функции поставщика подходят:

• Поставщик конфигурации Azure Key Vault: поставщик не поддерживается для управляемых identity и идентификаторов приложений (идентификатор клиента) с сценариями секрета клиента. Идентификатор приложения с секретом клиента не рекомендуется использовать для любого приложения ASP.NET Core, особенно для клиентских приложений, так как секрет клиента не может быть защищен на стороне клиента для доступа к службе Azure Key Vault.
• приложение Azure поставщик конфигурации: поставщик не подходит для клиентского приложения, так как приложение не выполняется на сервере в Azure.

Дополнительные сведения о поставщиках конфигурации см. в статье Конфигурация в ASP.NET Core.

Предупреждение

Файлы конфигурации и параметров в корневом веб-каталоге (wwwroot папка) видны пользователям на клиенте, и пользователи могут изменить данные. Не сохраняйте секреты, учетные данные приложения или другие конфиденциальные данные в любом корневом файле веб-сайта.

Конфигурация параметров приложения

По умолчанию загружается конфигурация из файлов параметров приложения. В приведенном ниже примере значение конфигурации пользовательского интерфейса хранится в файле параметров приложения и автоматически загружается платформой 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.

Предупреждение

Файлы конфигурации и параметров в корневом веб-каталоге (wwwroot папка) видны пользователям на клиенте, и пользователи могут изменить данные. Не сохраняйте секреты, учетные данные приложения или другие конфиденциальные данные в любом корневом файле веб-сайта.

В приведенном ниже примере данные из файла конфигурации (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);

В предыдущем примере задается базовый адрес (IWebAssemblyHostEnvironment.BaseAddress), который получает базовый адрес builder.HostEnvironment.BaseAddress для приложения и обычно является производным от <base> значения тега href на хост-странице.

Источник конфигурации памяти

В следующем примере используется MemoryConfigurationSource в Program файле для предоставления дополнительной конфигурации.

Добавьте пространство имен для 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>

Получите раздел конфигурации в коде C# с помощью IConfiguration.GetSection. В приведенном ниже примере извлекается раздел wheels конфигурации из предыдущего примера.

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

        ...
    }
}

Конфигурация проверки подлинности

Укажите конфигурацию общедоступной проверки подлинности в файле параметров приложения.

wwwroot/appsettings.json:

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

Загрузите конфигурацию поставщика Identity в ConfigurationBinder.Bind Program файле. В следующем примере загружается конфигурация для поставщика OIDC:

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

Предупреждение

Файлы конфигурации и параметров в корневом веб-каталоге (wwwroot папка) видны пользователям на клиенте, и пользователи могут изменить данные. Не сохраняйте секреты, учетные данные приложения или другие конфиденциальные данные в любом корневом файле веб-сайта.

Конфигурация ведения журнала

Этот раздел относится к приложениям, которые настраивают ведение журнала с помощью файла параметров приложения в папке wwwroot .

Добавьте пакет Microsoft.Extensions.Logging.Configuration в приложение.

Примечание.

Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

В файле параметров приложения укажите конфигурацию ведения журнала. Конфигурация ведения журнала загружается в Program файл.

wwwroot/appsettings.json:

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

В файле Program:

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

Конфигурация построителя узлов

Чтение конфигурации построителя узлов из WebAssemblyHostBuilder.Configuration Program файла:

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

Кэшированная конфигурация

Файлы конфигурации кэшируются для автономного использования. При использовании Progressive Web Applications (PWAs) файлы конфигурации можно изменять только при создании развертывания. Изменение файлов конфигурации между развертываниями не работает по следующим причинам:

• У пользователей есть кэшированные версии файлов, которые они продолжают использовать.
• Файлы service-worker.js и service-worker-assets.js PWA должны быть перестроены при компиляции, что при следующем входе пользователя в сеть сообщает приложению о том, что приложение было развернуто повторно.

Дополнительные сведения об обработке фоновых обновлений прогрессивными веб-приложениями см. в статье Прогрессивные веб-приложения Blazor ASP.NET Core.

Конфигурация параметров

Для настройки параметров требуется добавить ссылку на Microsoft.Extensions.Options.ConfigurationExtensions пакет NuGet.

Примечание.

Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

Пример:

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

В компонентах Razor поддерживаются не все возможности параметров ASP.NET Core. Например, поддерживается конфигурация IOptionsSnapshot<TOptions> и IOptionsMonitor<TOptions>, но повторное вычисление значений параметров для этих интерфейсов возможно только за счет перезагрузки приложения путем его запроса в новой вкладке или нажатия кнопки перезагрузки в браузере. При изменении базовой конфигурации вызова StateHasChanged недостаточно для обновления моментального снимка или значений отслеживаемых параметров.