Tutoriel : Utiliser la configuration dynamique dans une application .NET

2025-04-18

La bibliothèque de fournisseur .NET App Configuration prend en charge la mise à jour de la configuration à la demande sans entraîner le redémarrage d’une application. Ce tutoriel montre comment implémenter des mises à jour de configuration dynamique dans votre code. Il s’appuie sur l’application présentée dans le guide de démarrage rapide. Vous devez terminer la création d’une application .NET avec App Configuration avant de continuer.

Vous pouvez utiliser l’éditeur de code de votre choix pour exécuter les étapes de ce tutoriel. Visual Studio Code est une excellente option qui est disponible sur les plateformes Windows, macOS et Linux.

Dans ce tutoriel, vous allez apprendre à :

Configurez votre application .NET pour mettre à jour sa configuration en réponse aux modifications apportées à un magasin de configuration d'application.
Utiliser la configuration la plus récente dans votre application.

Conditions préalables

Si vous ne disposez pas d’un compte Azure, créez-en un gratuitement avant de commencer.

Terminez le guide de démarrage rapide Créer une application .NET avec App Configuration.

Actualisation de la configuration basée sur l’activité

Ouvrez Program.cs et mettez à jour le fichier avec le code suivant. Vous pouvez vous connecter à App Configuration à l’aide de Microsoft Entra ID (recommandé) ou d’une chaîne de connexion. L’extrait de code suivant illustre l’utilisation de Microsoft Entra ID.

Vous utilisez le DefaultAzureCredential pour vous authentifier auprès de votre magasin App Configuration. Lors de la fin du guide de démarrage rapide répertorié dans les conditions préalables, vous avez déjà affecté vos informations d’identification au rôle lecteur de données 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!");

}

Dans la ConfigureRefresh méthode, vous appelez la RegisterAll méthode pour indiquer au fournisseur App Configuration de recharger l’intégralité de la configuration chaque fois qu’elle détecte une modification dans l’une des valeurs clés sélectionnées (dans ce cas, simplement TestApp :Settings :Message). Pour plus d’informations sur la surveillance des modifications de configuration, consultez les meilleures pratiques pour l’actualisation de la configuration.

La méthode SetRefreshInterval spécifie le temps minimum qui doit s'écouler avant qu'une nouvelle requête puisse être adressée à App Configuration pour rechercher les changements de configuration. Dans cet exemple, vous remplacez le délai d’expiration par défaut de 30 secondes par un délai de 10 secondes à des fins de démonstration.

L’appel de la méthode ConfigureRefresh seule n’entraîne pas l’actualisation automatique de la configuration. Vous appelez la méthode TryRefreshAsync à partir de l’interface IConfigurationRefresher pour déclencher une actualisation. Cette conception consiste à éviter les demandes envoyées à App Configuration même lorsque votre application est inactive. Vous voudrez inclure l'appel TryRefreshAsync là où vous considérez que votre application est active. Par exemple, cela peut se produire quand vous traitez un message entrant, une commande ou l’itération d’une tâche complexe. Il peut également s’agir d’un minuteur si votre application est active en permanence. Dans cet exemple, vous appelez TryRefreshAsync chaque fois que vous appuyez sur la touche Entrée. Même si l’appel TryRefreshAsync échoue pour une raison quelconque, votre application continue d’utiliser la configuration mise en cache. Une autre tentative est effectuée lorsque l’intervalle d’actualisation configuré est passé et que l’appel TryRefreshAsync est déclenché à nouveau par l’activité de votre application. L’appel de TryRefreshAsync est une opération sans opération avant l’expiration de l’intervalle d’actualisation configuré, de sorte que son impact sur les performances est minimal, même s’il est appelé fréquemment.

Actualisation de la configuration à l’aide de l’injection de dépendances

Dans le code précédent, vous enregistrez manuellement une instance de IConfigurationRefresher pour invoquer TryRefreshAsync. Si vous utilisez l’injection de dépendances pour résoudre vos services, vous pouvez également référencer les étapes suivantes.

Inscrivez les services App Configuration requis en appelant AddAzureAppConfiguration sur votre IServiceCollection.

Ajoutez le code suivant à Program.cs.

// Existing code in Program.cs
// ... ...

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

Actualisez votre configuration en résolvant un instance de IConfigurationRefresherProvider à partir de votre collection de services et en appelant TryRefreshAsync sur chacun de ses actualiseurs.

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

Générer et exécuter l’application localement

Définissez une variable d’environnement nommée Endpoint sur le point de terminaison de votre magasin App Configuration qui se trouve sous la Vue d’ensemble de votre magasin dans le Portail Azure.

Si vous utilisez l’invite de commandes Windows, exécutez la commande suivante et redémarrez l’invite pour que la modification soit prise en compte :
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Si vous utilisez PowerShell, exécutez la commande suivante :
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Si vous utilisez macOS ou Linux, exécutez la commande suivante :
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Exécutez la commande suivante pour générer l’application console :
```
 dotnet build
```
La génération terminée correctement, lancez la commande suivante pour exécuter l’application localement :
```
 dotnet run
```
Connectez-vous au portail Azure. Sélectionnez toutes les ressources, puis sélectionnez l’instance du magasin App Configuration que vous avez créée dans le guide de démarrage rapide.
Sélectionnez l’Explorateur de configuration et mettez à jour les valeurs des clés suivantes :

Clé Valeur

TestApp :Paramètres :Message Données d’Azure App Configuration - Mise à jour
Appuyez sur La touche Entrée pour déclencher une actualisation et imprimer la valeur mise à jour dans l’invite de commandes ou la fenêtre PowerShell.

Remarque

Étant donné que l’intervalle d’actualisation a été défini sur 10 secondes à l’aide de la SetRefreshInterval méthode lors de la spécification de la configuration de l’opération d’actualisation, la valeur du paramètre de configuration est mise à jour uniquement si au moins 10 secondes se sont écoulées depuis la dernière actualisation pour ce paramètre.

Clé	Valeur
TestApp :Paramètres :Message	Données d’Azure App Configuration - Mise à jour

Journalisation et surveillance

Les journaux sont générés lors de l’actualisation de la configuration et contiennent des informations détaillées sur les valeurs clés récupérées à partir de votre magasin App Configuration et des changements de configuration apportés à votre application. Si vous disposez d’une application ASP.NET Core, consultez ces instructions pour la journalisation et la surveillance dans ASP.NET Core. Sinon, vous pouvez activer la journalisation à l’aide des instructions de journalisation avec le Kit de développement logiciel (SDK) Azure.

Les journaux sont générés à différents niveaux d’un événement. Le niveau par défaut est Informational.

Niveau d’événement	Descriptif
Commentaires	Les journaux incluent la clé et l’étiquette des valeurs clés que votre application supervise pour des modifications apportées à partir de votre magasin App Configuration. Les informations indiquent également si la clé valeur a été modifiée par rapport à ce que votre application a déjà chargé. Activez des journaux à ce niveau pour résoudre les problèmes de votre application si une modification de configuration ne s’est pas produite comme prévu.
Informationnel	Les journaux incluent les clés des paramètres de configuration mis à jour lors d’une actualisation de la configuration. Les valeurs des paramètres de configuration sont omises dans le journal pour éviter des fuites de données sensibles. Vous pouvez surveiller les journaux à ce niveau pour vous assurer que votre application applique les modifications de configuration attendues.
Avertissement	Les journaux incluent les échecs et les exceptions qui se sont produits lors de l’actualisation de la configuration. Les occurrences occasionnelles peuvent être ignorées, car le fournisseur de configuration continue d’utiliser les données mises en cache et tente d’actualiser la configuration la prochaine fois. Vous pouvez surveiller des journaux à ce niveau pour détecter des avertissements répétitifs susceptibles d’indiquer des problèmes potentiels. Par exemple, vous avez pivoté la chaîne de connexion, mais vous avez oublié de mettre à jour votre application.

Vous pouvez activer la journalisation au niveau de l’événement Verbose en spécifiant le EventLevel.Verbose paramètre, comme dans l’exemple suivant. Ces instructions s’appliquent également à tous les autres niveaux d’événements. Cet exemple active également des journaux pour la catégorie Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh uniquement.

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 catégorie de journalisation est Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh. Elle apparaît avant chaque journal. Voici quelques exemples de journaux d’activité au niveau de chaque événement :

[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'

Remarque

La journalisation est disponible si vous utilisez la version 6.0.0 ou une version ultérieure de l’un des packages suivants.

Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Azure.AppConfiguration.AspNetCore
Microsoft.Azure.AppConfiguration.Functions.Worker

Nettoyer les ressources

Si vous ne souhaitez plus utiliser les ressources créées dans cet article, supprimez le groupe de ressources que vous avez créé ici afin d’éviter des frais.

Important

La suppression d’un groupe de ressources est irréversible. Le groupe de ressources et toutes les ressources qu’il contient sont supprimés définitivement. Veillez à ne pas supprimer accidentellement les mauvaises ressources ou le mauvais groupe de ressources. Si vous avez créé les ressources pour cet article dans un groupe de ressources contenant d’autres ressources que vous souhaitez conserver, supprimez chaque ressource individuellement à partir de son volet, au lieu de supprimer l’intégralité du groupe de ressources.

Connectez-vous au portail Azure, puis sélectionnez Groupes de ressources.
Dans la zone Filtrer par nom, entrez le nom de votre groupe de ressources.
Dans la liste de résultats, sélectionnez le nom du groupe de ressources pour afficher une vue d’ensemble.
Sélectionnez Supprimer le groupe de ressources.
Vous êtes invité à confirmer la suppression du groupe de ressources. Entrez le nom de votre groupe de ressources à confirmer, puis sélectionnez Supprimer.

Après quelques instants, le groupe de ressources et toutes ses ressources sont supprimés.

Étapes suivantes

Dans ce tutoriel, vous avez activé votre application .NET pour actualiser dynamiquement les paramètres de configuration à partir d’App Configuration. Pour savoir comment utiliser une identité managée Azure afin de simplifier l’accès à App Configuration, passez au tutoriel suivant.

Intégration des identités managées

Partager via