Entornos de Blazor de ASP.NET Core

En este artículo se explica cómo configurar y leer el entorno en una aplicación Blazor.

Cuando una aplicación se ejecuta de manera local, el entorno se establece de manera predeterminada en Development. Cuando la aplicación se publica, el entorno se establece de manera predeterminada en Production.

Se recomiendan las convenciones siguientes:

• Use siempre el nombre del entorno "Development" para el desarrollo local. Es así porque el marco de ASP.NET Core espera exactamente ese nombre al configurar la aplicación y las herramientas para las ejecuciones de desarrollo local de una aplicación.

• Para los entornos de prueba, almacenamiento provisional y producción, publique e implemente siempre la aplicación. Puede usar cualquier esquema de nomenclatura de entorno que desee para las aplicaciones publicadas, pero usar siempre los nombres de archivo de configuración de la aplicación con mayúsculas y minúsculas del segmento de entorno que coincida exactamente con el nombre del entorno. Para el almacenamiento provisional, use "Staging" ("S" mayúscula) como nombre del entorno y asigne el nombre al archivo de configuración de la aplicación para que coincida (appsettings.Staging.json). Para producción, use "Production" ("P" mayúscula) como nombre del entorno y asigne el nombre al archivo de configuración de la aplicación para que coincida (appsettings.Production.json).

Establecimiento del entorno

El entorno se establece con cualquiera de los siguientes enfoques:

• Blazor Web App: use cualquiera de los enfoques descritos en Usar varios entornos en ASP.NET Core para aplicaciones generales ASP.NET Core.
• Blazor Web App o Blazor WebAssembly independiente: configuración de inicio de Blazor
• Blazor WebAssembly independiente: encabezado de blazor-environment
• Blazor Web App o Blazor WebAssembly independiente: Azure App Service

En el cliente de una Blazor Web App, el entorno se determina desde el servidor a través de un middleware que comunica el entorno al explorador a través de un encabezado denominado blazor-environment. El encabezado establece el entorno cuando WebAssemblyHost se crea en el archivo del lado cliente Program (WebAssemblyHostBuilder.CreateDefault).

Para una aplicación Blazor WebAssembly independiente que se ejecuta localmente, el servidor de desarrollo agrega el encabezado de blazor-environment.

Para las aplicaciones que se ejecutan localmente en el desarrollo, la aplicación tiene como valor predeterminado el entorno Development. La publicación de la aplicación tiene como valor predeterminado el entorno en Production.

Establecimiento del entorno del lado cliente mediante la configuración de inicio de Blazor

En el ejemplo siguiente se inicia Blazor en el entorno de Staging si el nombre de host incluye localhost. De lo contrario, el entorno se establece en su valor predeterminado.

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>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo de Blazor. Para obtener la ubicación del script, consulta la estructura del proyecto ASP.NET CoreBlazor.

Nota:

En el caso de Blazor Web App que establecen la propiedad webAssembly>environment en la configuración Blazor.start, es aconsejable que coincida el entorno del lado servidor con el entorno establecido en la propiedad environment. De lo contrario, la representación previa en el servidor funcionará en un entorno diferente al de la representación en el cliente, lo que produce efectos arbitrarios. Para obtener instrucciones generales sobre cómo establecer el entorno para un objeto Blazor Web App, consulta Uso de varios entornos en ASP.NET Core.

Blazor WebAssembly independiente:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulta la estructura del proyecto ASP.NET CoreBlazor.

El uso de la propiedad environment invalida el entorno establecido por el encabezado blazor-environment.

El enfoque anterior establece el entorno del cliente sin cambiar el valor del encabezado blazor-environment, ni cambia el registro de consola del proyecto de servidor del entorno de inicio de una Blazor Web App que ha adoptado la representación global de WebAssembly.

Para registrar el entorno en la consola en un proyecto Blazor WebAssembly independiente o en el proyecto .Client de una Blazor Web App, coloca el siguiente código de C# en el archivo Program después de crear WebAssemblyHost con WebAssemblyHostBuilder.CreateDefault y antes de la línea que compila y ejecuta el proyecto (await builder.Build().RunAsync();):

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Para obtener más información sobre el inicio de Blazor, consulta Inicio de Blazor en ASP.NET Core.

Establecimiento del entorno del lado cliente a través del encabezado

Las aplicaciones Blazor WebAssembly pueden establecer el entorno con el encabezado de blazor-environment.

En el ejemplo siguiente de IIS, se agrega el encabezado personalizado (blazor-environment) al archivo web.config publicado. El archivo web.config se encuentra en la carpeta bin/Release/{TARGET FRAMEWORK}/publish, donde el marcador de posición {TARGET FRAMEWORK} corresponde a la plataforma 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>

Nota:

Si quieres usar un archivo web.config personalizado para IIS que no se sobrescriba cuando la aplicación se publique en la carpeta publish, consulta Hospedaje e implementación de ASP.NET Core Blazor WebAssembly.

Aunque el marco Blazor emite el nombre del encabezado en todas las letras minúsculas (blazor-environment), te invitamos a usar las mayúsculas y las minúsculas como desee. Por ejemplo, se admite un nombre de encabezado que escribe en mayúsculas cada palabra (Blazor-Environment).

Establecimiento del entorno para Azure App Service

Para una aplicación Blazor WebAssembly independiente, establece el entorno manualmente a través de la configuración de inicio o el encabezado de blazor-environment.

Para una aplicación del lado servidor, establece el entorno a través de una configuración de aplicación ASPNETCORE_ENVIRONMENT en Azure:

1. Confirma que el uso de mayúsculas y minúsculas de los segmentos del entorno en los nombres de archivo de la configuración de la aplicación coincida exactamente con el uso de mayúsculas y minúsculas del nombre de su entorno. Por ejemplo, el nombre de archivo de configuración de la aplicación correspondiente para el entorno de Staging es appsettings.Staging.json. Si el nombre de archivo es appsettings.staging.json (minúscula "s"), el archivo no se encuentra y la configuración del archivo no se usa en el entorno Staging.

2. Para la implementación de Visual Studio, confirma que la aplicación está implementada en la ranura de implementación correcta. Para una aplicación denominada BlazorAzureAppSample, la aplicación se implementa en la ranura de implementación Staging.

3. En la Azure Portal para la ranura de implementación del entorno, establece el entorno con la configuración de la aplicación ASPNETCORE_ENVIRONMENT. Para una aplicación denominada BlazorAzureAppSample, el espacio de App Service se denomina BlazorAzureAppSample/Staging. Para la configuración de la ranura Staging, crea una configuración de aplicación para ASPNETCORE_ENVIRONMENT con un valor de Staging. La configuración de la ranura de implementación está habilitada para la configuración.

Cuando se solicita en un explorador, la aplicación BlazorAzureAppSample/Staging se carga en el entorno Staging en https://blazorazureappsample-staging.azurewebsites.net.

Cuando la aplicación se carga en el explorador, la colección de encabezados de respuesta de blazor.boot.json indica que el valor del encabezado blazor-environment es Staging.

La aplicación carga la configuración de la aplicación del archivo appsettings.{ENVIRONMENT}.json, donde el marcador de posición {ENVIRONMENT} es el entorno de la aplicación. En el ejemplo anterior, se carga la configuración del archivo appsettings.Staging.json.

Lectura del entorno en una aplicación Blazor WebAssembly

Para obtener el entorno de la aplicación en un componente, inserta IWebAssemblyHostEnvironment y lee la propiedad Environment.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Lectura del lado cliente del entorno en una Blazor Web App

Suponiendo que la representación previa no está deshabilitada para un componente o para la aplicación, un componente del proyecto .Client se representa previamente en el servidor. Dado que el servidor no tiene un servicio registrado IWebAssemblyHostEnvironment, no es posible insertar el servicio y usar los métodos y las propiedades de extensión de entorno de host de la implementación del servicio durante la representación previa del servidor. La inserción del servicio en un componente Interactivo webAssembly o Interactive Auto produce el siguiente error en tiempo de ejecución:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Para solucionar este problema, crea una implementación de servicio personalizada para IWebAssemblyHostEnvironment en el servidor. Agrega la siguiente clase al proyecto de 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;
}

En el archivo del proyecto Program de servidor, registra el servicio:

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

En este momento, el servicio IWebAssemblyHostEnvironment se puede insertar en un componente WebAssembly interactivo o Automático interactivo, y se puede usar como se muestra en la sección Lectura del entorno en una aplicación Blazor WebAssembly.

En el ejemplo anterior se puede demostrar que es posible tener un entorno de servidor diferente al del entorno de cliente, que no se recomienda y puede dar lugar a resultados arbitrarios. Al establecer el entorno en una Blazor Web App, es mejor que coincidan los entornos de servidor y proyecto .Client. Ten en cuenta el siguiente escenario en una aplicación de prueba:

• Implementa la propiedad de entorno del lado cliente (webassembly) con el entorno Staging a través de Blazor.start. Consulta la sección Establecer el entorno del lado cliente a través de la configuración de inicio para obtener un ejemplo.
• No cambies el archivo Properties/launchSettings.json del lado servidor. Deja la sección environmentVariables con la variable de entorno ASPNETCORE_ENVIRONMENT establecida en Development.

Puedes ver el valor del cambio de la propiedad IWebAssemblyHostEnvironment.Environment en la interfaz de usuario.

Cuando se produce la representación previa en el servidor, el componente se representa en el entorno Development:

Environment: Development

Cuando el componente se vuelve a representar solo un segundo o dos después, después de descargar la agrupación Blazor y el runtime de .NET WebAssembly se activa, los valores cambian para reflejar que el cliente funciona en el entorno Staging en el cliente:

Environment: Staging

En el ejemplo anterior se muestra por qué se recomienda establecer el entorno de servidor para que coincida con el entorno de cliente para las implementaciones de desarrollo, pruebas y producción.

Para obtener más información, consulta la sección Servicios del lado cliente que no se pueden resolver durante la representación previa del artículo Modos de representación, que aparece más adelante en la documentación Blazor.

Lectura del entorno del lado cliente durante el inicio

Durante el inicio, WebAssemblyHostBuilder expone la IWebAssemblyHostEnvironment a través de la propiedad HostEnvironment, lo que habilita una lógica específica del entorno en el código del generador de host.

En el archivo Program:

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

Los métodos de extensión útiles siguientes proporcionados a través de WebAssemblyHostEnvironmentExtensions permiten comprobar el entorno actual para Development, Productiony Staging, y los nombres de entornos personalizados:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

En el archivo Program:

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

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

La propiedad IWebAssemblyHostEnvironment.BaseAddress se puede usar durante el inicio cuando el servicio NavigationManager no está disponible.

Recursos adicionales

• Inicio de Blazor en ASP.NET Core
• Usar varios entornos en ASP.NET Core
• Repositorio de GitHub con ejemplos de Blazor (dotnet/blazor-samples) (cómo descargar)