Среды ASP.NET Core Blazor

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

При локальном запуске приложения среда по умолчанию имеет значение Development. При публикации приложения среда по умолчанию имеет значение Production.

Рекомендуется использовать следующие соглашения:

• Всегда используйте имя среды "Development" для локальной разработки. Это связано с тем, что платформа ASP.NET Core ожидает именно это имя при настройке приложения и инструментов для локальных запусков разработки приложения.

• Для тестирования, промежуточной и рабочей среды всегда публикуйте и развертывайте приложение. Вы можете использовать любую схему именования среды, которую вы хотите использовать для опубликованных приложений, но всегда используйте имена файлов параметров приложения с регистром сегмента среды, который точно соответствует имени среды. Для промежуточного выполнения используйте "Staging" ("S" ("") в качестве имени среды и присвойте файлу параметров приложения для сопоставления (appsettings.Staging.json). Для рабочей среды используйте "Production" ("" ("P") в качестве имени среды и назовите файл параметров приложения для сопоставления (appsettings.Production.json).

Указание среды

Для задания среды можно использовать любой из следующих подходов:

• Blazor Веб-приложение. Используйте любой из подходов, описанных в статье "Использование нескольких сред в ASP.NET Core для общих приложений ASP.NET Core".
• Blazor Веб-приложение или автономное приложение Blazor WebAssembly: Blazor начальная конфигурация
• Автономный Blazor WebAssembly: blazor-environment заголовок
• BlazorВеб-приложение или автономное Blazor WebAssemblyприложение: служба приложение Azure

На клиенте веб-приложения Blazor среда определяется с сервера с помощью по промежуточного слоя, которое передает среду в браузер через заголовок с именем blazor-environment. Заголовок задает среду при WebAssemblyHost создании в клиентском Program файле (WebAssemblyHostBuilder.CreateDefault).

Для автономного Blazor WebAssembly приложения, работающего локально, сервер разработки добавляет blazor-environment заголовок.

Для локального запуска приложения в разработке приложение по умолчанию использует Development среду. Публикация приложения по умолчанию использует среду Production.

Настройка клиентской среды с помощью Blazor конфигурации запуска

В приведенном ниже примере Blazor запускается в среде Staging, если в имени узла содержится localhost. В противном случае среда имеет значение по умолчанию.

Blazor Веб-приложение:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

В предыдущем примере {BLAZOR SCRIPT} заполнитель — это путь к скрипту Blazor и имя файла. Сведения о расположении скрипта см. в разделе ASP.NET Структура проекта CoreBlazor.

Примечание.

Для Blazor веб-приложения, которые задают webAssemblyenvironment>свойство в Blazor.start конфигурации, рекомендуется сопоставить среду на стороне сервера с средой, заданной в свойстве.environment В противном случае предварительное отображение на сервере будет работать в другой среде, чем отрисовка на клиенте, что приводит к произвольным последствиям. Общие рекомендации по настройке среды для Blazor веб-приложения см. в разделе "Использование нескольких сред в ASP.NET Core".

Изолированное решение Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

В предыдущем примере {BLAZOR SCRIPT} заполнитель — это путь к скрипту Blazor и имя файла. Сведения о расположении скрипта см. в разделе ASP.NET Структура проекта CoreBlazor.

Использование свойства environment переопределяет среду, заданную заголовком blazor-environment.

Предыдущий подход задает среду клиента без изменения blazor-environment значения заголовка, а также не изменяет ведение журнала Blazor консоли проекта сервера для веб-приложения, который принял глобальную интерактивную отрисовку WebAssembly.

Чтобы записать среду в консоль в автономном Blazor WebAssembly проекте или .Client проекте Blazor веб-приложения, поместите следующий код C# в Program файл после WebAssemblyHost создания WebAssemblyHostBuilder.CreateDefault и перед строкой, которая создает и запускает проект (await builder.Build().RunAsync();):

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Дополнительные сведения о запуске Blazor см. в статье Запуск ASP.NET Core Blazor.

Настройка клиентской среды с помощью заголовка

Blazor WebAssembly приложения могут задать среду с заголовком blazor-environment .

В приведенном ниже примере для служб IIS пользовательский заголовок (blazor-environment) добавляется в опубликованный файл web.config. Файл web.config находится в папке bin/Release/{TARGET FRAMEWORK}/publish, где заполнитель {TARGET FRAMEWORK} — это целевая платформа.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    ...

    <httpProtocol>
      <customHeaders>
        <add name="blazor-environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Примечание.

Сведения об использовании пользовательского файла web.config для служб IIS, который не перезаписывается при публикации приложения в папку publish, см. в разделе Размещение и развертывание ASP.NET Core Blazor WebAssembly.

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

Задание среды для Службы приложений Azure

Для автономного Blazor WebAssembly приложения можно вручную задать среду с помощью конфигурации запуска или заголовкаblazor-environment.

Для серверного приложения настройте среду с помощью ASPNETCORE_ENVIRONMENT параметра приложения в Azure:

1. Убедитесь, что регистр сегментов среды в именах файлов параметров приложения точно совпадают с регистром имени среды. Например, совпадающее имя файла параметров приложения для Staging среды appsettings.Staging.json. Если имя файла — appsettings.staging.json (строчная буква "s"), файл не расположен, а параметры в файле не используются в Staging среде.

2. Для развертывания Visual Studio убедитесь, что приложение развернуто в нужном слоте. Для приложения с именем BlazorAzureAppSample приложение развертывается в слоте развертывания Staging.

3. На портале Azure в слоте развертывания среды задайте среду с параметром приложения ASPNETCORE_ENVIRONMENT. Для приложения с именем BlazorAzureAppSample промежуточный слот Службы приложений называется BlazorAzureAppSample/Staging. Для конфигурации слота Staging создайте параметр приложения ASPNETCORE_ENVIRONMENT со значением Staging. Параметр слота развертывания включен для параметра.

При запросе в браузере приложение BlazorAzureAppSample/Staging загружается в среду Staging в https://blazorazureappsample-staging.azurewebsites.net.

При загрузке приложения в браузере коллекция заголовков ответа для blazor.boot.json указывает, что значение заголовка blazor-environment — Staging.

Параметры приложения из файла appsettings.{ENVIRONMENT}.json загружаются приложением, где заполнитель {ENVIRONMENT} — это среда приложения. В предыдущем примере загружаются параметры из файла appsettings.Staging.json.

Чтение среды в Blazor WebAssembly приложении

Чтобы получить среду приложения в компоненте, вставьте IWebAssemblyHostEnvironment и прочтите свойство Environment.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Чтение клиентской Blazor среды в веб-приложении

Если предварительное создание не отключено для компонента или приложения, компонент в .Client проекте предварительно отображается на сервере. Так как сервер не имеет зарегистрированной IWebAssemblyHostEnvironment службы, невозможно внедрить службу и использовать методы расширения и свойства среды узла реализации службы во время предварительной подготовки сервера. Внедрение службы в интерактивный компонент WebAssembly или Interactive Auto приводит к следующей ошибке среды выполнения:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Чтобы устранить эту проблему, создайте пользовательскую реализацию службы на IWebAssemblyHostEnvironment сервере. Добавьте следующий класс в серверный проект.

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

В файле проекта Program сервера зарегистрируйте службу:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

На этом этапе IWebAssemblyHostEnvironment служба может быть внедрена в интерактивный веб-компонент WebAssembly или интерактивный автоматический компонент и использоваться, как показано в разделе "Чтение среды" в Blazor WebAssembly разделе приложения .

В предыдущем примере можно продемонстрировать, что можно иметь другую серверную среду, отличную от клиентской среды, которая не рекомендуется и может привести к произвольным результатам. При настройке среды в Blazor веб-приложении лучше всего соответствовать средам сервера и .Client проекта. Рассмотрим следующий сценарий в тестовом приложении:

• Реализуйте свойство среды на сторонеwebassemblyStaging клиента с помощью Blazor.startсреды. Пример см. в разделе "Настройка клиентской среды" с помощью раздела конфигурации запуска.
• Не изменяйте файл на стороне Properties/launchSettings.json сервера. environmentVariables Оставьте раздел переменной ASPNETCORE_ENVIRONMENT среды, в которой задано значение Development.

Вы можете увидеть значение IWebAssemblyHostEnvironment.Environment изменения свойства в пользовательском интерфейсе.

При предварительной подготовке на сервере компонент отображается в Development среде:

Environment: Development

Если компонент перенамерован всего за секунду или два позже, после Blazor скачивания пакета и Blazor WebAssembly активации среды выполнения, значения изменяются, чтобы отразить, что клиент работает в Staging среде на клиенте:

Environment: Staging

В предыдущем примере показано, почему мы рекомендуем настроить среду сервера для сопоставления клиентской среды для разработки, тестирования и производственных развертываний.

Дополнительные сведения см. в статье о режимах отрисовки на стороне клиента, которая отображается далее в Blazor документации.

Чтение клиентской среды во время запуска

Во время запуска WebAssemblyHostBuilder предоставляет IWebAssemblyHostEnvironment с помощью свойства HostEnvironment, которое позволяет реализовать в коде построителя узлов логику для конкретной среды.

В файле Program:

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

Следующие удобные методы расширения, предоставляемые через WebAssemblyHostEnvironmentExtensions, допускают проверку текущей среды на признак Development (среды разработки), Production (среды тестирования), Staging (коммерческой среды) или пользовательской среды.

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

В файле Program:

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

Свойство IWebAssemblyHostEnvironment.BaseAddress можно использовать во время запуска, если служба NavigationManager недоступна.

Дополнительные ресурсы

• Запуск BlazorASP.NET Core
• Использование нескольких сред в ASP.NET Core
• Blazorпримеры репозитория GitHub (dotnet/blazor-samplesкак скачать)