entornos de ASP.NET Core Blazor

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

Cuando se ejecuta una aplicación localmente, el entorno tiene Developmentcomo valor predeterminado . Cuando se publica la aplicación, el entorno tiene Productioncomo valor predeterminado .

Se recomiendan las convenciones siguientes:

• Use siempre el nombre del entorno "Development" para el desarrollo local. Esto se debe a que 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" (mayúscula "S") 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" (mayúscula "P") 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 mediante cualquiera de los métodos siguientes:

• Blazor Web App o Blazor Server: Use cualquiera de los enfoques descritos en entornos de tiempo de ejecución de ASP.NET Core para aplicaciones generales de ASP.NET Core.
• Cualquier Blazor aplicación: Blazor iniciar la configuración
• Independiente Blazor WebAssembly: propiedad <WasmApplicationEnvironmentName>

En el cliente de un Blazor Web App, el entorno se determina desde el servidor a través de un comentario HTML con el que los desarrolladores no interactúan:

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

Para una aplicación independiente Blazor WebAssembly , establezca el entorno con la <WasmApplicationEnvironmentName> propiedad MSBuild en el archivo de proyecto de la aplicación (.csproj). En el siguiente ejemplo se configura el entorno Staging.

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Los entornos predeterminados son Development para la compilación y Production para la publicación.

Hay varios enfoques para establecer el entorno en una aplicación independiente Blazor WebAssembly durante las operaciones de compilación o publicación y un enfoque para que una aplicación se inicie o ejecute en el cliente:

• Establezca el valor de la propiedad cuando se ejecuten dotnet build o dotnet publish. En el ejemplo siguiente se establece el entorno en Staging cuando se publica una aplicación:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Establezca la propiedad durante la compilación o publicación en función de la configuración de la aplicación en Visual Studio. Los siguientes grupos de propiedades se pueden usar en el archivo de proyecto de la aplicación o en cualquier archivo de configuración de publicación (.pubxml). Agregue grupos de propiedades adicionales para otras configuraciones de compilación en uso.

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

• El entorno se puede establecer en función del uso de un perfil de publicación. En el ejemplo siguiente, la primera condición establece el entorno en Development cuando no se usa ningún perfil de publicación (se aplica a las operaciones de compilación y publicación sin un perfil), mientras que la segunda condición abarca el establecimiento del entorno en Production cuando se usa cualquier perfil de publicación:

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

• Cree un punto de conexión personalizado de API web del lado servidor. La aplicación independiente Blazor WebAssembly solicita su entorno desde la API web en el inicio de la aplicación o a petición mientras se ejecuta. El valor debe pasarse a WebAssemblyStartOptions o con withApplicationEnvironment.

  Nota:

  Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta para una versión específica, use la lista desplegable Cambiar ramas o etiquetas . Para obtener más información, consulta Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Para las aplicaciones que se ejecutan localmente en desarrollo, la aplicación utiliza por defecto el entorno Development. Al publicar la aplicación, el entorno predeterminado será Production.

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

El siguiente ejemplo inicia Blazor en el entorno Staging si el nombre del 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} representa la ruta de acceso del script y Blazor el nombre del archivo. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Nota:

Para Blazor Web App que establecen la webAssembly>environment propiedad en la configuración de Blazor.start, es aconsejable que el entorno del lado del servidor coincida con el entorno establecido en la propiedad environment. De lo contrario, la representación previa en el servidor funciona 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 Blazor Web App, consulte entornos de tiempo de ejecución de 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} representa la ruta de acceso del script y Blazor el nombre del archivo. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Para registrar el entorno en la consola en una aplicación independiente Blazor WebAssembly o en el proyecto .Client de Blazor Web App, coloque 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 más información sobre el inicio de Blazor, vea Inicio de Blazor en ASP.NET Core.

Lectura del entorno en una aplicación Blazor WebAssembly

Obtenga el entorno de la aplicación en un componente inyectando IWebAssemblyHostEnvironment y leyendo 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>

Leer el entorno en el lado del cliente en Blazor Web App

Suponiendo que la representación previa no está deshabilitada para un componente o la aplicación, un componente del .Client proyecto 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 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, cree una implementación de servicio personalizada para IWebAssemblyHostEnvironment en el servidor. Para obtener más información y una implementación de ejemplo, consulte la sección Implementación de servicios personalizados en la sección servidor del artículo Representación previa , que aparece más adelante en la Blazor documentación.

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 siguientes métodos de extensión de conveniencia proporcionados mediante WebAssemblyHostEnvironmentExtensions permiten comprobar el entorno actual para Development, Production, Staging y nombres de entorno personalizados:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

En el archivo Program:

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

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

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

Recursos adicionales

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