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

La biblioteca de proveedores .NET de App Configuration admite la actualización de la configuración a petición sin provocar el reinicio de una aplicación. 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 que se introdujo en el inicio rápido. Antes de continuar, debe finalizar el tutorial Creación de una aplicación .NET 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:

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

Prerrequisitos

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

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

Actualización de configuración por actividad

Abra Program.cs y actualice el archivo con el código siguiente.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(TimeSpan.FromSeconds(10));
            });

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

En el método ConfigureRefresh, se registra una clave dentro del almacén de App Configuration para la supervisión de cambios. El método Register tiene un parámetro booleano refreshAll opcional que se puede usar para indicar si se deben actualizar todos los valores de configuración si cambia la clave registrada. En este ejemplo, solo se actualizará la clave TestApp:Settings:Message. 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 se especifica un tiempo de 10 minutos en su lugar para fines de demostración.

La llamada al método ConfigureRefresh por sí sola no hará que la configuración se actualice automáticamente. El método TryRefreshAsync se llama desde la interfaz IConfigurationRefresher para desencadenar una actualización. Este diseño es para evitar las solicitudes enviadas a App Configuration incluso cuando la aplicación está inactiva. Le recomendamos incluir la llamada a TryRefreshAsync donde considere que la aplicación esté activa. Por ejemplo, puede ser cuando se procesa un mensaje entrante, un pedido o una iteración de una tarea compleja. También puede ser en un temporizador si la aplicación está activa todo el tiempo. En este ejemplo, llamará a TryRefreshAsync cada vez que presione la tecla Entrar. Incluso si se produce un error en la llamada a TryRefreshAsync por cualquier motivo, la aplicación seguirá usando la configuración almacenada en caché. Se realizará otro intento cuando haya pasado el tiempo de expiración de la caché configurada y la actividad de la aplicación vuelva a desencadenar la llamada a TryRefreshAsync. Llamar a TryRefreshAsync es una operación sin efecto antes de que pase el tiempo de expiración de la caché configurada, por lo que su impacto en el rendimiento es mínimo, aunque se llame con frecuencia.

Actualización de la configuración mediante la inserción de dependencias

En el código anterior, guardó manualmente una instancia de IConfigurationRefresher para invocar TryRefreshAsync. Como alternativa, si usa la inserción de dependencias para resolver los servicios, puede hacer referencia a los pasos siguientes.

1. Registre los servicios de App Configuration necesarios invocando AddAzureAppConfiguration en IServiceCollection.

   Añada el código siguiente a Program.cs.

   // Existing code in Program.cs
   // ... ...
   
   // Add Azure App Configuration services to IServiceCollection
   builder.Services.AddAzureAppConfiguration();
   

2. Actualice la configuración resolviendo una instancia de IConfigurationRefresherProvider de la colección de servicios e invocando TryRefreshAsync en cada uno de sus actualizadores.

   class SampleConfigRefresher
   {
       private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;
   
       public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
       {
           _refreshers = refresherProvider.Refreshers;
       }
   
       public async Task RefreshConfiguration()
       {
           foreach (var refresher in _refreshers)
           {
               _ = refresher.TryRefreshAsync();
           }
       }
   }
   

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

1. Establezca una variable de entorno llamada ConnectionString y defínala como la clave de acceso a su almacén de App Configuration. Si usa el símbolo del sistema de Windows, ejecute el siguiente comando y reinícielo para que se aplique el cambio:

    setx ConnectionString "<connection-string-of-your-app-configuration-store>"
   

   Si usa Windows PowerShell, ejecute el siguiente comando:

    $Env:ConnectionString = "<connection-string-of-your-app-configuration-store>"
   

   Si usa macOS o Linux, ejecute el siguiente comando:

    export ConnectionString='<connection-string-of-your-app-configuration-store>'
   

2. Ejecute el siguiente comando para compilar la aplicación de consola:

    dotnet build
   

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

    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:

   Clave	Value
   TestApp:Settings:Message	Datos de Azure App Configuration, actualizados

6. Presione la tecla Entrar para desencadenar una actualización e imprimir el valor actualizado en la ventana del símbolo del sistema o de PowerShell.

   

   Nota:

   Dado que el tiempo de expiración de la caché se estableció en 10 segundos mediante el método SetCacheExpiration al especificar la configuración para la operación de actualización, el valor de la configuración solo se actualizará si han transcurrido al menos 10 segundos desde la última actualización de dicha configuración.

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. Si tiene una aplicación ASP.NET Core, consulte estas instrucciones para Registrar y supervisar en ASP.NET Core. De lo contrario, puede habilitar el registro mediante las instrucciones para el registro con el SDK de Azure.

• Los registros se generan en distintos niveles de eventos. El nivel predeterminado es Informational.

  Nivel de evento	Descripción
  Verbose	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.
  Informativo	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 Verbose nivel de evento especificando el parámetro EventLevel.Verbose, como se hace en el ejemplo siguiente. Estas instrucciones también se aplican a todos los demás niveles de eventos. En este ejemplo también se habilitan los registros solo para la categoría Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh.

  using var listener = new AzureEventSourceListener((eventData, text) =>
  {
      if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
      {
          Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
      }
  }, EventLevel.Verbose);
  

• 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 evento:

  [Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  [Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  Setting updated. Key:'ExampleKey'
  
  [Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  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'
  

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.

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 de .NET para actualizar dinámicamente la configuración a partir de App Configuration. Para obtener información sobre cómo usar una identidad administrada de Azure para simplificar el acceso a App Configuration, vaya al siguiente tutorial.

Integración de identidades administradas