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

2025-04-24

La biblioteca de proveedores de .NET de App Configuration admite la actualización de la configuración a petición sin hacer que una aplicación se reinicie. En este tutorial se muestra cómo puede implementar actualizaciones de configuración dinámicas en el código. Se basa en la aplicación introducida en el inicio rápido. Debe finalizar La creación de una aplicación .NET con App Configuration antes de continuar.

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 su aplicación .NET para actualizar su configuración en respuesta a los cambios en el almacén de configuración de aplicaciones.
Consuma en la aplicación la configuración más reciente.

Prerrequisitos

Si no tiene una cuenta de Azure, cree una cuenta gratuita antes de comenzar.

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

Actualización de configuración controlada por actividad

Abra Program.cs y actualice el archivo con el código siguiente. 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.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(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!");

}

Dentro del método ConfigureRefresh, se invoca al método RegisterAll para instruir 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 (en este caso, solo TestApp:Settings:Message). 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.

El método SetRefreshInterval 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 estar en un temporizador si la aplicación está activa todo el tiempo. En este ejemplo, llamas TryRefreshAsync cada vez que presionas la tecla Intro. Incluso si se produce un error en la llamada TryRefreshAsync por cualquier motivo, la aplicación sigue usando la configuración almacenada en caché. Otro intento se realiza cuando se ha pasado el intervalo de actualización configurado y la llamada se desencadena de nuevo por la TryRefreshAsync actividad de la aplicación. Llamar a TryRefreshAsync no tiene efecto antes de que transcurre el intervalo de actualización configurado, por lo que su impacto en el rendimiento es mínimo incluso si se llama con frecuencia.

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

En el código anterior, estás guardando 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.

Registre los servicios de App Configuration necesarios al invocar AddAzureAppConfiguration en IServiceCollection.

Agregue el código siguiente a Program.cs.
```
// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();
```

Actualice su configuración resolviendo una instancia de IConfigurationRefresherProvider de su colección de servicios e invocando TryRefreshAsync en cada uno de sus refrescadores.

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

Establezca una variable de entorno denominada Punto de conexión en el punto de conexión del almacén de App Configuration que se encuentra en la Información general del almacén en Azure Portal.

Si usa el símbolo del sistema de Windows, ejecute el siguiente comando y reinícielo para que se aplique el cambio:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Si usa PowerShell, ejecute el siguiente comando:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Si usa macOS o Linux, ejecute el siguiente comando:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Ejecute el siguiente comando para compilar la aplicación de consola:
```
 dotnet build
```
Una vez que la compilación se haya realizado correctamente, ejecute el siguiente comando para ejecutar la aplicación localmente:
```
 dotnet run
```
Inicie sesión en Azure Portal. Seleccione Todos los recursos y seleccione la instancia del 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:

Clave Importancia

TestApp:Configuración:Mensaje Datos de Azure App Configuration: actualizado
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 intervalo de actualización se estableció en 10 segundos mediante el SetRefreshInterval método mientras se especifica la configuración para la operación de actualización, el valor de la configuración solo se actualizará si al menos 10 segundos han transcurrido desde la última actualización para esa configuración.

Clave	Importancia
TestApp:Configuración:Mensaje	Datos de Azure App Configuration: 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. Si tiene una aplicación ASP.NET Core, consulte estas instrucciones para Supervisión y registro 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
Detallado	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 EventLevel.Verbose parámetro , 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 Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh categoría.

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.

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 .NET para actualizar dinámicamente las opciones de configuración desde 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