Tutoriel : Utiliser une configuration dynamique dans un service en arrière-plan .NET

Article
11/21/2024

Les données d’App Configuration peuvent être chargées en tant que paramètres d’application dans une application .NET. Pour plus d’informations, consultez le guide de démarrage rapide. Toutefois, comme il est conçu par .NET, les paramètres de l’application ne peuvent s’actualiser qu’au redémarrage de l’application. Le fournisseur .NET d’App Configuration est une bibliothèque .NET Standard. Il prend en charge la mise en cache et l’actualisation dynamiques de la configuration sans redémarrage de l’application. Ce tutoriel montre comment implémenter des mises à jour de configuration dynamique dans un service en arrière-plan .NET.

Dans ce tutoriel, vous allez apprendre à :

Configurez votre service en arrière-plan .NET pour mettre à jour sa configuration en réponse aux modifications apportées à un magasin App Configuration.
Utilisez la dernière configuration dans votre service en arrière-plan.

Prérequis

Compte Azure avec un abonnement actif. Créez-en un gratuitement.
Un magasin App Configuration. Créez un magasin.
.NET SDK 6.0 ou ultérieur – également disponible dans Azure Cloud Shell.

Ajouter une clé-valeur

Ajoutez la clé-valeur suivante au magasin App Configuration et laissez les valeurs par défaut pour Étiquette et Type de contenu. Pour plus d’informations sur l’ajout de clés-valeurs à un magasin avec le Portail Azure ou la CLI, consultez Créer une clé-valeur.

Clé	Valeur
TestApp:Settings:Message	Data from Azure App Configuration

Créer un service en arrière-plan .NET

Vous utilisez l’interface de ligne de commande .NET (CLI) pour créer un projet d’application .NET. Par rapport à Visual Studio, l’interface CLI .NET offre l’avantage d’être disponible sur les plateformes Windows, macOS et Linux. Vous pouvez également utiliser les outils préinstallés qui sont disponibles dans Azure Cloud Shell.

Créez un nouveau dossier pour votre projet.
Dans le nouveau dossier, exécutez la commande suivante pour créer un projet de service en arrière-plan .NET :
```
dotnet new worker
```

Recharger des données à partir d’Azure App Configuration

Ajoutez des références au package NuGet Microsoft.Extensions.Configuration.AzureAppConfiguration en exécutant la commande suivante :
```
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
```
Exécutez la commande suivante pour restaurer les packages de votre projet :
```
dotnet restore
```

Ouvrez Program.cs et ajoutez les instructions suivantes :

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

Connectez-vous à App Configuration à l’aide de l’ID Microsoft Entra (recommandé) ou d’une chaîne de connexion.

Microsoft Entra ID (recommandé)
Chaîne de connexion

Vous utilisez le DefaultAzureCredential pour vous authentifier auprès de votre magasin App Configuration. Suivez les instructions pour attribuer à votre identifiant le rôle de lecteur de données de configuration de l'application. Veillez à laisser suffisamment de temps pour que l’autorisation se propage avant d’exécuter votre application.

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());
        // Load all keys that start with `TestApp:`.
        .Select("TestApp:*")
        // Configure to reload the key 'TestApp:Settings:Message' if it is modified.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.Register("TestApp:Settings:Message");
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

// The rest of existing code in Program.cs
// ... ...

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
        // Load all keys that start with `TestApp:`.
        .Select("TestApp:*")
        // Configure to reload the key 'TestApp:Settings:Message' if it is modified.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.Register("TestApp:Settings:Message");
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

// The rest of existing code in Program.cs
// ... ...

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. Tous les paramètres inscrits pour l’actualisation ont un délai d’expiration du cache de 30 secondes par défaut avant une nouvelle tentative d’actualisation. Vous pouvez changer ce délai en appelant la méthode AzureAppConfigurationRefreshOptions.SetCacheExpiration.

Ouvrez Worker.cs. Injectez IConfiguration et IConfigurationRefresher au service Worker et journaliser les données de configuration à partir d’App Configuration.
```
public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;
    private readonly IConfiguration _configuration;
    private readonly IConfigurationRefresher _refresher;

    public Worker(ILogger<Worker> logger, IConfiguration configuration, IConfigurationRefresher refresher)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
        _refresher = refresher ?? throw new ArgumentNullException(nameof(refresher));
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Intentionally not await TryRefreshAsync to avoid blocking the execution.
            _refresher.TryRefreshAsync(stoppingToken);

            if (_logger.IsEnabled(LogLevel.Information))
            {
                _logger.LogInformation(_configuration["TestApp:Settings:Message"] ?? "No data.");
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}
```
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 pouvez inclure l’appel de 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 le service en arrière-plan est exécuté. Notez que, même en cas d’échec de l’appel de 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 de 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.

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

Définissez une variable d’environnement.
- Microsoft Entra ID (recommandé)
- Chaîne de connexion
Définissez la variable d’environnement nommée Point de terminaison sur le point de terminaison de votre magasin App Configuration trouvé 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, utilisez 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>'
```
Définissez la variable d’environnement nommée ConnectionString sur la chaîne de connexion en lecture seule de votre magasin App Configuration trouvée sous clés d’accès 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 ConnectionString "<connection-string-of-your-app-configuration-store>"
```
Si vous utilisez PowerShell, utilisez 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.
```
dotnet build
```
La génération terminée correctement, lancez la commande suivante pour exécuter l’application localement.
```
dotnet run
```
Les sorties suivantes devraient s’afficher dans la console.
Dans le portail Azure, accédez à l’Explorateur de configurations de votre magasin App Configuration, puis mettez à jour la valeur de la clé suivante.

Clé Valeur

TestApp:Settings:Message Données issues d’Azure App Configuration - Mise à jour
Patientez quelques instants pour que la fenêtre d’intervalle d’actualisation passe. Les sorties de la console seront être modifiées.

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

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 service en arrière-plan .NET pour actualiser dynamiquement les paramètres de configuration à partir d’App Configuration. Pour savoir comment activer la configuration dynamique dans une application web ASP.NET, passez au tutoriel suivant :

Activer la configuration dynamique dans les applications web ASP.NET

Pour savoir comment utiliser une identité managée Azure de façon à simplifier l’accès à App Configuration, passez au tutoriel suivant :

Intégration des identités managées

Partager via