Ambientes do ASP.NET Core Blazor

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

Ao executar um aplicativo localmente, o ambiente usa como padrão Development. Quando o aplicativo é publicado, o ambiente usa como padrão Production.

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" (capital "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" (capital "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 qualquer uma das seguintes abordagens:

• Blazor Web App ou Blazor Server: use qualquer uma das abordagens descritas em Usar vários ambientes no ASP.NET Core para aplicativos gerais do ASP.NET Core.
• Qualquer aplicativo Blazor:
  • Blazor iniciar a configuração
  • Serviço de Aplicativos do Azure
• Blazor WebAssembly: Blazor-Environment cabeçalho

No cliente de um Blazor Web App, o ambiente é determinado pelo servidor por meio de um middleware que comunica o ambiente ao navegador por meio de um cabeçalho chamado Blazor-Environment. O cabeçalho define o ambiente quando WebAssemblyHost é criado no arquivo Program do cliente (WebAssemblyHostBuilder.CreateDefault).

Para um aplicativo autônomo Blazor WebAssembly em execução localmente, o servidor de desenvolvimento adiciona o Blazor-Environment cabeçalho com o nome do ambiente obtido do ambiente de hospedagem. O ambiente de hospedagem define o ambiente a partir da variável de ambiente ASPNETCORE_ENVIRONMENT estabelecida pelo arquivo Properties/launchSettings.json do projeto. O valor padrão da variável de ambiente em um projeto criado a partir do Blazor WebAssembly modelo de projeto é Development. Para obter mais informações, consulte a seção Definir o ambiente do lado do cliente por meio da seção de cabeçalho .

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

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

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.

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>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} representa o caminho do 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 Blazor Web Apps que definem a propriedade webAssembly>environment na configuração Blazor.start, é sábio corresponder o ambiente do servidor ao ambiente 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 diretrizes gerais sobre como definir o ambiente para um Blazor Web App, 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} representa o caminho do script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Usar a environment propriedade substitui o ambiente definido pelo Blazor-Environment cabeçalho.

A abordagem anterior define o ambiente do cliente sem alterar o valor do cabeçalho Blazor-Environment, nem modificar o registro no console do projeto de servidor do ambiente de inicialização para um Blazor Web App que adotou a renderização global do WebAssembly interativo.

Para registrar o ambiente no console em um aplicativo autônomo Blazor WebAssembly ou no projeto .Client de um Blazor Web App, coloque o seguinte código C# no arquivo Program depois que WebAssemblyHost for criado 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

Blazor WebAssembly os aplicativos podem definir o ambiente com o Blazor-Environment cabeçalho. Especificamente, o cabeçalho de resposta deve ser definido no arquivo _framework/blazor.boot.json, mas não há problema em definir o cabeçalho nas respostas do servidor de arquivos para outras solicitações de arquivo Blazor ou em toda a implantação Blazor.

Embora a estrutura Blazor emite o nome do cabeçalho em kebab case com letras maiúsculas e minúsculas (Blazor-Environment), você é bem-vindo a usar tudo em minúsculas ou tudo em maiúsculas no kebab case (blazor-environment, BLAZOR-ENVIRONMENT).

Para execuções de desenvolvimento local com o servidor de desenvolvimento integrado do Blazor, você pode controlar o valor do cabeçalho Blazor-Environment definindo o valor da variável de ambiente ASPNETCORE_ENVIRONMENT no arquivo Properties/launchSettings.json do projeto. Ao executar localmente com o servidor de desenvolvimento, a ordem de precedência para determinar o ambiente do aplicativo é a configuração Blazor.start (chave environment)>Blazor-Environment cabeçalho de resposta (arquivo blazor.boot.json) >ASPNETCORE_ENVIRONMENT variável de ambiente (launchSettings.json). Não é possível usar a abordagem da variável de ambiente ASPNETCORE_ENVIRONMENT (launchSettings.json) para um aplicativo Blazor WebAssembly implantado. A técnica só funciona com o servidor de desenvolvimento em execuções locais do aplicativo.

IIS

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, onde 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, consulte Hospedar e implantar o ASP.NET Core Blazor WebAssembly com IIS.

Nginx

Para servidores Nginx, use a diretiva add_header do ngx_http_headers_module:

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

Para obter mais informações, consulte os seguintes recursos:

• Documentação do Nginx
• Hospedar e implantar ASP.NET Core Blazor WebAssembly com o Nginx

Apache

Para servidores Apache, use a diretiva Header do módulo mod_headers:

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

Para obter mais informações, consulte os seguintes recursos:

• Documentação do Apache (pesquise a versão mais recente para "mod_headers")
• Hospedar e implantar ASP.NET Core Blazor WebAssembly com o Apache

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

Para um aplicativo autônomo Blazor WebAssembly , você pode definir o ambiente manualmente por meio da configuração inicial 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 para o Staging ambiente é appsettings.Staging.json. Se o nome do arquivo for appsettings.staging.json (minúscula "s"), o arquivo não é encontrado, e as configurações no arquivo não serão usadas no ambiente Staging.

2. Para 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 appsettings.Staging.json arquivo são carregadas.

Ler o ambiente em um aplicativo Blazor WebAssembly

Obtenha o ambiente do aplicativo em um componente injetando IWebAssemblyHostEnvironment e lendo a propriedade Environment.

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 Blazor Web App

Supondo que a pré-geração não esteja desabilitada para um componente ou aplicativo, um componente no .Client projeto é pré-gerado no servidor. Como o servidor não possui um serviço IWebAssemblyHostEnvironment registrado, não é possível injetar o serviço nem utilizar, durante a renderização prévia do servidor, as propriedades e métodos de extensão do ambiente de host da implementação do serviço. 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 no 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 Program do projeto servidor, registre o serviço:

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

Neste ponto, o serviço IWebAssemblyHostEnvironment pode ser injetado em um WebAssembly interativo ou em um componente Auto 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 Blazor Web App, é melhor alinhar os ambientes do servidor e do projeto .Client. Considere o seguinte cenário em um aplicativo de teste:

• Implemente a propriedade de ambiente do lado do cliente (webassembly) usando o ambiente Staging por meio de Blazor.start. Consulte a seção Definir o ambiente do lado do cliente por meio da seção de configuração de inicialização para obter um exemplo.
• Não altere o arquivo do lado Properties/launchSettings.json do servidor. Deixe a environmentVariables seção com a variável de ASPNETCORE_ENVIRONMENT ambiente definida como Development.

Você pode ver a alteração do valor 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 é rerenderizado apenas um segundo ou dois depois, após o pacote Blazor ser baixado e o tempo de execução do .NET WebAssembly ser ativado, os valores são alterados para refletir que o cliente está operando no ambiente Staging do 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, o WebAssemblyHostBuilder expõe o IWebAssemblyHostEnvironment através da propriedade HostEnvironment, que permite 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 do WebAssemblyHostEnvironmentExtensions permitem a verificação do ambiente atual para Development, Production, Staging e nomes de ambiente personalizados.

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

No arquivo Program:

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

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

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

Recursos adicionais

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