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

ASP.NET Core dispone de un sistema de configuración conectable que puede leer datos de configuración de diversos orígenes. Es capaz de controlar los cambios de forma dinámica sin hacer que una aplicación se reinicie. ASP.NET Core admite el enlace de valores de configuración a clases .NET fuertemente tipadas. Las inserta en el código mediante IOptionsSnapshot<T>, que vuelve a cargar automáticamente la configuración de la aplicación cuando cambian los datos subyacentes.

Este tutorial le muestra cómo puede implementar las actualizaciones de configuración dinámica en el código. Se basa en la aplicación web que se introdujo en los inicios rápidos. Antes de continuar, finalice primero el tutorial Creación de una aplicación ASP.NET Core con Azure App Configuration.

Para realizar los pasos de este tutorial, puede usar cualquier editor de código. Visual Studio Code es una excelente opción que está disponible en las plataformas Windows, macOS y Linux.

En este tutorial, aprenderá a:

Prerrequisitos

Para realizar este tutorial, instale el SDK de .NET Core.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Antes de continuar, finalice primero el tutorial 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 especial 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 en la aplicación y reduce el número total de solicitudes realizadas a App Configuration, en comparación con la supervisión de los cambios en todas las claves.

1. En Azure Portal, seleccione Explorador de configuración > Crear > Clave-valor.
2. En Clave, escriba TestApp:Settings:Sentinel. En Valor, escriba 1. Deje Etiqueta y Tipo de contenido en blanco.
3. Seleccione Aplicar.

Recarga de datos de App Configuration

1. Para agregar una referencia al paquete NuGet Microsoft.Azure.AppConfiguration.AspNetCore, ejecute el comando siguiente:

   dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
   

2. Abra Program.cs y actualice el método CreateWebHostBuilder para agregar el método config.AddAzureAppConfiguration().

   • .NET 5.x
   • .NET Core 3.x
   • .NET Core 2.x

   public static IHostBuilder CreateHostBuilder(string[] args) =>
       Host.CreateDefaultBuilder(args)
           .ConfigureWebHostDefaults(webBuilder =>
               webBuilder.ConfigureAppConfiguration((hostingContext, config) =>
               {
                   var settings = config.Build();
                   config.AddAzureAppConfiguration(options =>
                   {
                       options.Connect(settings["ConnectionStrings:AppConfig"])
                              .ConfigureRefresh(refresh =>
                                   {
                                       refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)
                                              .SetCacheExpiration(new TimeSpan(0, 5, 0));
                                   });
                   });
               })
           .UseStartup<Startup>());
   

   En el método ConfigureRefresh, puede registrar las claves en el almacén de App Configuration que desea supervisar para detectar los cambios. El parámetro refreshAll del método Register indica que se deben actualizar todos los valores de configuración si cambia la clave registrada. El método SetCacheExpiration especifica el tiempo mínimo que debe transcurrir antes de que se realice una nueva solicitud a App Configuration para comprobar si hay cambios de configuración. En este ejemplo, se reemplaza el tiempo de expiración predeterminado de 30 segundos y especifica un tiempo de 5 minutos en su lugar. Esto reduce el número posible de solicitudes realizadas al almacén de App Configuration.

   Nota

   Puede que desee reducir el tiempo de expiración de la actualización de la memoria caché con fines de prueba.

   Para desencadenar realmente una actualización de la configuración, usará el middleware de App Configuration. Puede ver cómo hacerlo en un paso posterior.

3. Agregue el archivo Settings.cs al directorio Controllers que define e implementa una nueva clase Settings. Reemplace el espacio de nombres por el nombre del proyecto.

   namespace TestAppConfig
   {
       public class Settings
       {
           public string BackgroundColor { get; set; }
           public long FontSize { get; set; }
           public string FontColor { get; set; }
           public string Message { get; set; }
       }
   }
   

4. Abra Startup.cs y actualice el método ConfigureServices. Llame a Configure<Settings> para enlazar datos de configuración a la clase Settings. Llame a AddAzureAppConfiguration para agregar los componentes de App Configuration a la colección de servicios de la aplicación.

   • .NET 5.x
   • .NET Core 3.x
   • .NET Core 2.x

   public void ConfigureServices(IServiceCollection services)
   {
       services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
       services.AddControllersWithViews();
       services.AddAzureAppConfiguration();
   }
   

5. Actualice el método Configure y agregue una llamada a UseAzureAppConfiguration. Esto permite a la aplicación usar el middleware de App Configuration para controlar automáticamente las actualizaciones de configuración.

   • .NET 5.x
   • .NET Core 3.x
   • .NET Core 2.x

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
           if (env.IsDevelopment())
           {
               app.UseDeveloperExceptionPage();
           }
           else
           {
               app.UseExceptionHandler("/Home/Error");
               // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
               app.UseHsts();
           }
   
           // Add the following line:
           app.UseAzureAppConfiguration();
   
           app.UseHttpsRedirection();
   
           app.UseStaticFiles();
   
           app.UseRouting();
   
           app.UseAuthorization();
   
           app.UseEndpoints(endpoints =>
           {
               endpoints.MapControllerRoute(
                   name: "default",
                   pattern: "{controller=Home}/{action=Index}/{id?}");
           });
   }
   

   Nota

   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 del paso anterior. 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. Cuando se detecta un cambio, se actualizará toda la configuración, si se usa la clave de Sentinel, o solo se actualizarán los valores de las claves registradas.

   • 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é. Se realizará otra comprobación cuando el tiempo de expiración de la caché configurado haya transcurrido de nuevo y 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 a app.UseAzureAppConfiguration() tan pronto como sea adecuado en la canalización de solicitudes para que otro middleware no provoque un cortocircuito en la aplicación.

Uso de los datos de configuración más recientes

1. Abra HomeController.cs en el directorio de controladores y agregue una referencia al paquete Microsoft.Extensions.Options.

   using Microsoft.Extensions.Options;
   

2. Actualice la clase HomeController para recibir Settings mediante la inserción de dependencias y asegúrese de usar sus valores.

   • .NET 5.x
   • .NET Core 3.x
   • .NET Core 2.x

   public class HomeController : Controller
   {
       private readonly Settings _settings;
       private readonly ILogger<HomeController> _logger;
   
       public HomeController(ILogger<HomeController> logger, IOptionsSnapshot<Settings> settings)
       {
           _logger = logger;
           _settings = settings.Value;
       }
   
       public IActionResult Index()
       {
           ViewData["BackgroundColor"] = _settings.BackgroundColor;
           ViewData["FontSize"] = _settings.FontSize;
           ViewData["FontColor"] = _settings.FontColor;
           ViewData["Message"] = _settings.Message;
   
           return View();
       }
   
       // ...
   }
   

   Sugerencia

   Para obtener más información sobre el patrón de opciones al leer valores de configuración, consulte Patrón de opciones en ASP.NET Core.

3. Abra el archivo Index.cshtml en el directorio Views > Home, y sustituya su contenido por el siguiente script:

   <!DOCTYPE html>
   <html lang="en">
   <style>
       body {
           background-color: @ViewData["BackgroundColor"]
       }
       h1 {
           color: @ViewData["FontColor"];
           font-size: @ViewData["FontSize"]px;
       }
   </style>
   <head>
       <title>Index View</title>
   </head>
   <body>
       <h1>@ViewData["Message"]</h1>
   </body>
   </html>
   

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

1. Para compilar la aplicación mediante la CLI de .NET Core, 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 la instancia de 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. 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

6. Actualice la página del explorador para ver los nuevos valores de configuración. Es posible que necesite actualizar el explorador más de una vez para que se reflejen los cambios o que tenga que cambiar el tiempo de expiración de la caché para que sea inferior a 5 minutos.

   

Limpieza de recursos

Si no desea seguir usando los recursos creados 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.