Ambientes do Blazor ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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

O ambiente é definido usando uma das seguintes abordagens:

No cliente de um Blazor aplicativo Web, o ambiente é determinado a partir do servidor por meio de um middleware que comunica o ambiente ao navegador por meio de um cabeçalho denominado blazor-environment. O cabeçalho define o ambiente quando o WebAssemblyHost é criado no arquivo de Program do lado do cliente (WebAssemblyHostBuilder.CreateDefault).

O ambiente é definido usando uma das seguintes abordagens:

No cliente de um Blazor Aplicativo Web ou do cliente de um aplicativo Blazor WebAssembly hospedado, o ambiente é determinado pelo servidor por um middleware que comunica o ambiente com o navegador por um cabeçalho chamado blazor-environment. O cabeçalho define o ambiente quando o WebAssemblyHost é criado no arquivo de Program do lado do cliente (WebAssemblyHostBuilder.CreateDefault).

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.

Para obter diretrizes gerais sobre a configuração do aplicativo do ASP.NET Core, consulte Usar vários ambientes no ASP.NET Core. Para obter a configuração do aplicativo do lado do servidor com arquivos estáticos nos ambientes diferentes do ambiente Development durante o desenvolvimento e teste (por exemplo, Staging), consulte Arquivos estáticos do Blazor ASP.NET Core.

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.

Aplicativo Web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        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.

Observação

Para aplicativos Web do Blazor que definem a webAssembly>environment propriedade na configuração do Blazor.start, é sábio corresponder o ambiente do lado do servidor ao ambiente definido na propriedade environment. Caso contrário, a pré-geração no servidor funcionará em um ambiente diferente da renderização no cliente, o que resultará em efeitos arbitrários. Para obter orientações gerais sobre como definir o ambiente para um aplicativo Web do Blazor, consulte Usar vários ambientes no ASP.NET Core.

Blazor WebAssembly autônomo:

<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 blazor-environment, nem altera o log do console do projeto de servidor do ambiente de inicialização de um aplicativo Web do Blazor que adotou a renderização webassembly interativa global.

Para registrar o ambiente no console em um projeto autônomo Blazor WebAssembly ou no .Client projeto de um aplicativo Web do Blazor, 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>

Observação

Para usar um arquivo personalizado web.config para IIS e que não seja substituído quando o aplicativo for publicado na pasta publish, confira Hospedar e implantar o ASP.NET Core Blazor WebAssembly.

Embora a estrutura do Blazor emita o nome do cabeçalho em todas as letras minúsculas (blazor-environment), você é bem-vindo a usar qualquer maiúscula desejada. Por exemplo, há suporte para um nome de cabeçalho que capitaliza cada palavra (Blazor-Environment).

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>

Ler o lado do cliente do ambiente em um aplicativo Web do Blazor

Supondo que a pré-geração não esteja desabilitada para um componente ou aplicativo, um componente no projeto .Client é pré-gerado no servidor. Como o servidor não tem um serviço registrado IWebAssemblyHostEnvironment, não é possível injetar o serviço e usar as propriedades e métodos de extensão de ambiente de host da implementação do serviço durante a pré-geração do servidor. Injetar o serviço em um componente WebAssembly interativo ou Interativo Automático resulta no seguinte erro de runtime:

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

Para resolver isso, crie uma implementação de serviço personalizada para IWebAssemblyHostEnvironment o servidor. Adicione a classe a seguir ao projeto do servidor.

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

No arquivo do projeto Program do servidor, registre o serviço:

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

Neste ponto, o serviço IWebAssemblyHostEnvironment pode ser injetado em uma WebAssembly interativa ou componente automático interativo e usado como mostrado na seção Ler o ambiente em um aplicativo Blazor WebAssembly.

O exemplo anterior pode demonstrar que é possível ter um ambiente de servidor diferente do ambiente do cliente, o que não é recomendado e pode levar a resultados arbitrários. Ao definir o ambiente em um aplicativo Web do Blazor, é melhor corresponder ambientes de servidor e projeto .Client. Considere o seguinte cenário em um aplicativo de teste:

Você pode ver o valor da alteração da propriedade IWebAssemblyHostEnvironment.Environment na interface do usuário.

Quando a pré-geração ocorre no servidor, o componente é renderizado no ambiente Development:

Environment: Development

Quando o componente é renderizado apenas um segundo ou dois depois, depois que o pacote Blazor é baixado e o runtime do Blazor WebAssembly é ativado, os valores mudam para refletir que o cliente está operando no ambiente Staging no cliente:

Environment: Staging

O exemplo anterior demonstra por que recomendamos definir o ambiente do servidor para corresponder ao ambiente do cliente para implantações de desenvolvimento, teste e produção.

Para obter mais informações, consulte Os serviços do lado do cliente não são resolvidos durante a pré-renderização no artigo Modos renderizados, que aparece posteriormente na documentação do Blazor.

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:

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