Ambientes do Blazor ASP.NET Core

Este artigo explica como configurar e ler o ambiente em um aplicativo Blazor.

Ao executar um aplicativo localmente, o ambiente usará Development como padrão. Quando o aplicativo for publicado, o ambiente usará Production como padrão.

Recomendamos as seguintes convenções:

• Sempre use o nome do ambiente "Development" para desenvolvimento local. Isso ocorre porque a estrutura do ASP.NET Core espera exatamente esse nome ao configurar o aplicativo e as ferramentas para execuções de desenvolvimento local de um aplicativo.

• Para ambientes de teste, preparo e produção, sempre publique e implante o aplicativo. Você pode usar qualquer esquema de nomenclatura de ambiente que desejar para aplicativos publicados, mas sempre use nomes de arquivo de configuração de aplicativo com maiúsculas e minúsculas do segmento de ambiente que corresponde exatamente ao nome do ambiente. Para preparo, use "Staging" (maiúsculo "S") como o nome do ambiente e nomeie o arquivo de configurações do aplicativo para corresponder (appsettings.Staging.json). Para produção, use "Production" (maiúsculo "P") como o nome do ambiente e nomeie o arquivo de configurações do aplicativo para corresponder (appsettings.Production.json).

Definir o ambiente

Para um aplicativo Blazor WebAssembly autônomo executado localmente, o servidor de desenvolvimento adiciona o cabeçalho blazor-environment.

Para o aplicativo em execução localmente em desenvolvimento, o aplicativo usa como padrão o ambiente de Development. A publicação do aplicativo usa como padrão o ambiente para Production.

Defina o ambiente do lado do cliente por meio da configuração de inicialização Blazor

O exemplo a seguir iniciará o Blazor no ambiente Staging se o nome do host incluir localhost. Caso contrário, o ambiente será definido como seu valor padrão.

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

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

O uso da propriedade environment substitui o ambiente definido pelo cabeçalho do blazor-environment.

A abordagem anterior define o ambiente do cliente sem alterar o valor do cabeçalho do blazor-environment, nem altera o log do console do projeto de servidor do ambiente de inicialização de um Blazor Web App que adotou a renderização WebAssembly interativa global.

Para registrar o ambiente no console em um projeto Blazor WebAssembly autônomo ou no projeto .Client de um Blazor Web App, coloque o seguinte código C# no arquivo Program após a criação de WebAssemblyHost com WebAssemblyHostBuilder.CreateDefault e antes da linha que compila e executa o projeto (await builder.Build().RunAsync();):

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

Para obter mais informações sobre a inicialização de Blazor, veja Inicialização de Blazor no ASP.NET Core.

Definir o ambiente do lado do cliente por meio do cabeçalho

Os aplicativos Blazor WebAssembly podem definir o ambiente com o cabeçalho blazor-environment.

No exemplo a seguir para o IIS, o cabeçalho personalizado (blazor-environment) é adicionado ao arquivo publicado web.config. O arquivo web.config está localizado na pasta bin/Release/{TARGET FRAMEWORK}/publish, em que o espaço reservado {TARGET FRAMEWORK} é a estrutura de destino:

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

    ...

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

Definir o ambiente para o Serviço de Aplicativo do Azure

Para um aplicativo Blazor WebAssembly autônomo, você pode definir o ambiente manualmente por meio de configuração de inicialização ou do blazor-environment cabeçalho.

Para um aplicativo do lado do servidor, defina o ambiente por meio de uma configuração ASPNETCORE_ENVIRONMENT de aplicativo no Azure:

1. Confirme se a caixa dos segmentos de ambiente nos nomes dos arquivos de configurações de aplicativos correspondem à caixa do nome do ambiente exatamente. Por exemplo, o nome do arquivo de configurações de aplicativo correspondente do ambiente Staging é appsettings.Staging.json. Se o nome do arquivo for appsettings.staging.json (com "s" minúsculo), indica que o arquivo não está localizado e que as configurações no arquivo não serão usadas no ambiente Staging.

2. Em relação à implantação do Visual Studio, confirme se o aplicativo foi implantado no slot de implantação correto. Em relação a um aplicativo chamado BlazorAzureAppSample, o aplicativo será implantado no slot de implantação Staging.

3. No portal do Azure do slot de implantação do ambiente, defina o ambiente com a configuração do aplicativo ASPNETCORE_ENVIRONMENT. Para um aplicativo chamado BlazorAzureAppSample, o slot de Serviço de Aplicativo de preparo é chamado BlazorAzureAppSample/Staging. Para a configuração do slot Staging, crie uma configuração de aplicativo para ASPNETCORE_ENVIRONMENT com um valor de Staging. A configuração do slot de implantação está habilitada para a configuração.

Quando for solicitado em um navegador, o aplicativo BlazorAzureAppSample/Staging será carregado no ambiente Staging em https://blazorazureappsample-staging.azurewebsites.net.

Quando o aplicativo for carregado no navegador, a coleção de cabeçalhos de resposta para blazor.boot.json indicará que o valor do cabeçalho do blazor-environment é Staging.

As configurações do aplicativo do arquivo appsettings.{ENVIRONMENT}.json são carregadas pelo aplicativo, em que o espaço reservado {ENVIRONMENT} é o ambiente do aplicativo. No exemplo anterior, as configurações do arquivo appsettings.Staging.json estão carregadas.

Ler o ambiente em um aplicativo Blazor WebAssembly

Injete IWebAssemblyHostEnvironment e leia a propriedade Environment para obter o ambiente do aplicativo em um componente.

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

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;
}

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

Ler o ambiente do lado do cliente durante a inicialização

Durante a inicialização, WebAssemblyHostBuilder expõe IWebAssemblyHostEnvironment por meio da propriedade HostEnvironment, que habilita a lógica específica do ambiente no código do construtor de host.

No arquivo Program:

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

Os seguintes métodos de extensão de conveniência fornecidos por meio de WebAssemblyHostEnvironmentExtensions permitem a verificação do ambiente atual quanto a Development, Production, Staginge nomes de ambiente personalizados:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

No arquivo Program:

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

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

A propriedade IWebAssemblyHostEnvironment.BaseAddress pode ser usada durante a inicialização quando o serviço NavigationManager não estiver disponível.

Recursos adicionais

• Inicialização do ASP.NET Core Blazor
• Usar múltiplos ambientes no ASP.NET Core
• Blazor Repositório GitHub de exemplos(dotnet/blazor-samples) (como baixar)