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

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:

Requisitos previos

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

Recarga de datos de App Configuration

1. 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)
              // Reload configuration if any selected key-values have changed.
              .ConfigureRefresh(refreshOptions =>
                  refreshOptions.RegisterAll());
   });
   

   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.

   Dentro del método ConfigureRefresh, se llama al método RegisterAll para indicar al proveedor de App Configuration que vuelva a cargar toda la configuración siempre que detecte un cambio en cualquiera de los pares clave-valor seleccionados (los que empiezan por TestApp: y no tienen etiqueta). Para obtener más información sobre la supervisión de los cambios de configuración, consulte Procedimientos recomendados para la actualización de la configuración.

   Sugerencia

   Puede agregar una llamada al método refreshOptions.SetRefreshInterval 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.

2. Agregue middleware de Azure App Configuration a la colección de servicios de su 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
   // ... ...
   

3. 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. Cuando la aplicación está activa, el middleware de App Configuration supervisa las claves que registró para actualizar en la llamada ConfigureRefresh. El middleware se desencadena en cada solicitud entrante a la aplicación. Sin embargo, el middleware solo enviará solicitudes para comprobar el valor en App Configuration cuando se haya superado el intervalo de actualización 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

1. Para compilar la aplicación mediante la CLI de .NET, ejecute el siguiente comando en el shell de comandos:

       dotnet build
   

2. Una vez que la compilación se haya realizado correctamente, ejecute el siguiente comando para ejecutar la aplicación web localmente:

       dotnet run
   

3. Abra una ventana del explorador y vaya a la dirección URL que aparece en la salida dotnet run.

   

4. 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.

5. Seleccione Explorador de configuración y actualice los valores de las claves siguientes.

   Clave	Valor
   TestApp:Configuración:Color de fondo	verde
   TestApp:Settings:FontColor	Gris claro
   TestApp:Configuración:Mensaje	Datos de Azure App Configuration: ahora con actualizaciones directas

6. Actualice el explorador varias veces. Cuando el intervalo de actualización transcurre después de 30 segundos, la página se muestra con 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 ILoggerFactory, se agrega automáticamente un valor predeterminado services.AddAzureAppConfiguration(). 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.

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.

1. Inicie sesión en Azure Portal y después seleccione Grupos de recursos.
2. En el cuadro de texto Filtrar por nombre, escriba el nombre del grupo de recursos.
3. En la lista resultados, seleccione el nombre del grupo de recursos para ver la información general.
4. Seleccione Eliminar grupo de recursos.
5. 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.