Configuración de Blazor en ASP.NET Core

En este artículo se explica cómo configurar las aplicaciones Blazor, incluida la configuración de las aplicaciones, la autenticación y la configuración del registro.

Esta guía se aplica a la configuración del proyecto del lado cliente en una Blazor Web App o en una aplicación Blazor WebAssembly independiente.

Comportamiento predeterminado en Blazor Web App:

• Para la configuración del lado servidor:
  • Consulta Configuración en ASP.NET Core para obtener instrucciones.
  • Solo se carga la configuración en los archivos de configuración de la aplicación raíz del proyecto.
  • El resto de este artículo solo se aplica a la configuración del lado cliente en el proyecto .Client.
• En el caso de la configuración del lado cliente (proyecto .Client), la configuración se carga desde los siguientes archivos de configuración de la aplicación:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, donde el marcador de posición {ENVIRONMENT} es el entorno en tiempo de ejecución de la aplicación.

En aplicaciones Blazor WebAssembly independientes, la configuración se carga desde los siguientes archivos de configuración de la aplicación:

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, donde el marcador de posición {ENVIRONMENT} es el entorno en tiempo de ejecución de la aplicación.

Nota

La configuración de registro colocada en un archivo de configuración de la aplicación en wwwroot no se carga por defecto. Para obtener más información, consulta la sección Configuración de registro más adelante en este artículo.

En algunos escenarios, como con los servicios de Azure, es importante usar un segmento de nombre de archivo de entorno que coincida exactamente con el nombre del entorno. Por ejemplo, usa el nombre de archivo appsettings.Staging.json con una "S" mayúscula para el entorno Staging. Para obtener convenciones recomendadas, consulta los comentarios de apertura de los entornos deASP.NET Core Blazor.

Otros proveedores de configuración registrados por la aplicación también pueden proporcionar configuración, pero no todos los proveedores o características de los proveedores son apropiados:

• Proveedor de configuración de Azure Key Vault: El proveedor no es compatible con escenarios de identidad administrada e identificador de aplicación (ID de cliente) que requieren un secreto del cliente. El Id. de aplicación con un secreto de cliente no se recomienda para ninguna aplicación ASP.NET Core, especialmente las aplicaciones del lado del cliente, ya que el secreto de cliente no se puede proteger del lado del cliente para acceder al servicio Azure Key Vault.
• Proveedor de Azure App Configuration: el proveedor no es apropiado para aplicaciones del lado del cliente porque no se ejecutan en un servidor en Azure.

Para obtener más información sobre el uso de proveedores de configuración, consulta Configuración en ASP.NET Core.

Aviso

Los archivos de configuración y ajustes de la raíz web (carpeta wwwroot) son visibles para los usuarios en el cliente, y los usuarios pueden manipular los datos. No almacenes secretos de aplicación, credenciales ni otros datos confidenciales en ningún archivo raíz web.

Configuración de aplicaciones

La configuración de los archivos de configuración de la aplicación se carga de forma predeterminada. En el siguiente ejemplo, un valor de configuración de la interfaz de usuario se almacena en un archivo de configuración de la aplicación y lo carga el marco Blazor automáticamente. Un componente lee el valor.

wwwroot/appsettings.json:

JSON

{
    "h1FontSize": "50px"
}

Inserta una instancia IConfiguration en un componente para acceder a los datos de configuración.

ConfigExample.razor:

razor

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example (50px)
</h1>

Las restricciones de seguridad del cliente impiden el acceso directo a los archivos a través del código de usuario, incluidos los archivos de configuración de la aplicación. Para leer los archivos de configuración además de appsettings.json/appsettings.{ENVIRONMENT}.json desde la carpeta wwwroot en la configuración, use HttpClient.

Aviso

Los archivos de configuración y ajustes de la raíz web (carpeta wwwroot) son visibles para los usuarios en el cliente, y los usuarios pueden manipular los datos. No almacenes secretos de aplicación, credenciales ni otros datos confidenciales en ningún archivo raíz web.

En el ejemplo siguiente se lee un archivo de configuración (cars.json) en la configuración de la aplicación.

wwwroot/cars.json:

JSON

{
    "size": "tiny"
}

Agrega el espacio de nombres para Microsoft.Extensions.Configuration al archivo Program:

C#

using Microsoft.Extensions.Configuration;

Modifica el registro de servicio HttpClient existente para utilizar el cliente para leer el archivo:

C#

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

En el ejemplo anterior se establece la dirección base con builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), que obtiene la dirección base de la aplicación y se deriva normalmente del valor <base> de la etiqueta href en la página host.

Origen de la configuración de la memoria

El siguiente ejemplo utiliza MemoryConfigurationSource en el Program archivo para suministrar configuración adicional.

Agrega el espacio de nombres para Microsoft.Extensions.Configuration.Memory al archivo Program:

C#

using Microsoft.Extensions.Configuration.Memory;

En el archivo Program:

C#

var vehicleData = new Dictionary<string, string?>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

Inserta una instancia IConfiguration en un componente para acceder a los datos de configuración.

MemoryConfig.razor:

razor

@page "/memory-config"
@inject IConfiguration Configuration

<PageTitle>Memory Configuration</PageTitle>

<h1>Memory Configuration Example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

Obtén una sección de la configuración en el código de C# con IConfiguration.GetSection. En el ejemplo siguiente se obtiene la sección wheels para la configuración del ejemplo anterior:

razor

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

Configuración de autenticación

Proporciona la configuración de autenticación pública en un archivo de configuración de la aplicación.

wwwroot/appsettings.json:

JSON

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Carga la configuración de un proveedor Identity con ConfigurationBinder.Bind en el archivo Program. El siguiente ejemplo carga la configuración para un proveedor OIDC:

C#

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

Aviso

Los archivos de configuración y ajustes de la raíz web (carpeta wwwroot) son visibles para los usuarios en el cliente, y los usuarios pueden manipular los datos. No almacenes secretos de aplicación, credenciales ni otros datos confidenciales en ningún archivo raíz web.

Configuración del registro

Esta sección se aplica a las aplicaciones que configuran el registro a través de un archivo de configuración de la aplicación en la wwwroot carpeta.

Agrega el paquete Microsoft.Extensions.Logging.Configuration al proyecto.

Nota

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulta los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (documentación de NuGet). Confirma las versiones correctas del paquete en NuGet.org.

En el archivo de configuración de la aplicación, proporcione la configuración de registro. La configuración de registro se carga en el archivo Program.

wwwroot/appsettings.json:

JSON

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

En el archivo Program:

C#

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

Configuración del generador de host

Lee la configuración del host builder del WebAssemblyHostBuilder.Configuration en el archivo Program:

C#

var hostname = builder.Configuration["HostName"];

Configuración almacenada en caché

Los archivos de configuración se almacenan en caché para usarlos sin conexión. Con Aplicaciones web progresivas (PWA), solo puedes actualizar los archivos de configuración al crear una implementación nueva. Editar los archivos de configuración entre las implementaciones no tiene ningún efecto, debido a lo siguiente:

• Los usuarios tienen versiones en caché de los archivos que siguen usando.
• Los archivos service-worker.js y service-worker-assets.js de PWA se deben recompilar en la compilación, lo que indica a la aplicación en la próxima visita en línea del usuario que la aplicación se volvió a implementar.

Para obtener más información sobre cómo las PWA controlan las actualizaciones en segundo plano, consulta Aplicación web progresiva (PWA) con ASP.NET Core Blazor.

Configuración de opciones

La configuración de opciones requiere agregar una referencia de paquete para el Microsoft.Extensions.Options.ConfigurationExtensions paquete NuGet.

Nota

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulta los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (documentación de NuGet). Confirma las versiones correctas del paquete en NuGet.org.

Ejemplo:

OptionsExample.cs:

C#

public class OptionsExample
{
    public string? Option1 { get; set; }
    public string? Option2 { get; set; }
}

En appsettings.json:

JSON

"OptionsExample": {
  "Option1": "Option1 Value",
  "Option2": "Option2 Value"
}

C#

builder.Services.Configure<OptionsExample>(
    builder.Configuration.GetSection("OptionsExample"));

El siguiente componente de Razor recupera la configuración con la directiva @inject o el atributo [Inject].

Options.razor:

razor

@page "/options"
@using Microsoft.Extensions.Options
@inject IOptions<OptionsExample>? OptionsExample1

<h1>Options</h1>

<h2>
    &commat;inject approach
</h2>

<ul>
    <li>@OptionsExample1?.Value.Option1</li>
    <li>@OptionsExample1?.Value.Option2</li>
</ul>

<h2>
    [Inject] approach
</h2>

<ul>
    <li>@OptionsExample2?.Value.Option1</li>
    <li>@OptionsExample2?.Value.Option2</li>
</ul>

@code {
    [Inject]
    public IOptions<OptionsExample>? OptionsExample2 { get; set; }
}

No todas las características de opciones de ASP.NET Core están admitidas en los componentes Razor. Por ejemplo, se admite la configuraciónIOptionsSnapshot<TOptions> y IOptionsMonitor<TOptions>, pero no se admite volver a calcular los valores de opción para estas interfaces más allá de volver a cargar la aplicación solicitando la aplicación en una nueva pestaña del explorador o seleccionando el botón de volver a cargar del explorador. Con solo llamar StateHasChanged no se actualizan los valores de opción de instantánea ni los supervisados cuando cambia la configuración subyacente.