Tutoriel : Utiliser la configuration dynamique dans une application ASP.NET Core

  • Article

Ce tutoriel montre comment activer les mises à jour de configuration dynamique dans une application ASP.NET Core. Il s’appuie sur l’application web introduite dans les guides de démarrage rapide. Votre application tire parti de la bibliothèque de fournisseurs App Configuration pour ses fonctionnalités intégrées d’actualisation et de mise en cache de configuration. Avant de continuer, terminez d’abord l’étape Créer une application ASP.NET Core avec App Configuration.

Dans ce tutoriel, vous allez apprendre à :

  • Configurez votre application pour mettre à jour sa configuration en réponse aux changements survenant dans un magasin App Configuration.
  • Injectez la configuration la plus récente dans votre application.

Prérequis

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

Ajouter une clé Sentinel

Une clé Sentinel est une clé que vous mettez à jour après avoir modifié toutes les autres clés. Votre application supervise la clé Sentinel. Lorsqu’un changement est détecté, votre application actualise toutes les valeurs de configuration. Cette approche permet de garantir la cohérence de la configuration dans votre application et de réduire le nombre total de demandes adressées à votre magasin App Configuration, par rapport au monitoring des changements de toutes les clés.

  1. Dans le portail Azure, ouvrez votre magasin App Configuration et sélectionnez Explorateur de configurations > Créer > Clé-valeur.
  2. Pour Clé, entrez TestApp:Settings:Sentinel. Pour Valeur, entrez 1. Laissez Étiquette et Type de contenu vides.
  3. Sélectionnez Appliquer.

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

  1. Ouvrez Program.cs et mettez à jour la méthode AddAzureAppConfiguration que vous avez ajoutée précédemment lors du démarrage rapide.

    // Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString)
           // Load all keys that start with `TestApp:` and have no label
           .Select("TestApp:*", LabelFilter.Null)
           // Configure to reload configuration if the registered sentinel key is modified
           .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});

    La méthode Select est utilisée pour charger toutes les valeurs de clé dont le nom de clé commence par TestApp: et qui n’ont aucune étiquette. Vous pouvez appeler la méthode Select plusieurs fois pour charger des configurations avec différents préfixes ou étiquettes. Si vous partagez un magasin App Configuration avec plusieurs applications, cette approche permet de charger la configuration uniquement pertinente pour votre application actuelle au lieu de charger tous les éléments de votre magasin.

    Dans la méthode ConfigureRefresh, vous inscrivez les clés dont vous souhaitez superviser les changements dans votre magasin App Configuration. Le paramètre refreshAll pour la méthode Register indique que toutes les configurations que vous avez spécifiées par la méthode Select seront rechargées si la clé inscrite change.

    Conseil

    Vous pouvez ajouter un appel à la méthode refreshOptions.SetCacheExpiration pour spécifier le temps minimal entre les actualisations de configuration. Dans cet exemple, vous utilisez la valeur par défaut de 30 secondes. Choisissez une valeur plus élevée si vous devez réduire le nombre de demandes adressées à votre magasin App Configuration.

  2. Ajoutez un intergiciel (middleware) Azure App Configuration à la collection de services de votre application.

    Mettez à jour Program.cs avec le code suivant.

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

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

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

  3. Appelez la méthode UseAzureAppConfiguration . Elle permet à votre application d’utiliser l’intergiciel App Configuration pour mettre automatiquement à jour la configuration.

    Mettez à jour Program.cs avec le code suivant.

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

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

Vous avez configuré votre application pour utiliser le modèle d’options dans ASP.NET Core pendant le démarrage rapide. Lorsque la configuration sous-jacente de votre application est mise à jour à partir d’App Configuration, votre objet Settings fortement typé obtenu via IOptionsSnapshot<T> est mis à jour automatiquement. Notez que vous ne devez pas utiliser le IOptions<T> si la mise à jour de la configuration dynamique est souhaitée, car elle ne lit pas les données de configuration après le démarrage de l’application.

Actualisation de la configuration pilotée par les demandes

L’actualisation de la configuration est déclenchée par les demandes entrantes adressées à votre application web. Aucune actualisation ne se produit si votre application est inactive. Lorsque votre application est active, l’intergiciel App Configuration supervise la clé Sentinel ou toute autre clé que vous avez inscrite pour l’actualisation dans l’appel ConfigureRefresh. L’intergiciel est déclenché lors de chaque demande entrante adressée à votre application. Mais il n'envoie des requêtes de vérification de la valeur dans App Configuration que lorsque le délai d'expiration du cache que vous avez défini est écoulé.

  • En cas d’échec d’une demande de détection de changements adressée à App Configuration, votre application continue d’utiliser la configuration mise en cache. De nouvelles tentatives de recherche des changements sont effectuées régulièrement tant qu’il existe de nouvelles demandes entrantes adressées à votre application.
  • L’actualisation de la configuration se produit de manière asynchrone par rapport au traitement des demandes entrantes de votre application. Cela ne bloque pas ou ne ralentit pas la requête entrante qui a déclenché l'actualisation. La demande qui a déclenché l’actualisation peut ne pas obtenir les valeurs de configuration mises à jour, mais les demandes ultérieures obtiendront de nouvelles valeurs de configuration.
  • Pour vous assurer que l’intergiciel est déclenché, appelez la méthode app.UseAzureAppConfiguration() le plus tôt possible dans votre pipeline de demandes afin qu’un autre intergiciel ne l’ignore pas dans votre application.

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

  1. Pour générer l’application à l’aide de l’interface CLI .NET, exécutez la commande suivante dans l’interpréteur de commandes :

        dotnet build

  2. Une fois la génération correctement terminée, exécutez la commande suivante pour exécuter l’application web localement :

        dotnet run

  3. Ouvrez une fenêtre de navigateur, puis accédez à l’URL figurant dans la sortie de dotnet run.

    Launching quickstart app locally

  4. Connectez-vous au portail Azure. Sélectionnez Toutes les ressources, puis sélectionnez le magasin App Configuration que vous avez créé dans le guide de démarrage rapide.

  5. Sélectionnez Explorateur de configurations et mettez à jour les valeurs des clés suivantes. N'oubliez pas de mettre à jour la clé Sentinelle.

    Clé Valeur
    TestApp:Settings:BackgroundColor green
    TestApp:Settings:FontColor lightGray
    TestApp:Settings:Message Données provenant d’Azure App Configuration, avec maintenant des mises à jour automatiques !
    TestApp:Settings:Sentinel 2

  6. Actualisez le navigateur à plusieurs reprises. Lorsque le cache expire au bout de 30 secondes, la page s’affiche avec le contenu mis à jour.

    Launching updated quickstart app locally

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 les valeurs clés récupérées à partir de votre magasin App Configuration et des changements de configuration apportés à votre application.

  • Une valeur ILoggerFactory par défaut est automatiquement ajoutée quand services.AddAzureAppConfiguration() est appelé. Le fournisseur App Configuration utilise cette valeur ILoggerFactory pour créer un instance de ILogger, qui génère ces journaux. ASP.NET Core utilise ILogger pour la journalisation par défaut. Vous n’avez donc pas besoin d’apporter d’autres changements au code afin d’activer la journalisation pour le fournisseur App Configuration.

  • Les journaux sont générés à différents niveaux de journal. Le niveau par défaut est Information.

    Niveau du journal Description
    Débogage Les journaux incluent la clé et l’étiquette des valeurs clés dont votre application supervise les changements apportés par 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 les journaux à ce niveau pour résoudre les problèmes de votre application si un changement de configuration ne s’est pas produit comme prévu.
    Information 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 permuter la chaîne de connexion, mais vous avez oublié de mettre à jour votre application.

    Vous pouvez activer la journalisation au niveau du journal Debug en ajoutant l’exemple suivant à votre fichier appsettings.json. Cet exemple s’applique également à tous les autres niveaux de journal.

    "Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

  • La catégorie de journalisation est Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh. Elle apparaît avant chaque journal. Voici quelques exemples de journaux à chaque niveau de journal :

    dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    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'

L’utilisation de ILogger est la méthode privilégiée dans les applications ASP.NET et est prioritaire en tant que source de journalisation si une instance de ILoggerFactory est présente. Toutefois, si ILoggerFactory n’est pas disponible, les journaux peuvent également être activés et configurés par le biais des instructions pour les applications .NET Core. Pour plus d’informations, consultez Journalisation dans .NET Core et ASP.NET Core.

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.

  1. Connectez-vous au portail Azure, puis sélectionnez Groupes de ressources.
  2. Dans la zone Filtrer par nom, entrez le nom de votre groupe de ressources.
  3. Dans la liste de résultats, sélectionnez le nom du groupe de ressources pour afficher une vue d’ensemble.
  4. Sélectionnez Supprimer le groupe de ressources.
  5. 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 web ASP.NET Core d’actualiser dynamiquement les paramètres de configuration à partir d’App Configuration. Pour savoir comment utiliser une identité managée Azure de façon à simplifier l’accès à App Configuration, passez au tutoriel suivant.

Accès App Configuration à l’aide d’une identité managée