ASP.NET Core Blazor средах

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

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

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

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

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

Настройка среды

Среда устанавливается с помощью любого из следующих подходов:

• Blazor Web App или Blazor Server: используйте любой из подходов, описанных в средах выполнения ASP.NET Core для общих приложений ASP.NET Core.
• Любое Blazor приложение: Blazor запуск конфигурации
• Автономное Blazor WebAssembly: <WasmApplicationEnvironmentName> свойство

На клиенте для Blazor Web App, среда определяется с сервера с помощью HTML-комментария, с которым разработчики не взаимодействуют.

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Для автономного Blazor WebAssembly приложения задайте среду со <WasmApplicationEnvironmentName> свойством MSBuild в файле проекта приложения (.csproj). Следующий пример задает Staging среду:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Среды по умолчанию — Development для сборки и Production для публикации.

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

• Установите значение свойства, когда выполняется dotnet build или dotnet publish. Следующий пример задает среду Staging для публикации приложения:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Задайте свойство во время сборки или публикации на основе конфигурации приложения в Visual Studio. Следующие группы свойств можно использовать в файле проекта приложения или любом файле конфигурации публикации (.pubxml). Добавьте дополнительные группы свойств для других конфигураций сборки, используемых.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Среду можно задать на основе использования профиля публикации. В следующем примере первое условие задает среду Development , если профиль публикации не используется (применяется как к операциям сборки, так и к публикации без профиля), а второе условие охватывает настройку среды Production при использовании любого профиля публикации:

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Создайте пользовательскую конечную точку веб-API на стороне сервера. Автономное Blazor WebAssembly приложение запрашивает среду из веб-API при запуске приложения или по запросу во время его выполнения. Значение должно передаваться через WebAssemblyStartOptions или с помощью withApplicationEnvironment.

  Примечание.

  Ссылки в документации на исходный код .NET обычно загружают ветку репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для конкретного релиза, используйте раскрывающийся список Переключение ветвей или тегов. Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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

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

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

Blazor Web App:

<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 Core.

Примечание.

Для Blazor Web Appэтого webAssembly>environmentсвойства в Blazor.start конфигурации рекомендуется сопоставить среду на стороне сервера с средой, заданной в свойстве.environment В противном случае предварительное отображение на сервере работает в другой среде, отличной от отрисовки на клиенте, что приводит к произвольным последствиям. Общие рекомендации по настройке среды для Blazor Web App см. в средах выполнения 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 Core.

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

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

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

Чтение среды в 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 Web App

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

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

Чтобы устранить эту проблему, создайте пользовательскую реализацию службы для IWebAssemblyHostEnvironment на сервере. Дополнительную информацию и пример реализации см. в разделе "Реализация пользовательской службы на сервере" статьи о предварительной отрисовке, которая находится далее в 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 служба недоступна.

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

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