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 ambientes de runtime do ASP.NET Core para aplicativos gerais do ASP.NET Core.
• Qualquer aplicativoBlazor: Blazor iniciar configuração
• Propriedade Blazor WebAssembly: <WasmApplicationEnvironmentName> autônoma

No cliente de um Blazor Web App, o ambiente é determinado do servidor por meio de um comentário HTML com o qual os desenvolvedores não interagem:

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

Para um aplicativo autônomo Blazor WebAssembly , defina o ambiente com a <WasmApplicationEnvironmentName> propriedade MSBuild no arquivo de projeto do aplicativo (.csproj). O exemplo a seguir define o Staging ambiente:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

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

Há várias abordagens para definir o ambiente em um aplicativo autônomo Blazor WebAssembly durante operações de build/publicação e uma abordagem para um aplicativo iniciando ou em execução no cliente:

• Defina o valor da propriedade quando dotnet build ou dotnet publish for executado. O exemplo a seguir define o ambiente como Staging quando um aplicativo é publicado:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Defina a propriedade durante a compilação ou publicação com base na configuração do aplicativo no Visual Studio. Os grupos de propriedades a seguir podem ser usados no arquivo de projeto do aplicativo ou em qualquer arquivo de configuração de publicação (.pubxml). Adicione 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 no uso de um perfil de publicação. No exemplo a seguir, a primeira condição define o ambiente como Development quando nenhum perfil de publicação é usado (aplica-se a operações de compilação e publicação sem um perfil), enquanto a segunda condição abrange a configuração do ambiente para Production quando qualquer perfil de publicação é usado:

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

• Crie um endpoint de API da Web personalizado no servidor. O aplicativo autônomo Blazor WebAssembly solicita seu ambiente da API Web na inicialização do aplicativo ou sob demanda enquanto ele está em execução. O valor deve ser passado para WebAssemblyStartOptions ou com withApplicationEnvironment.

  Observação

  Os links de documentação para o código 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 marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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 opera em um ambiente diferente da renderização no cliente, o que resulta em efeitos arbitrários. Para obter diretrizes gerais sobre como definir o ambiente para um Blazor Web App, consulte os ambientes de runtime do 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.

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.

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

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
• ambientes de runtime do ASP.NET Core
• Blazor amostras do repositório GitHub (dotnet/blazor-samples) (como baixar)