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

O ambiente é definido usando qualquer uma das seguintes abordagens:

• Blazor Web App ou Blazor Server: Utilize quaisquer das abordagens descritas nos ambientes de tempo de execução ASP.NET Core para aplicações gerais ASP.NET Core.
• Qualquer Blazor aplicativo: Blazor iniciar a configuração
• Autônomo Blazor WebAssembly: <WasmApplicationEnvironmentName> propriedade

No cliente para um Blazor Web App, o ambiente é determinado a partir do servidor através de um comentário HTML com o qual os desenvolvedores não interagem:

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Para uma aplicação autónoma Blazor WebAssembly, configure o ambiente com a propriedade <WasmApplicationEnvironmentName> MSBuild no ficheiro de projeto da aplicação (.csproj). O exemplo a seguir define o Staging ambiente:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Os ambientes padrão são Development para compilação e Production para publicação.

Existem várias abordagens para definir o ambiente numa aplicação autónoma Blazor WebAssembly durante operações de build/publish e uma abordagem para uma aplicação que inicia ou está a correr no cliente:

• Defina o valor da propriedade quando dotnet build ou dotnet publish for invocado. O exemplo seguinte define o ambiente para Staging quando uma aplicação é publicada:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Define a propriedade durante a compilação ou publicação com base na configuração da aplicação no Visual Studio. Os seguintes grupos de propriedades podem ser usados no ficheiro de projeto da aplicação ou em qualquer ficheiro de configuração de publicação (.pubxml). Adicionar grupos de propriedades adicionais para outras configurações de build em uso.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• O ambiente pode ser definido com base na utilização de um perfil de publicação. No exemplo seguinte, a primeira condição define o ambiente para Development quando não é utilizado nenhum perfil de publicação (aplica-se tanto a operações de construção como de publicação sem perfil), enquanto a segunda condição cobre a definição do ambiente para Production quando qualquer perfil de publicação é utilizado:

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Crie um endpoint web API personalizado do lado do servidor. A aplicação autónoma Blazor WebAssembly solicita o seu ambiente à API web, seja no arranque da aplicação ou a pedido enquanto está a correr. O valor deve ser passado para WebAssemblyStartOptions ou com withApplicationEnvironment.

  Observação

  Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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.

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 marcador {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do ficheiro. Para consultar a localização do script, veja a estrutura do projeto do ASP.NET Core Blazor.

Observação

Para Blazor Web Apps que definem a propriedade webAssembly>environment na configuração Blazor.start, é aconselhável alinhar o ambiente do servidor com o ambiente definido na propriedade environment. Caso contrário, a pré-renderização no servidor opera em um ambiente diferente da renderização no cliente, o que resulta em efeitos arbitrários. Para obter orientações gerais sobre como configurar o ambiente para um Blazor Web App, consulte ASP.NET Core runtime environments.

Blazor WebAssembly: independente

<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 marcador {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do ficheiro. Para consultar a localização do script, veja a estrutura do projeto do ASP.NET Core Blazor.

Para registar o ambiente na consola em uma aplicação autónoma Blazor WebAssembly ou no projeto .Client de um Blazor Web App, coloque o seguinte código C# no ficheiro Program depois de o WebAssemblyHost ser 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, consulte ASP.NET Core Blazor inicialização.

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>

Leia o ambiente do lado do cliente num Blazor Web App

Supondo que a pré-renderização não esteja desabilitada para um componente ou o aplicativo, um componente no projeto .Client é pré-renderizado no servidor. Como o servidor não tem um serviço IWebAssemblyHostEnvironment registado, não é possível injetar o serviço nem usar os métodos e propriedades de extensão do ambiente de acolhimento da implementação do serviço durante a pré-renderização do servidor. Injetar o serviço em um componente Interactive WebAssembly ou Interactive Auto resulta no seguinte erro de tempo de execução:

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. Para obter mais informações e um exemplo de implementação, consulte a seção Implementação de serviço personalizado no servidor do artigo Pré-renderização , que aparece posteriormente na Blazor documentação.

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

• Inicialização do ASP.NET Core Blazor
• Ambientes de runtime do ASP.NET Core
• Blazor exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)