Tutorial: Uso de la configuración dinámica en una aplicación de ASP.NET Core

Artículo
12/10/2024

En este tutorial se muestra cómo habilitar las actualizaciones de la configuración dinámica en una aplicación de ASP.NET Core. Se basa en la aplicación web que se introdujo en los inicios rápidos. La aplicación aprovechará la biblioteca de proveedores de App Configuration para sus funcionalidades integradas de almacenamiento en caché y actualización de la configuración. Antes de continuar, finalice primero el tutorial Creación de una aplicación ASP.NET Core con Azure App Configuration.

En este tutorial, aprenderá a:

Configurar la aplicación para actualizar su configuración en respuesta a los cambios en un almacén de App Configuration.
Insertar la configuración más reciente en la aplicación.

Requisitos previos

Complete el inicio rápido Creación de una aplicación ASP.NET Core con Azure App Configuration.

Adición de una clave de Sentinel

Una clave de Sentinel es una clave que se actualiza después de completar el cambio de todas las demás claves. La aplicación supervisa la clave de Sentinel. Cuando se detecta un cambio, la aplicación actualiza todos los valores de configuración. Este enfoque ayuda a garantizar la coherencia de la configuración de la aplicación y reduce el número total de solicitudes realizadas al almacén de App Configuration, en comparación con la supervisión de los cambios en todas las claves.

En Azure Portal, abra el almacén de App Configuration y seleccione Explorador de configuración > Crear > Pares clave-valor.
En Clave, escriba TestApp:Settings:Sentinel. En Valor, escriba 1. Deje Etiqueta y Tipo de contenido en blanco.
Seleccione Aplicar.

Recarga de datos de App Configuration

Abra Program.cs y actualice el método AddAzureAppConfiguration que agregó durante el inicio rápido. Puede conectarse a App Configuration mediante Microsoft Entra ID (recomendado) o una cadena de conexión. El siguiente fragmento de código muestra cómo usar Microsoft Entra ID.

Use DefaultAzureCredential para autenticarse en el almacén de App Configuration. Al completar el inicio rápido que se muestra en los requisitos previos, ya asignó a su credencial el rol de Lector de datos de App Configuration.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());
            // Load all keys that start with `TestApp:` and have no label
            .Select("TestApp:*", LabelFilter.Null)
            // Configure to reload configuration if the registered sentinel key is modified
            .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});
```
El método Select se usa para cargar todos los pares clave-valor cuyo nombre comienza por TestApp: y que no tienen etiqueta. Puede llamar al método Select más de una vez para cargar configuraciones con distintos prefijos o etiquetas. Si comparte un almacén de App Configuration con varias aplicaciones, este enfoque ayuda a cargar solo la configuración que es pertinente para la aplicación actual en lugar de cargar todo desde el almacén.

En el método ConfigureRefresh, puede registrar las claves que desea supervisar para detectar los cambios en el almacén de App Configuration. El parámetro refreshAll del método Register indica que todas las configuraciones especificadas por el método Select se volverán a cargar si cambia la clave registrada.

Sugerencia

Puede agregar una llamada al método refreshOptions.SetCacheExpiration para especificar el tiempo mínimo entre las actualizaciones de configuración. En este ejemplo, usará el valor predeterminado de 30 segundos. Ajústelo a un valor mayor si necesita reducir el número de solicitudes realizadas en el almacén de App Configuration.

Agregue middleware de Azure App Configuration a la colección de servicios de la aplicación.

Actualice Program.cs con el siguiente código.

// Existing code in Program.cs
// ... ...

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Llame al método UseAzureAppConfiguration. Esto permite a la aplicación usar el middleware de App Configuration para actualizar automáticamente la configuración.

Actualice Program.cs con el siguiente código.

// Existing code in Program.cs
// ... ...

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

// The rest of existing code in program.cs
// ... ...

Ha configurado la aplicación para que use el patrón de opciones de ASP.NET Core durante el inicio rápido. Cuando la configuración subyacente de la aplicación se actualiza desde App Configuration, el objeto fuertemente tipado Settings obtenido a través de IOptionsSnapshot<T> se actualiza automáticamente. Tenga en cuenta que no debe usar el IOptions<T> se desea actualizar la configuración dinámica, ya que no lee los datos de configuración una vez iniciada la aplicación.

Actualización de configuración controlada por solicitudes

La actualización de configuración se desencadena mediante las solicitudes entrantes a la aplicación web. No se producirá ninguna actualización si la aplicación está inactiva. Si la aplicación está activa, el middleware de App Configuration supervisa la clave de Sentinel o cualquier otra clave que haya registrado para la actualización en la llamada a ConfigureRefresh. El middleware se desencadena en cada solicitud entrante a la aplicación. Sin embargo, el middleware solo enviará solicitudes para comprobar el valor de App Configuration cuando haya transcurrido el tiempo de expiración de la caché establecido.

Si se produce un error en una solicitud de detección de cambios de App Configuration, la aplicación seguirá utilizando la configuración almacenada en la caché. Los nuevos intentos de buscar cambios se realizarán periódicamente mientras haya nuevas solicitudes entrantes a la aplicación.
La actualización de la configuración se produce de forma asincrónica con respecto al procesamiento de las solicitudes entrantes de la aplicación. No bloqueará ni ralentizará la solicitud entrante que desencadenó la actualización. Es posible que no se actualicen los valores de configuración de la solicitud que desencadenó la actualización, pero sí lo harán las solicitudes posteriores.
Para asegurarse de que el middleware se desencadena, llame al método app.UseAzureAppConfiguration() tan pronto como sea adecuado en la canalización de solicitudes para que otro middleware no lo omita en la aplicación.

Compilación y ejecución de la aplicación en un entorno local

Para compilar la aplicación mediante la CLI de .NET, ejecute el siguiente comando en el shell de comandos:
```
    dotnet build
```
Una vez que la compilación se haya realizado correctamente, ejecute el siguiente comando para ejecutar la aplicación web localmente:
```
    dotnet run
```
Abra una ventana del explorador y vaya a la dirección URL que aparece en la salida dotnet run.
Inicie sesión en Azure Portal. Seleccione Todos los recursos y seleccione el almacén de App Configuration que creó en el inicio rápido.

Seleccione Explorador de configuración y actualice los valores de las claves siguientes. No olvide actualizar la clave de Sentinel al final.

Clave	Value
TestApp:Settings:BackgroundColor	green
TestApp:Settings:FontColor	lightGray
TestApp:Settings:Message	Datos de Azure App Configuration: ahora con actualizaciones directas
TestApp:Settings:Sentinel	2

Actualice el explorador varias veces. Cuando la caché expira después de 30 segundos, la página se muestra con el contenido actualizado.

Registro y supervisión

Los registros se generan al actualizar la configuración y contienen información detallada sobre los valores de clave recuperados del almacén de App Configuration y los cambios de configuración realizados en la aplicación.

Cuando se invoca services.AddAzureAppConfiguration(), se agrega automáticamente un valor predeterminado ILoggerFactory. El proveedor de App Configuration usa este ILoggerFactory para crear una instancia de ILogger, que genera estos registros. ASP.NET Core usa ILogger para el registro de forma predeterminada, por lo que no es necesario realizar cambios de código adicionales a fin de habilitar el registro para el proveedor de App Configuration.

Los registros se generan en distintos niveles de registro. El nivel predeterminado es Information.

Nivel de registro	Descripción
Depurar	Los registros incluyen la clave y la etiqueta de los valores clave que la aplicación supervisa en busca de cambios en el almacén de App Configuration. También se incluye la información sobre si el valor de clave ha cambiado en comparación con lo que la aplicación ya ha cargado. Habilite los registros en este nivel para solucionar problemas de la aplicación si no se ha producido un cambio de configuración según lo previsto.
Información	Los registros incluyen las claves de los parámetros de configuración actualizados durante una actualización de la configuración. Los valores de los parámetros de configuración se omiten en el registro para evitar la filtración de datos confidenciales. Puede supervisar los registros en este nivel para asegurarse de que la aplicación incluya cambios de configuración esperados.
Advertencia	Los registros incluyen errores y excepciones que se produjeron durante la actualización de la configuración. Se pueden omitir repeticiones ocasionales porque el proveedor de configuración seguirá usando los datos almacenados en caché e intentará actualizar la configuración la próxima vez. Puede supervisar los registros en este nivel en busca de advertencias repetitivas que puedan indicar posibles problemas. Por ejemplo, ha girado la cadena de conexión, pero olvidó actualizar la aplicación.

Puede habilitar el registro en el nivel de registro Debug agregando el ejemplo siguiente al archivo appsettings.json. Este ejemplo también se aplica a todos los demás niveles de registro.

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

La categoría de registro es Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, que aparece antes de cada registro. Estos son algunos registros de ejemplo en cada nivel de registro:

dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    A refresh operation failed while resolving a Key Vault reference.
Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'

El uso de ILogger es el método preferido en aplicaciones ASP.NET y se prioriza como origen de registro si hay una instancia de ILoggerFactory presente. Sin embargo, si ILoggerFactory no está disponible, los registros se pueden habilitar y configurar mediante las instrucciones para las aplicaciones .NET Core. Para obtener más información, consulte Registros en .NET Core y ASP.NET Core.

Nota

El registro está disponible si usa la versión 6.0.0 o posterior de cualquiera de los siguientes paquetes.

Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Azure.AppConfiguration.AspNetCore
Microsoft.Azure.AppConfiguration.Functions.Worker

Limpieza de recursos

Si no quiere seguir usando los recursos que se han creado en este artículo, elimine el grupo de recursos que creó aquí para evitar cargos.

Importante

La eliminación de un grupo de recursos es irreversible. El grupo de recursos y todos los recursos que contiene se eliminan permanentemente. Asegúrese de que no elimina por accidente el grupo de recursos o los recursos equivocados. Si creó los recursos para este artículo en un grupo de recursos que contenga los recursos que desee conservar, elimine cada recurso de forma individual desde su panel respectivo, en lugar de eliminar el grupo de recursos.

Inicie sesión en Azure Portal y después seleccione Grupos de recursos.
En el cuadro de texto Filtrar por nombre, escriba el nombre del grupo de recursos.
En la lista resultados, seleccione el nombre del grupo de recursos para ver la información general.
Seleccione Eliminar grupo de recursos.
Se le pedirá que confirme la eliminación del grupo de recursos. Escriba el nombre del grupo de recursos para confirmar y seleccione Eliminar.

Transcurridos unos instantes, el grupo de recursos y todos sus recursos se eliminan.

Pasos siguientes

En este tutorial, ha habilitado la aplicación web de ASP.NET Core para actualizar dinámicamente la configuración a partir de App Configuration. Para aprender a usar una identidad administrada de Azure para simplificar el acceso a App Configuration, vaya al siguiente tutorial.

Acceso a App Configuration mediante una identidad administrada

Compartir vía