ASP.NET Core Blazor ambientes

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

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

Recomendamos as seguintes convenções:

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

• Para ambientes de teste, preparação 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 invólucro do segmento de ambiente que corresponda exatamente ao nome do ambiente. Para preparação, use "Staging" (maiúscula "S") como o nome do ambiente e nomeie o arquivo de configurações do aplicativo para corresponder a (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 a (appsettings.Production.json).

Definir o ambiente

Para um aplicativo Blazor WebAssembly autônomo em execução local, o servidor de desenvolvimento adiciona o cabeçalho Blazor-Environment 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 modelo de projeto Blazor WebAssembly é Development. Para obter mais informações, consulte a secção Definir o ambiente do lado do cliente através do cabeçalho na secção.

Para aplicativos executados localmente em desenvolvimento, o aplicativo assume como padrão o ambiente Development. A publicação da aplicação define o ambiente padrão como Production.

Definir o ambiente do lado do cliente através da configuração de arranque Blazor

O exemplo a seguir inicia Blazor no ambiente Staging se o nome do host incluir localhost. Caso contrário, o ambiente é definido para o 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 do script Blazor e o nome do ficheiro. Para obter o local do script, consulte a estrutura do projeto do ASP.NET Core Blazor.

O uso da propriedade environment substitui o ambiente definido pelo cabeçalho 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 para um Blazor Web App que adotou a renderização global do Interactive WebAssembly.

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 depois que o WebAssemblyHost for criado com WebAssemblyHostBuilder.CreateDefault e antes da linha que cria 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, consulte ASP.NET Core Blazor inicialização.

Definir o ambiente do lado do cliente via cabeçalho

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

Embora a estrutura Blazor emita o nome do cabeçalho no caso de kebab com maiúsculas e minúsculas mistas (Blazor-Environment), você pode usar todas as letras maiúsculas ou minúsculas de kebab (blazor-environment, BLAZOR-ENVIRONMENT).

Para execução de desenvolvimento local com o servidor de desenvolvimento interno 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 é Blazor.start configuração (chaveenvironment)>Blazor-Environment cabeçalho de resposta (arquivoblazor.boot.json) >ASPNETCORE_ENVIRONMENT variável de ambiente (launchSettings.json). Não é possível usar a abordagem de 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 de web.config publicado. O arquivo web.config está localizado na pasta bin/Release/{TARGET FRAMEWORK}/publish, onde o espaço reservado para {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>

Nginx

Para servidores Nginx, use a diretiva add_header a partir do ngx_http_headers_module:

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

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

• A documentação do Nginx
• Blazor WebAssembly Orientação de hospedagem Nginx

Apache

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

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

Para mais informações:

• documentação do Apache (pesquise a versão mais recente por "mod_headers")
• Blazor WebAssembly Guia de hospedagem Apache

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

Para uma aplicação de Blazor WebAssembly autónomo, pode-se definir o ambiente manualmente através da configuração de início ou do cabeçalho Blazor-Environment.

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

1. Confirme se o invólucro dos segmentos de ambiente nos nomes de arquivo de configurações do aplicativo corresponde exatamente ao invólucro do nome do ambiente. Por exemplo, o nome do arquivo de configurações do aplicativo correspondente para o ambiente Staging é appsettings.Staging.json. Se o nome do arquivo for appsettings.staging.json (minúscula "s"), o arquivo não será localizado 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 está implantado no slot de implantação correto. Para um aplicativo chamado BlazorAzureAppSample, o aplicativo é implantado no slot de implantação Staging.

3. No portal do Azure para o slot de implantação do ambiente, configure o ambiente com a configuração de aplicativo "ASPNETCORE_ENVIRONMENT". Para uma aplicação chamada BlazorAzureAppSample, o Slot do Serviço de Aplicações intermédio é denominado 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 solicitado em um navegador, o aplicativo BlazorAzureAppSample/Staging é carregado no ambiente Staging em https://blazorazureappsample-staging.azurewebsites.net.

Quando o aplicativo é carregado no navegador, a coleção de cabeçalhos de resposta para blazor.boot.json indica que o valor do cabeçalho Blazor-Environment é Staging.

As definições da aplicação são carregadas pela aplicação a partir do ficheiro appsettings.{ENVIRONMENT}.json, onde o marcador de posição {ENVIRONMENT} é o ambiente da aplicação. No exemplo anterior, as configurações do arquivo appsettings.Staging.json são carregadas.

Ler o ambiente numa aplicação Blazor WebAssembly

Obtenha o ambiente da aplicação 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>

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>();

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

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

No ficheiro Program:

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

Os seguintes métodos de extensão de conveniência disponibilizados através de WebAssemblyHostEnvironmentExtensions permitem verificar o ambiente atual para Development, Production, Staginge nomes de ambiente personalizados:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

No ficheiro 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

• ASP.NET de inicialização do Core Blazor
• Usar vários ambientes no ASP.NET Core
• Blazor exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)