Ambientes do Blazor ASP.NET Core
Observação
Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.
Aviso
Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 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 a versão atual, consulte a versão .NET 9 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:
- Blazor Web App: Use qualquer uma das abordagens descritas em Usar vários ambientes no ASP.NET Core para aplicativos do ASP.NET Core em geral.
- Blazor Web App ou autônomo Blazor WebAssembly: iniciar configuração do Blazor
- Autônomo Blazor WebAssembly:
blazor-environment
cabeçalho - Blazor Web App ou autônomo Blazor WebAssembly: Serviço de Aplicativo do Azure
No cliente de um Blazor Web App, 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:
- Blazor Server: Use qualquer uma das abordagens descritas em Usar vários ambientes no ASP.NET Core para aplicativos do ASP.NET Core em geral.
- Blazor Server ou Blazor WebAssembly: Blazor iniciar configuração
- Blazor WebAssembly:
blazor-environment
cabeçalho - Blazor Server ou Blazor WebAssembly: Serviço de Aplicativo do Azure
No cliente de um Blazor Web App ou do cliente de um aplicativo Blazor WebAssembly hospedado, o ambiente é determinado pelo servidor por meio de um middleware que comunica o ambiente ao 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.
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}
é 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 Blazor Web App que definem a propriedade webAssembly
>environment
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 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}
é 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>
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:
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 forappsettings.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 ambienteStaging
.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çãoStaging
.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 chamadoBlazorAzureAppSample
, o slot de Serviço de Aplicativo de preparo é chamadoBlazorAzureAppSample/Staging
. Para a configuração do slotStaging
, crie uma configuração de aplicativo paraASPNETCORE_ENVIRONMENT
com um valor deStaging
. 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 ambiente do lado do cliente em um Blazor Web App
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 Blazor Web App, é melhor corresponder ambientes de servidor e projeto do .Client
. Considere o seguinte cenário em um aplicativo de teste:
- Implemente a propriedade de ambiente do lado do cliente (
webassembly
) com o ambienteStaging
por meio deBlazor.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
Properties/launchSettings.json
do lado do servidor. Deixe a seçãoenvironmentVariables
com a variável de ambienteASPNETCORE_ENVIRONMENT
definida comoDevelopment
.
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 .NET 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
, Staging
e 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.