Fournisseur de configuration .NET

Azure App Configuration est un service managé qui permet aux développeurs de centraliser leurs configurations d’application de façon simple et sécurisée. La bibliothèque du fournisseur de configuration .NET permet de charger la configuration à partir d’un magasin Azure App Configuration de manière managée. Cette bibliothèque cliente ajoute des fonctionnalités supplémentaires au-dessus du Kit de développement logiciel (SDK) Azure pour .NET.

Charger la configuration

Le fournisseur de configuration .NET Azure App Configuration s’intègre au système de configuration .NET, ce qui facilite le chargement des valeurs de configuration à partir de votre magasin Azure App Configuration. Vous pouvez ajouter le fournisseur au démarrage de l’application et l’utiliser avec d’autres sources de configuration.

Pour utiliser le fournisseur de configuration .NET, installez le package :

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Vous appelez la méthode d'extension AddAzureAppConfiguration sur IConfigurationBuilder pour ajouter Azure App Configuration comme fournisseur de configuration pour votre application.

La bibliothèque du fournisseur de configuration implémente un modèle d’options et un modèle de générateur combinés pour fournir un moyen propre et déclaratif de configurer le AzureAppConfigurationOptions. La AddAzureAppConfiguration méthode accepte un Action<AzureAppConfigurationOptions> paramètre délégué qui vous permet de configurer le fournisseur via une API Fluent.

Pour vous connecter à votre magasin Azure App Configuration, appelez la méthode Connect sur l’instance AzureAppConfigurationOptions, qui retourne le même objet d’options pour activer le chaînage de méthodes.

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!");

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

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

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

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

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

Utiliser la configuration

Après avoir ajouté le fournisseur Azure App Configuration, vous pouvez accéder à vos valeurs de configuration de plusieurs façons :

1. Accès direct

L’approche la plus simple consiste à récupérer des valeurs directement à partir de l’instance IConfiguration :

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

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

2. Injection de dépendances avec IConfiguration

Dans les services ou les contrôleurs, vous pouvez injecter et utiliser directement l’interface 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. Modèle d’options pour la configuration fortement typée

// 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"));

Pour plus d’informations sur le modèle d’options dans .NET, consultez la documentation.

Gestion des types de contenu JSON

Vous pouvez créer des valeurs de clé JSON dans App Configuration. Lorsqu’une clé-valeur avec le type de contenu "application/json" est lue, le fournisseur de configuration l’aplatit en paramètres individuels à l’intérieur de IConfiguration. Pour plus d’informations, accédez à Utiliser le type de contenu pour stocker des valeurs de clé JSON dans App Configuration.

Charger des valeurs de clé spécifiques à l’aide de sélecteurs

Par défaut, le fournisseur de configuration charge toutes les valeurs de clé sans étiquette à partir d’App Configuration. Vous pouvez charger de manière sélective des valeurs de clé à partir de votre magasin App Configuration en appelant la méthode Select sur 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" })
});

La Select méthode prend trois paramètres. Le premier paramètre est un filtre de clé qui spécifie les clés à charger, le deuxième paramètre est un filtre d’étiquette qui spécifie les valeurs clés avec des étiquettes spécifiques à charger, et le troisième paramètre spécifie une collection de filtres d’étiquettes qui doivent tous être présents sur une valeur clé à charger.

Filtre principal

Le paramètre de filtre de clé détermine les clés de configuration à inclure :

• Correspondance exacte : l’utilisation d’une chaîne spécifique correspond uniquement aux clés qui correspondent exactement au filtre.
• Correspondance de préfixe : l’ajout d’un astérisque (*) à la fin crée un filtre de préfixe (par exemple, App:Settings:* charge toutes les clés à partir de « App :Settings : »).
• Sélection de plusieurs clés : l’utilisation d’une virgule (,) autorise la sélection de plusieurs clés explicites (par exemple Key1,Key2,Key3).
• Caractères réservés : l'astérisque (*), la virgule (,) et la barre oblique inverse (\) sont réservés et doivent être précédés d'une barre oblique inverse lorsqu’ils sont utilisés dans les noms de clés (par exemple, le filtre a\\b\,\*c* renvoie toutes les paires clé-valeur dont la clé commence par a\b,*c.).

Filtre d’étiquette

Le paramètre de filtre d’étiquette sélectionne les valeurs clés avec une étiquette spécifique. S’il n’est pas spécifié, le composant LabelFilter.Null intégré est utilisé.

Filtres d’étiquettes

Le paramètre de filtre d’étiquettes sélectionne les valeurs clés avec des balises spécifiques. Une clé-valeur est chargée uniquement si toutes les balises et les valeurs correspondantes sont spécifiées dans les filtres. Pour spécifier une valeur Null pour une balise, l’élément TagValue.Null intégré peut être utilisé.

Supprimer le préfixe des clés

Lorsque vous chargez des valeurs de configuration avec des préfixes spécifiques, vous pouvez utiliser la TrimKeyPrefix méthode pour supprimer ces préfixes des clés de votre configuration. Cela crée des clés de configuration plus propres dans votre application tout en conservant l’organisation dans votre magasin 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:");
});

Par exemple, si votre magasin App Configuration contient une clé nommée TestApp:Settings:Message, elle sera accessible dans votre application comme Settings:Message après avoir supprimé le TestApp: préfixe.

Mappage des paramètres de configuration

Lors du chargement de clés à partir d’Azure App Configuration, le fournisseur les récupère d’abord en tant qu’objets ConfigurationSetting avant de les ajouter au système de configuration .NET. L’API Map vous permet de transformer ces paramètres pendant ce pipeline, ce qui vous permet de contrôler la façon dont les configurations apparaissent dans votre application.

La Map méthode accepte une fonction déléguée qui reçoit un ConfigurationSetting objet, vous permet de la modifier et retourne un ValueTask<ConfigurationSetting>. Cela est particulièrement utile pour les transformations de nom de clé ou la mise en forme de valeur en fonction des conditions d’exécution.

L’exemple suivant illustre l’utilisation de l’API Map pour remplacer les traits de soulignement doubles (__) par les deux-points (:) dans les clés de configuration. Cette transformation conserve la structure hiérarchique attendue par la configuration .NET lorsque les clés doivent utiliser d’autres caractères dans 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);
        });
});

Actualisation de la configuration

La configuration de l’actualisation permet à l’application d’extraire les dernières valeurs du magasin App Configuration sans avoir à redémarrer. Vous pouvez appeler la méthode ConfigureRefresh pour configurer l'actualisation clé/valeur.

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));
        });
});

Dans la ConfigureRefresh méthode, vous appelez la RegisterAll méthode pour indiquer au fournisseur App Configuration de recharger la configuration chaque fois qu’il détecte une modification dans l’une des valeurs clés sélectionnées (celles commençant par TestApp : et sans étiquette).

Vous pouvez ajouter un appel à la méthode SetRefreshInterval pour spécifier le temps minimal entre les actualisations de configuration. S’il n’est pas défini, l’intervalle d’actualisation par défaut est de 30 secondes.

Déclencher l’actualisation

Pour déclencher l’actualisation, vous devez appeler la TryRefreshAsync méthode du IConfigurationRefresher. Azure App Configuration fournit plusieurs modèles d’implémentation en fonction de votre architecture d’application.

1. Injection de dépendances

Pour les applications qui utilisent l’injection de dépendances (y compris ASP.NET Core et les services en arrière-plan), enregistrez le service d’actualisation :

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() ajoute le service IConfigurationRefreshProvider au conteneur DI, ce qui vous donne accès aux actualisateurs de toutes les sources de la configuration d'application Azure App Configuration.

Applications ASP.NET Core

Pour les applications ASP.NET Core, vous pouvez utiliser le Microsoft.Azure.AppConfiguration.AspNetCore package pour obtenir une actualisation de configuration pilotée par la requête avec un intergiciel intégré.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Après avoir enregistré le service, appelez le UseAzureAppConfiguration pour ajouter le AzureAppConfigurationRefreshMiddleware dans le pipeline de votre application afin d'actualiser automatiquement la configuration des requêtes 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();
...

Le AzureAppConfigurationRefreshMiddleware vérifie automatiquement les modifications de configuration à l’intervalle configuré pour l’actualisation. Cette approche est efficace car elle s’actualise uniquement lorsque les deux conditions sont remplies : une requête HTTP est reçue et l’intervalle d’actualisation s’est écoulé.

Services en arrière-plan

Pour les services en arrière-plan, vous pouvez injecter le service IConfigurationRefresherProvider et actualiser manuellement chacun des rafraîchisseurs inscrits.

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. Accès direct

Pour les applications qui n’utilisent pas l’injection de dépendances, vous pouvez obtenir l’actualisation directement à partir des options :

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"]);

Actualiser sur la clé sentinelle

Une clé Sentinel est une clé que vous mettez à jour après avoir modifié toutes les autres clés. Le fournisseur de configuration surveille la clé sentinelle au lieu de toutes les valeurs de clé sélectionnées. Lorsqu’un changement est détecté, votre application actualise toutes les valeurs de configuration.

Cette approche est utile lors de la mise à jour de plusieurs valeurs clés. En mettant à jour la clé Sentinel uniquement une fois toutes les autres modifications de configuration terminées, vous assurez que votre application recharge la configuration une seule fois, en conservant la cohérence.

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);
        });
});

Pour plus d’informations sur la configuration de l’actualisation, accédez au tutoriel : Utiliser la configuration dynamique dans une application ASP.NET Core.

Indicateur de fonctionnalité

Les indicateurs de fonctionnalité dans Azure App Configuration offrent un moyen moderne de contrôler la disponibilité des fonctionnalités dans vos applications. Contrairement aux valeurs de configuration régulières, les indicateurs de fonctionnalité doivent être chargés explicitement à l’aide de la UseFeatureFlags méthode. Vous pouvez configurer FeatureFlagOptions pour charger des flags de fonctionnalité spécifiques en utilisant des sélecteurs et définir l’intervalle de rafraîchissement des flags de fonctionnalité.

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));
        });
});

À l’intérieur de la UseFeatureFlags méthode, vous appelez la Select méthode pour charger sélectivement des indicateurs de fonctionnalité. Vous pouvez utiliser le filtre de clé, le filtred’étiquette et les filtres d’étiquettes pour sélectionner les indicateurs de fonctionnalité que vous souhaitez charger. Si aucune méthode n’est Select appelée, UseFeatureFlags charge tous les indicateurs de fonctionnalité sans étiquette par défaut.

Différents des valeurs clés, les indicateurs de fonctionnalité sont automatiquement inscrits pour l’actualisation sans nécessiter d’appel explicite ConfigureRefresh . Vous pouvez spécifier la durée minimale entre les actualisations de l’indicateur de fonctionnalité par le biais de la SetRefreshInterval méthode. L’intervalle d’actualisation par défaut est de 30 secondes.

Gestion des fonctionnalités

La bibliothèque de gestion des fonctionnalités permet de développer et d’exposer les fonctionnalités d’application en fonction des indicateurs de fonctionnalité. La bibliothèque de gestion des fonctionnalités est conçue pour fonctionner conjointement avec la bibliothèque du fournisseur de configuration. Installez le package Microsoft.FeatureManagement :

dotnet add package Microsoft.FeatureManagement

Vous pouvez appeler AddFeatureManagement pour inscrire IVariantFeatureManager et les services connexes dans le conteneur DI. Cette inscription rend la fonctionnalité d’indicateur de fonctionnalité disponible dans l’ensemble de votre application via l’injection de dépendances.

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();

L’exemple suivant montre comment utiliser le service Feature Manager via l’injection de dépendances :

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");
    }
}

Pour plus d’informations sur l’utilisation de la bibliothèque de gestion des fonctionnalités, accédez au guide de démarrage rapide de l’indicateur de fonctionnalité.

Télémétrie de l’indicateur de fonctionnalité

Lorsque la télémétrie des indicateurs de fonctionnalité est activée, le fournisseur Azure App Configuration injecte des propriétés supplémentaires pour les données de télémétrie des indicateurs de fonctionnalité. Ces propriétés fournissent davantage de contexte sur l’indicateur de fonctionnalité et son évaluation :

• AllocationID : identificateur unique représentant l’état de l’allocation de l’indicateur de fonctionnalité.
• ETag : L'ETag actuel pour l'indicateur de configuration.
• FeatureFlagReference : référence à l’indicateur de fonctionnalité au format de <your_store_endpoint>kv/<feature_flag_key>. Lorsqu’une étiquette est présente, la référence l’inclut en tant que paramètre de requête : <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Le schéma complet se trouve dans la définition du schéma d’événement d’évaluation des fonctionnalités App Configuration. Pour plus d’informations sur l’utilisation des données de télémétrie des indicateurs de fonctionnalité, accédez à la procédure pas à pas pour activer la télémétrie pour les indicateurs de fonctionnalité .

Référence Key Vault

Azure App Configuration prend en charge le référencement des secrets stockés dans Azure Key Vault. Dans App Configuration, vous pouvez créer des clés qui associent des secrets stockés dans Key Vault. Les secrets sont stockés en toute sécurité dans Key Vault, mais sont accessibles comme toute autre configuration une fois chargés.

La bibliothèque du fournisseur de configuration récupère les références Key Vault, tout comme pour les autres clés stockées dans App Configuration. Étant donné que le client reconnaît les clés en tant que références Key Vault, ils ont un type de contenu unique et le client se connecte à Key Vault pour récupérer leurs valeurs pour votre application.

Se connecter à Key Vault

Vous devez appeler la ConfigureKeyVault méthode pour configurer la connexion à Key Vault. Le fournisseur Azure App Configuration offre plusieurs façons d’authentifier et d’accéder à vos secrets Key Vault.

1. Inscrire une SecretClient instance

Vous pouvez inscrire des instances spécifiées SecretClient à utiliser pour résoudre les références de coffre de clés pour les secrets du coffre de clés associé.

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. Utiliser les informations d’identification

Vous pouvez définir les informations d’identification utilisées pour s’authentifier auprès des coffres de clés qui n’ont pas d’inscription 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. Utiliser un résolveur de secret personnalisé

Vous pouvez également appeler SetSecretResolver pour ajouter un résolveur de secret personnalisé qui est utilisé lorsqu’aucun enregistrement SecretClient n’est disponible ou que les informations d’identification fournies ne parviennent pas à s’authentifier dans Key Vault. Cette méthode accepte une fonction déléguée qui résout un URI Key Vault en valeur secrète. L’exemple suivant illustre l’utilisation d’un programme de résolution de secrets qui récupère un secret à partir de variables d’environnement dans le développement et utilise des valeurs de secours lorsqu’il ne parvient pas à obtenir le secret à partir 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");
                }
            });
        });
});

Actualisation du secret dans Key Vault

Azure App Configuration vous permet de configurer les intervalles d’actualisation des secrets indépendamment de votre cycle d’actualisation de configuration. Cela est essentiel pour la sécurité, car bien que l’URI de référence Key Vault dans App Configuration reste inchangé, le secret sous-jacent dans Key Vault peut être pivoté dans le cadre de vos pratiques de sécurité.

Pour vous assurer que votre application utilise toujours les valeurs secrètes les plus actuelles, configurez la SetSecretRefreshInterval méthode. Cela force le fournisseur à récupérer de nouvelles valeurs secrètes à partir de Key Vault quand :

• Appels de votre application IConfigurationRefresher.TryRefreshAsync
• L’intervalle d’actualisation configuré pour le secret s’est écoulé

Ce mécanisme fonctionne même quand aucune modification n’est détectée dans votre magasin App Configuration, ce qui garantit que votre application reste synchronisée avec les secrets pivotés.

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());
});

Pour plus d’informations sur l’utilisation de la référence Key Vault, consultez le tutoriel : Utiliser des références Key Vault dans une application ASP.NET Core.

Instantané

Un instantané est un sous-ensemble nommé et immuable des valeurs clés d’un magasin de App Configuration. Les valeurs clés qui composent un instantané sont choisies au moment de la création via l’utilisation de filtres de clé et d’étiquette. Une fois qu’un instantané est créé, ses valeurs clés sont assurées de rester inchangées.

Vous pouvez appeler SelectSnapshot pour charger des valeurs de clé à partir d’un instantané.

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");
});

Pour plus d’informations sur l’utilisation des instantanés, accédez à Créer et utiliser des instantanés.

Référence de l'instantané

Une référence d’instantané est un paramètre de configuration qui fait référence à un instantané dans le même magasin App Configuration. Lorsqu’il est chargé, le fournisseur le résout et ajoute toutes les valeurs clés de cet instantané. L’utilisation de références d’instantanés permet de basculer entre les instantanés au moment de l’exécution, contrairement SelectSnapshot("...")à ce qui nécessite des modifications de code et/ou des redémarrages pour basculer vers un nouvel instantané.

Pour plus d’informations sur la création d’une référence d’instantané, accédez au concept de référence d’instantané.

Nouvelle tentative de démarrage

Le chargement de la configuration est une opération de chemin critique au démarrage de l’application. Pour garantir la fiabilité, le fournisseur Azure App Configuration implémente un mécanisme de nouvelle tentative robuste pendant la charge de configuration initiale. Cela permet de protéger votre application contre les problèmes réseau temporaires susceptibles d’empêcher le démarrage réussi.

Vous pouvez personnaliser ce comportement à l’aide de la ConfigureStartupOptions méthode :

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);
        });
});

Géoréplication

Pour plus d’informations sur l’utilisation de la géoréplication, accédez à Activer la géoréplication.

Suivi distribué

Le fournisseur .NET Azure App Configuration inclut la prise en charge intégrée du suivi distribué, ce qui vous permet de surveiller et de résoudre les problèmes d’opérations de configuration dans votre application. Le fournisseur expose un ActivitySource nommé "Microsoft.Extensions.Configuration.AzureAppConfiguration" qui commence Activity pour les opérations clés telles que le chargement et l’actualisation de la configuration.

L’exemple suivant montre comment configurer OpenTelemetry pour capturer et surveiller les traces distribuées générées par le fournisseur de configuration :

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

Pour plus d’informations sur OpenTelemetry dans .NET, consultez la documentation OpenTelemetry .NET.

Contrôle d’intégrité

Le fournisseur .NET Azure App Configuration prend en charge les vérifications d’intégrité des applications .NET. Pour activer les vérifications d’intégrité, vous pouvez appeler AddAzureAppConfiguration() une méthode sur IHealthChecksBuilderlaquelle ajouter IHealthCheck un nom "Microsoft.Extensions.Configuration.AzureAppConfiguration"d’inscription par défaut.

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

builder.Services.AddHealthChecks()
    .AddAzureAppConfiguration();

Le fournisseur .NET est considéré comme défectueux lorsque la dernière tentative de chargement ou d’actualisation a échoué.

Pour plus d’informations sur les vérifications d’intégrité dans .NET, consultez la documentation de surveillance de l’intégrité .NET.

Se connecter à Azure Front Door

L’intégration d’Azure Front Door permet aux applications clientes d’extraire la configuration à partir de points de terminaison mis en cache de périphérie plutôt que directement à partir d’App Configuration. Cette architecture offre un accès de configuration sécurisé et évolutif avec les avantages en matière de performances de la distribution de CDN globale. Pour obtenir des instructions de configuration, consultez Charger la configuration à partir d’Azure Front Door dans les applications clientes.

Étapes suivantes

Pour savoir comment utiliser le fournisseur de configuration .NET, passez au tutoriel suivant.