Compartir a través de

Proveedor de configuración de .NET

Microsoft.Extensions.Configuration.AzureAppConfiguration

Azure App Configuration es un servicio administrado que ayuda a los desarrolladores a centralizar la configuración de sus aplicaciones de forma sencilla y segura. La biblioteca del proveedor de configuración de .NET permite cargar la configuración desde un almacén de Azure App Configuration de forma administrada. Esta biblioteca cliente agrega funcionalidad adicional sobre el SDK de Azure para .NET.

Configuración de carga

El proveedor de configuración de .NET de Azure App Configuration se integra con el sistema de configuración de .NET, lo que facilita la carga de valores de configuración desde el almacén de Azure App Configuration. Puede agregar el proveedor durante el inicio de la aplicación y usarlo junto con otros orígenes de configuración.

Para usar el proveedor de configuración de .NET, instale el paquete:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Llamas al método de extensión AddAzureAppConfiguration en IConfigurationBuilder para agregar Azure App Configuration como proveedor de configuración de tu aplicación.

La biblioteca del proveedor de configuración implementa un patrón de opciones combinado y un patrón de creación para proporcionar una manera limpia y declarativa de configurar el . El AddAzureAppConfiguration método acepta un Action<AzureAppConfigurationOptions> parámetro delegado que permite configurar el proveedor a través de una API fluida.

Para conectarse al almacén de Azure App Configuration, llame al método Connect en la instancia AzureAppConfigurationOptions, que devuelve el mismo objeto de opciones para habilitar la cadena de métodos.

Puede usar DefaultAzureCredential o cualquier otra implementación de credenciales de token, para autenticarse en el almacén de App Configuration. Siga las instrucciones para asignar tu credencial al rol Lector de datos de App Configuration.

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

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("AppConfigurationEndpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

Nota:

En una aplicación ASP.NET Core o en un servicio en segundo plano, puede llamar a AddAzureAppConfiguration en builder.Configuration.

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

Consumo de la configuración

Después de agregar el proveedor de Azure App Configuration, puede acceder a los valores de configuración de varias maneras:

1. Acceso directo

El enfoque más sencillo es recuperar valores directamente de la IConfiguration instancia:

// Directly get the configuration
string message = configuration["TestApp:Settings:Message"];

IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");

2. Inserción de dependencias con IConfiguration

En los servicios o controladores, puede inyectar y utilizar directamente la interfaz IConfiguration.

public class WeatherService
{
    private readonly IConfiguration _configuration;

    public WeatherService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public Task<WeatherForecast> GetForecastAsync()
    {
        // Access configuration values directly from the injected instance
        string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];

        ...

        return Task.FromResult(new WeatherForecast());
    }
}

3. Patrón de opciones para la configuración fuertemente tipada

// Define a strongly-typed settings class
public class Settings
{
    public string BackgroundColor { get; set; }
    public long FontSize { get; set; }
    public string FontColor { get; set; }
    public string Message { get; set; }
}

builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

Para obtener más información sobre el patrón de opciones en .NET, vaya a la documentación.

Control de tipos de contenido JSON

Puede crear valores de clave JSON en App Configuration. Cuando se lee un par clave-valor con el tipo de contenido "application/json", el proveedor de configuración lo aplanará en una configuración individual dentro de IConfiguration. Para obtener más información, vaya a Usar el tipo de contenido para almacenar los valores de clave JSON en App Configuration.

Carga de pares clave-valor específicos mediante selectores

De manera predeterminada, el proveedor de configuración carga todos los pares clave-valor sin etiqueta de App Configuration. Puede cargar de forma selectiva los pares clave-valor desde el almacén de App Configuration llamando al método Select en AzureAppConfigurationOptions.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and no label
        .Select("App:Settings:*")
        // Load configuration values with prefix "TestApp:" and "Prod" label
        .Select("App:Settings:*", "Prod")
        // Load configuration values with prefix "TestApp:" and "Prod" label that have the tag "Group" with value "Contoso"
        .Select("App:Settings:*", "Prod", new[] { "Group=Contoso" })
});

El Select método toma tres parámetros. El primer parámetro es un filtro de clave que especifica las claves que se van a cargar, el segundo parámetro es un filtro de etiqueta que especifica qué valores de clave con etiquetas específicas se van a cargar y el tercer parámetro especifica una colección de filtros de etiquetas que todos deben estar presentes en un valor de clave que se va a cargar.

Nota:

Cuando varias Select llamadas incluyen claves superpuestas, las llamadas posteriores tienen prioridad sobre las anteriores.

Filtro de clave

El parámetro de filtro de clave determina qué claves de configuración se van a incluir:

  • Coincidencia exacta: el uso de una cadena específica solo coincide con las claves que coinciden exactamente con el filtro.
  • Coincidencia de prefijo: al agregar un asterisco (*) al final se crea un filtro de prefijo (por ejemplo, App:Settings:* se cargan todas las claves a partir de "App:Settings:").
  • Selección de varias teclas: el uso de una coma (,) permite la selección de varias claves explícitas (por ejemplo, Key1,Key2,Key3).
  • Caracteres reservados: los caracteres asterisco (*), coma (,) y barra diagonal inversa (\) están reservados y deben tener un escape con una barra diagonal inversa cuando se usa en nombres de clave (por ejemplo, el filtro a\\b\,\*c* de claves devuelve todos los valores de clave cuya clave comienza por a\b,*c.).

Nota:

No se puede combinar la coincidencia de prefijos con caracteres comodín con filtros separados por comas en la misma llamada Select. Por ejemplo, abc*,def no se admite, pero puede realizar llamadas independientes Select con abc* y def.

Filtro de etiqueta

El parámetro de filtro de etiqueta selecciona los valores de clave con una etiqueta específica. Si no se especifica, se usa el elemento integrado LabelFilter.Null .

Nota:

Los caracteres asterisco (*) y coma (,), no se admiten para el filtro de etiquetas. El carácter de barra diagonal inversa (\) está reservado y debe tener un escape mediante otra barra diagonal inversa (\).

Filtros de etiquetas

El parámetro de filtros de etiqueta selecciona los valores clave con etiquetas específicas. Solo se carga un valor de clave si tiene todas las etiquetas y los valores correspondientes especificados en los filtros. Para especificar un valor NULL para una etiqueta, se puede usar el elemento integrado TagValue.Null .

Nota:

Los caracteres asterisco (*), coma (,) y barra diagonal inversa (\) están reservados y se les debe aplicar escapar con una barra diagonal inversa cuando se usan en un filtro de etiqueta.

Recorte del prefijo de las claves

Al cargar valores de configuración con prefijos específicos, puede usar el TrimKeyPrefix método para quitar esos prefijos de las claves de la configuración. Esto crea claves de configuración más limpias en tu aplicación, mientras se mantiene la organización en la tienda App Configuration.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and trim the prefix
        .Select("TestApp:*")
        .TrimKeyPrefix("TestApp:");
});

Por ejemplo, si el almacén de App Configuration contiene una clave denominada TestApp:Settings:Message, será accesible en la aplicación como Settings:Message después de eliminar el prefijo TestApp:.

Asignación de opciones de configuración

Al cargar los valores de clave desde Azure App Configuration, el proveedor los recupera primero como ConfigurationSetting objetos antes de agregarlos al sistema de configuración de .NET. La Map API le permite transformar esta configuración durante esta canalización, lo que le proporciona control sobre cómo aparecen las configuraciones en la aplicación.

El Map método acepta una función de delegado que recibe un ConfigurationSetting objeto, le permite modificarlo y devuelve un ValueTask<ConfigurationSetting>. Esto es especialmente útil para las transformaciones de nombre de clave o el formato de valor en función de las condiciones del tiempo de ejecución.

En el ejemplo siguiente se muestra el uso de la Map API para reemplazar caracteres de subrayado dobles (__) por dos puntos (:) en las claves de configuración. Esta transformación conserva la estructura jerárquica esperada por la configuración de .NET cuando las claves necesitan usar caracteres alternativos en App Configuration:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .Map((setting) =>
        {
            // Transform keys from format "App__Settings__Message" to "App:Settings:Message"
            setting.Key = setting.Key.Replace("__", ":");
            
            return new ValueTask<ConfigurationSetting>(setting);
        });
});

Sugerencia

La Map operación se aplica a todas las opciones de configuración recuperadas de App Configuration, por lo que asegúrese de que la lógica de transformación controla todos los formatos de clave posibles correctamente.

Actualización de configuración

La configuración de la actualización permite a la aplicación extraer los valores más recientes del almacén de App Configuration sin tener que reiniciarse. Puede llamar al método ConfigureRefresh para configurar la actualización de par clave-valor.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh when any selected key changes.
            refreshOptions.RegisterAll()
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Dentro del ConfigureRefresh método, se llama al RegisterAll método para indicar al proveedor de App Configuration que vuelva a cargar la configuración siempre que se detecte un cambio en cualquiera de los valores clave seleccionados (aquellos que comienzan con TestApp: y no tienen etiqueta).

Puede agregar una llamada al método SetRefreshInterval para especificar el tiempo mínimo entre las actualizaciones de configuración. Si no se establece, el intervalo de actualización predeterminado es de 30 segundos.

Activar actualización

Para desencadenar la actualización, debe llamar al método TryRefreshAsync de IConfigurationRefresher. Azure App Configuration proporciona varios patrones para la implementación en función de la arquitectura de la aplicación.

1. Inserción de dependencia

En el caso de las aplicaciones que usan la inserción de dependencias (incluidos ASP.NET Core y servicios en segundo plano), registre el servicio de actualización:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromSeconds(60));
           })
});

// Register refresher service with the DI container
builder.Services.AddAzureAppConfiguration();

builder.Services.AddAzureAppConfiguration() agrega el servicio IConfigurationRefreshProvider al contenedor de DI, que proporciona acceso a los actualizadores de todos los orígenes de Azure App Configuration en la configuración de la aplicación.

Aplicaciones de ASP.NET Core

Para las aplicaciones ASP.NET Core, puede usar el Microsoft.Azure.AppConfiguration.AspNetCore paquete para lograr la actualización de configuración controlada por solicitudes con un middleware integrado.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Después de registrar el servicio, llame al UseAzureAppConfiguration para agregar el AzureAppConfigurationRefreshMiddleware a la canalización de su aplicación y actualizar automáticamente la configuración de las solicitudes entrantes.

...

// Call the AddAzureAppConfiguration to add refresher service to the DI container
builder.Services.AddAzureAppConfiguration();

var app = builder.Build();

// Call the app.UseAzureAppConfiguration() method as early as appropriate in your request pipeline so another middleware doesn't skip it
app.UseAzureAppConfiguration();

// Continue with other middleware registration
app.UseRouting();
...

AzureAppConfigurationRefreshMiddleware comprueba automáticamente los cambios de configuración en el intervalo de actualización configurado. Este enfoque es eficaz, ya que solo se actualiza cuando se cumplen ambas condiciones: se recibe una solicitud HTTP y el intervalo de actualización ha transcurrido.

Servicios en segundo plano

En el caso de los servicios en segundo plano, puede inyectar el servicio IConfigurationRefresherProvider y actualizar manualmente cada uno de los refrescadores registrados.

public class Worker : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly IEnumerable<IConfigurationRefresher> _refreshers;

    public Worker(IConfiguration configuration, IConfigurationRefresherProvider refresherProvider)
    {
        _configuration = configuration;
        _refreshers = refresherProvider.Refreshers;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        foreach (IConfigurationRefresher refresher in _refreshers)
        {
            refresher.TryRefreshAsync();
        }

        ...
    }
}

2. Acceso directo

En el caso de las aplicaciones que no usan la inserción de dependencias, puede obtener el actualizador directamente desde las opciones:

IConfigurationRefresher refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
               refreshOptions.RegisterAll();
           });

    // Store the refresher for later use
    refresher = options.GetRefresher();
});

IConfiguration config = builder.Build();

// Later in your code, trigger refresh when needed
if (refresher != null)
{
    await refresher.TryRefreshAsync()
}

Console.WriteLine(config["TestApp:Settings:Message"]);

Nota:

Incluso si se produce un error en la llamada de actualización por cualquier motivo, la aplicación sigue usando la configuración almacenada en caché. Se realiza otro intento después de un breve período en función de la actividad de la aplicación. La llamada a la actualización es una operación no operativa antes de que transcurra 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 en la clave Sentinel

Una clave de Sentinel es una clave que se actualiza después de completar el cambio de todas las demás claves. El proveedor de configuración supervisa la clave sentinel en lugar de todos los valores de clave seleccionados. Cuando se detecta un cambio, la aplicación actualiza todos los valores de configuración.

Este enfoque es útil al actualizar varios valores de clave. Al actualizar la clave centinela solo después de que se completen todos los demás cambios de configuración, asegúrese de que la aplicación vuelve a cargar la configuración una vez, manteniendo la coherencia.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh only if the `SentinelKey` changes.
            refreshOptions.Register("SentinelKey", refreshAll: true);
        });
});

Importante

Los valores de clave no se registran automáticamente para la supervisión de actualizaciones. Debe llamar ConfigureRefresh explícitamente y, a continuación, registrar claves mediante el RegisterAll método (para supervisar todas las claves cargadas) o el Register método (para supervisar una clave individual).

Para obtener más información sobre la configuración de actualización, vaya a Tutorial: Uso de la configuración dinámica en una aplicación ASP.NET Core.

Marca de características

Las marcas de características de Azure App Configuration proporcionan una manera moderna de controlar la disponibilidad de características en las aplicaciones. A diferencia de los valores de configuración normales, las marcas de características deben cargarse explícitamente mediante el UseFeatureFlags método . Puede configurar en FeatureFlagOptions para cargar marcas de características específicas mediante selectores y establecer el intervalo de actualización de marcas de características.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .UseFeatureFlags(featureFlagOptions => {
            // Load feature flags with prefix "TestApp:" and "dev" label
            featureFlagOptions.Select("TestApp:*", "dev")
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Dentro del método UseFeatureFlags, se llama al método Select para cargar selectivamente las banderas de funciones. Puede usar el filtro de claves, el filtro de etiquetas y los filtros de etiquetas para seleccionar las marcas de características que desea cargar. Si no se llama a ningún Select método, UseFeatureFlags carga todas las marcas de características sin etiqueta de forma predeterminada.

A diferencia de los pares clave-valor, las marcas de características se registran automáticamente para la actualización sin necesidad de una llamada explícita a ConfigureRefresh. Puede especificar el tiempo mínimo entre las actualizaciones de la bandera de características mediante el método SetRefreshInterval. El intervalo de actualización predeterminado es de 30 segundos.

Gestión de funcionalidades

La biblioteca de administración de características proporciona una manera de desarrollar y exponer la funcionalidad de la aplicación en función de las marcas de características. La biblioteca de administración de características está diseñada para funcionar junto con la biblioteca de proveedores de configuración. Instala el paquete Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

Puede llamar a AddFeatureManagement para registrar IVariantFeatureManager y servicios relacionados en el contenedor de DI. Este registro hace que la funcionalidad de marca de características esté disponible en toda la aplicación a través de la inserción de dependencias.

using Microsoft.FeatureManagement;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Use feature flags
    options.UseFeatureFlags();
});

// Register feature management services
builder.Services.AddFeatureManagement();

En el ejemplo siguiente se muestra cómo usar el servicio del administrador de características a través de la inserción de dependencias:

public class WeatherForecastController : ControllerBase
{
    private readonly IFeatureManager _featureManager;

    public WeatherForecastController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        // Check if a feature flag is enabled
        if (await _featureManager.IsEnabledAsync("WeatherForecast"))
        {
            var forecast = GenerateWeatherForecast();
            return Ok(forecast);
        }
        
        return NotFound("Weather forecast feature is not available");
    }
}

Para obtener más información sobre cómo usar la biblioteca de administración de características, vaya al inicio rápido de marcas de características.

Referencia de Key Vault

Azure App Configuration admite la referencia a secretos almacenados en Azure Key Vault. En App Configuration, puede crear claves que se asignen a secretos almacenados en Key Vault. Los secretos se almacenan de forma segura en Key Vault, pero se puede acceder a ellos como cualquier otra configuración una vez que se carguen.

La biblioteca de proveedores de configuración recupera las referencias de Key Vault, como hace para cualquier otra clave almacenada en App Configuration. Dado que el cliente reconoce las claves como referencias de Key Vault, tienen un tipo de contenido único y el cliente se conecta a Key Vault para recuperar sus valores para la aplicación.

Conexión a Key Vault

Debe llamar al ConfigureKeyVault método para configurar cómo conectarse a Key Vault. El proveedor de Azure App Configuration ofrece varias maneras de autenticar y acceder a los secretos de Key Vault.

1. Registrar instancia de SecretClient

Puede registrar instancias especificadas de SecretClient que se usarán para resolver las referencias del almacén de claves para los secretos del almacén de claves asociado.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

...

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Register a SecretClient instance
            kv.Register(secretClient);
        });
});

2. Uso de credenciales

Puede establecer la credencial usada para autenticarse en almacenes de claves que no tengan registrado SecretClient.

using Azure.Identity;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Use DefaultAzureCredential to access all Key Vaults
            kv.SetCredential(new DefaultAzureCredential());
        });
});

3. Usar solucionador de secretos personalizado

También puede llamar a SetSecretResolver para agregar un solucionador de secretos personalizado que se utiliza cuando no hay ningún SecretClient registrado disponible o la credencial proporcionada falla al autenticarse en Key Vault. Este método acepta una función de delegado que resuelve un URI de Key Vault en un valor secreto. En el ejemplo siguiente se muestra el uso de un solucionador de secretos que recupera un secreto de las variables de entorno en desarrollo y usa valores de reserva cuando no puede obtener el secreto de Key Vault.

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Add a custom secret resolver function
            kv.SetSecretResolver(async (Uri secretUri) =>
            {                
                if (builder.Environment.IsDevelopment())
                {
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }

                try 
                {
                    var secret = await secretClient.GetSecretAsync(secretName);
                    return secret.Value;
                }
                catch (Exception ex)
                {
                    logger.LogWarning($"Failed to retrieve secret from {secretUri}: {ex.Message}");
                    
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }
            });
        });
});

Nota:

Al resolver las referencias de Key Vault, el proveedor sigue este orden:

  1. Instancias de SecretClient registradas
  2. Credencial predeterminada
  3. Resolución de secretos personalizada

Importante

Si la aplicación carga los valores de clave que contienen referencias de Key Vault sin una configuración adecuada de Key Vault, se producirá una excepción al iniciarse. Asegúrese de que ha configurado correctamente el acceso o la resolución secreta de Key Vault.

Sugerencia

Puede usar un solucionador de secretos personalizado para controlar los casos en los que las referencias de Key Vault se agregan accidentalmente al almacén de App Configuration. El solucionador puede proporcionar valores de reserva, registrar advertencias o manejar adecuadamente la falta de credenciales adecuadas para acceder a Key Vault en lugar de lanzar excepciones.

Actualización de secretos de Key Vault

Azure App Configuration permite configurar intervalos de actualización de secretos independientemente del ciclo de actualización de configuración. Esto es fundamental para la seguridad porque, aunque el URI de referencia de Key Vault en App Configuration permanece sin cambios, el secreto subyacente de Key Vault podría rotarse como parte de las prácticas de seguridad.

Para asegurarse de que la aplicación siempre usa los valores de secreto más actuales, configure el SetSecretRefreshInterval método . Esto obliga al proveedor a recuperar valores secretos nuevos de Key Vault cuando:

  • Su aplicación realiza llamadas IConfigurationRefresher.TryRefreshAsync
  • El intervalo de actualización configurado para el secreto ha transcurrido

Este mecanismo funciona incluso cuando no se detectan cambios en el almacén de App Configuration, lo que garantiza que la aplicación permanezca sincronizada con secretos rotados.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureKeyVault(kv =>
        {
            kv.SetCredential(new DefaultAzureCredential());

            // Option 1: Set refresh interval for specific secrets
            kv.SetSecretRefreshInterval("ApiKey", TimeSpan.FromHours(12)); 
            
            // Option 2: Set a global refresh interval for all secrets with no refresh interval specified
            kv.SetSecretRefreshInterval(TimeSpan.FromHours(24));
        })
        .ConfigureRefresh(refreshOptions => refreshOptions.RegisterAll());
});

Para obtener más información sobre cómo usar la referencia de Key Vault, vaya al Tutorial: Uso de referencias de Key Vault en una aplicación de ASP.NET Core.

Instantánea

Una Instantánea es un subconjunto con nombre inmutable de los pares clave-valor de un almacén de App Configuration. Los valores clave que componen una instantánea se eligen durante el tiempo de creación mediante el uso de filtros de clave y etiqueta. Una vez creada una instantánea, se garantiza que los valores clave que contiene permanecen inalterados.

Puede llamar a SelectSnapshot para cargar los pares clave-valor desde una instantánea.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Select an existing snapshot by name. This adds all of the key-values and feature flags from the snapshot to this application's configuration.
    options.SelectSnapshot("SnapshotName");
});

Para obtener información sobre el uso de instantáneas, vaya a Crear y usar instantáneas.

Reintento de reinicio

La carga de configuración es un proceso crítico durante el inicio de la aplicación. Para garantizar la confiabilidad, el proveedor de Azure App Configuration implementa un mecanismo de reintento sólido durante la carga de configuración inicial. Esto ayuda a proteger la aplicación frente a problemas de red transitorios que podrían impedir el inicio correcto.

Puede personalizar este comportamiento mediante el ConfigureStartupOptions método :

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureStartupOptions(startupOptions =>
        {
            // Set the time-out for the initial configuration load
            startupOptions.Timeout = TimeSpan.FromSeconds(60);
        });
});

Replicación geográfica

Para obtener información sobre el uso de la replicación geográfica, vaya a Habilitación de la replicación geográfica.

Seguimiento distribuido

El proveedor .NET de Azure App Configuration incluye compatibilidad integrada con el seguimiento distribuido, lo que le permite supervisar y solucionar problemas de operaciones de configuración en la aplicación. El proveedor expone un objeto ActivitySource denominado "Microsoft.Extensions.Configuration.AzureAppConfiguration" que inicia Activity para las operaciones de clave, como cargar la configuración y actualizar la configuración.

En el ejemplo siguiente se muestra cómo configurar OpenTelemetry para capturar y supervisar seguimientos distribuidos generados por el proveedor de configuración:

List<Activity> exportedActivities = new();
builder.Services.AddOpenTelemetry()
    .WithTracing(traceBuilder => {
        traceBuilder.AddSource(["Microsoft.Extensions.Configuration.AzureAppConfiguration"]);
            .AddInMemoryExporter(exportedActivities)
    });

Para obtener más información sobre OpenTelemetry en .NET, consulte la documentación de .NET de OpenTelemetry.

Pasos siguientes

Para obtener información sobre cómo usar el proveedor de configuración de .NET, continúe con el siguiente tutorial.

Habilitación de la configuración dinámica en la aplicación web de ASP.NET