Tutoriel : utiliser la configuration dynamique dans une application .NET

Article
02/20/2024

La bibliothèque du fournisseur .NET d’App Configuration prend en charge la mise à jour de la configuration à la demande sans entraîner le redémarrage de l’application. Ce tutoriel montre comment vous pouvez implémenter des mises à jour de la configuration dynamique dans votre code. Il s’appuie sur l’application présentée dans le guide de démarrage rapide. Vous devez finir l’action Créer 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 changements survenant dans un magasin App Configuration.
Utiliser la configuration la plus récente dans votre application.

Prérequis

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Finissez 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.

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

}

Dans la méthode ConfigureRefresh, une clé de votre magasin App Configuration est inscrite pour la supervision des changements. La méthode Register a un paramètre booléen facultatif refreshAll qui permet d’indiquer si toutes les valeurs de configuration doivent être actualisées en cas de changement de la clé inscrite. Dans cet exemple, seule la clé TestApp:Settings:Message est actualisée. La méthode SetCacheExpiration 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 devez inclure l’appel TryRefreshAsync quand 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 en cas d’échec de l’appel TryRefreshAsync pour une raison quelconque, votre application continue à utiliser la configuration mise en cache. Une autre tentative a lieu quand le délai d’expiration configuré pour le cache est écoulé et que l’appel TryRefreshAsync est à nouveau déclenché par l’activité de votre application. L’appel de TryRefreshAsync est une non-opération avant l’expiration du délai configuré pour le cache. Son impact sur les performances est donc minimal, même si l’appel est effectué 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 appeler 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 dans 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 ConnectionString et affectez-lui la valeur de la clé d’accès à votre magasin App Configuration. 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 ConnectionString "<connection-string-of-your-app-configuration-store>"
```
Si vous utilisez Windows PowerShell, exécutez la commande suivante :
```
 $Env:ConnectionString = "<connection-string-of-your-app-configuration-store>"
```
Si vous utilisez macOS ou Linux, exécutez la commande suivante :
```
 export ConnectionString='<connection-string-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 Explorateur de configuration, puis mettez à jour les valeurs des clés suivantes :

Clé Valeur

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

Remarque

Étant donné que le délai d’expiration du cache a été défini sur 10 secondes à l’aide de la méthode SetCacheExpiration lors de la spécification de la configuration de l’opération d’actualisation, la valeur du paramètre de configuration ne sera actualisée que si 10 secondes se sont écoulées depuis la dernière actualisation de ce paramètre.

Clé	Valeur
TestApp:Settings:Message	Données issues d’Azure App Configuration - Mise à jour

Enregistrement et surveillance

Les journaux sont générés lors de l’actualisation de la configuration et contiennent des informations détaillées sur des valeurs clés récupérées à partir de votre magasin App Configuration et des modifications de configuration apportées à votre application. Si vous disposez d’une application ASP.NET Core, consultez ces instructions pour la Journalisation et surveillance dans ASP.NET Core. Sinon, vous pouvez activer la journalisation en suivant les 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	Description
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 superviser des journaux à ce niveau pour garantir que votre application récupère 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 paramètre EventLevel.Verbose, comme dans l’exemple suivant. Ces instructions s’appliquent également à tous les autres niveaux d’événement. 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 s’affiche avant chaque journal. Voici quelques exemples de journaux à chaque niveau de é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'

Notes

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 permis à votre application .NET d’actualiser dynamiquement les paramètres de configuration depuis 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