Tutorial: Use dynamic configuration in an ASP.NET Core app

This tutorial shows how you can enable dynamic configuration updates in an ASP.NET Core app. Он базируется на веб-приложении, представленном в руководстве по быстрому старту. Your app will leverage the App Configuration provider library for its built-in configuration caching and refreshing capabilities. Before you continue, finish Create an ASP.NET Core app with App Configuration first.

In this tutorial, you learn how to:

Prerequisites

Завершите быструю настройку: Создайте приложение ASP.NET Core с App Configuration.

Перезагрузить данные из конфигурации приложения

1. Откройте Program.cs и обновите метод AddAzureAppConfiguration, который вы добавили во время быстрого старта. Вы можете подключиться к конфигурации приложения, используя либо Microsoft Entra ID (рекомендуется), либо строку подключения. Следующий фрагмент кода демонстрирует использование Microsoft Entra ID.

   Вы используете DefaultAzureCredential, чтобы пройти аутентификацию в вашем хранилище конфигурации приложения. В процессе выполнения быстрого старта, указанного в списке предварительных условий, вы уже назначили своим учетным данным роль App Configuration Data Reader.

   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(new Uri(endpoint), new DefaultAzureCredential())
              // Load all keys that start with `TestApp:` and have no label.
              .Select("TestApp:*", LabelFilter.Null)
              // Reload configuration if any selected key-values have changed.
              .ConfigureRefresh(refreshOptions =>
                  refreshOptions.RegisterAll());
   });
   

   Метод Select используется для загрузки всех пар ключ-значений, ключ которых начинается с TestApp: и не имеет метки. Вы можете вызвать метод Select несколько раз, чтобы загрузить конфигурации с разными префиксами или метками. Если вы используете один магазин конфигурации приложений для нескольких приложений, этот подход поможет загружать только ту конфигурацию, которая актуальна для вашего текущего приложения, вместо загрузки всего из вашего магазина.

   Внутри метода ConfigureRefresh вы вызываете метод RegisterAll, чтобы указать поставщику App Configuration перезагрузить всю конфигурацию при обнаружении изменений в любом из выбранных ключевых значений (начиная с TestApp: и без ярлыка). Дополнительные сведения об изменениях конфигурации мониторинга см. в рекомендациях по обновлению конфигурации.

   Tip

   Вы можете добавить вызов метода refreshOptions.SetRefreshInterval, чтобы указать минимальное время между обновлениями конфигурации. В этом примере вы используете значение по умолчанию в 30 секунд. Увеличьте значение, если нужно уменьшить количество запросов к вашему хранилищу конфигурации приложений.

2. Добавьте промежуточное программное обеспечение Azure App Configuration в коллекцию служб вашего приложения.

   Обновите Program.cs с помощью следующего кода.

   // 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. Вызовите метод UseAzureAppConfiguration. It enables your app to use the App Configuration middleware to update the configuration for you automatically.

   Обновите Program.cs следующим кодом.

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

Вы настроили приложение для использования шаблона параметров в ASP.NET Core во время быстрого старта. Когда базовая конфигурация вашего приложения обновляется из App Configuration, ваш строго типизированный объект Settings, полученный через IOptionsSnapshot<T>, автоматически обновляется. Обратите внимание, что не следует использовать IOptions<T>, если требуется динамическое обновление конфигурации, поскольку оно не считывает данные конфигурации после запуска приложения.

Обновление конфигурации на основе запросов

The configuration refresh is triggered by the incoming requests to your web app. Обновление не произойдет, если ваше приложение бездействует. Когда приложение активно, ПО промежуточного слоя конфигурации приложений отслеживает все ключи, зарегистрированные для обновления в вызове ConfigureRefresh . The middleware is triggered upon every incoming request to your app. Однако по промежуточному слоям будут отправляться только запросы для проверки значения в конфигурации приложений при передаче заданного интервала обновления.

• If a request to App Configuration for change detection fails, your app will continue to use the cached configuration. New attempts to check for changes will be made periodically while there are new incoming requests to your app.
• Обновление конфигурации происходит асинхронно по отношению к обработке входящих запросов вашего приложения. Он не будет блокировать или замедлять входящий запрос, который инициировал обновление. Запрос, который инициировал обновление, может не получить обновленные значения конфигурации, но последующие запросы получат новые значения конфигурации.
• Чтобы гарантировать выполнение промежуточного ПО, вызовите метод app.UseAzureAppConfiguration() как можно раньше в вашем конвейере запросов, чтобы другое промежуточное ПО не пропустило его в вашем приложении.

Постройте и запустите приложение локально

1. Чтобы создать приложение, используя .NET CLI, выполните следующую команду в командной оболочке:

       dotnet build
   

2. После успешного завершения сборки выполните следующую команду, чтобы запустить веб-приложение локально:

       dotnet run
   

3. Откройте окно браузера и перейдите по URL-адресу, указанному в выходных данных dotnet run.

   

4. Sign in to the Azure portal. Выберите Все ресурсы и выберите хранилище App Configuration, которое вы создали в быстром старте.

5. Выберите Конфигурации проводник и обновите значения следующих ключей.

   Ключ	Значение
   TestApp:Settings:BackgroundColor	зелёный
   TestApp:Настройки:ЦветШрифта	светло-серый
   TestApp:Настройки:Сообщение	Данные из Azure App Configuration - теперь с обновлениями в реальном времени!

6. Обновите браузер несколько раз. Когда интервал обновления истекает через 30 секунд, страница отображается с обновленным содержимым.

   

Ведение журналов и мониторинг

Логи выводятся при обновлении конфигурации и содержат подробную информацию о ключевых значениях, извлечённых из вашего хранилища конфигураций приложений, и изменениях конфигурации, произведённых в вашем приложении.

• По умолчанию ILoggerFactory добавляется автоматически, когда вызывается services.AddAzureAppConfiguration(). Провайдер App Configuration использует этот ILoggerFactory, чтобы создать экземпляр ILogger, который выводит эти журналы. ASP.NET Core использует ILogger для регистрации по умолчанию, поэтому вам не нужно вносить дополнительные изменения в код, чтобы включить ведение журнала для поставщика конфигурации приложения.

• Журналы выводятся на разных уровнях логирования. Уровень по умолчанию - Information.

  Уровень ведения журнала	Описание
  Отладка	Логи включают ключ и метку ключ-значений, которые ваше приложение отслеживает на предмет изменений в вашем хранилище конфигураций приложений. Информация также включает в себя, изменилось ли значение ключа по сравнению с тем, что ваше приложение уже загрузило. Включите ведение журналов на этом уровне, чтобы устранить проблемы в приложении, если изменение конфигурации не произошло так, как ожидалось.
  Информация	Logs include the keys of configuration settings updated during a configuration refresh. Значения настроек конфигурации исключены из журнала, чтобы избежать утечки конфиденциальных данных. Вы можете отслеживать журналы на этом уровне, чтобы убедиться, что ваше приложение применяет ожидаемые изменения конфигурации.
  Предупреждение	Журналы содержат сбои и исключения, которые возникли в ходе обновления конфигурации. Occasional occurrences can be ignored because the configuration provider will continue using the cached data and attempt to refresh the configuration next time. You can monitor logs at this level for repetitive warnings that may indicate potential issues. Например, вы изменили строку подключения, но забыли обновить своё приложение.

  Вы можете включить ведение журнала на уровне Debug логирования, добавив следующий пример в файл appsettings.json. This example applies to all other log levels as well.

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

• Категория журналирования — это Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, которая появляется перед каждым журналом. Here are some example logs at each log level:

  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'
  

Using ILogger is the preferred method in ASP.NET applications and is prioritized as the logging source if an instance of ILoggerFactory is present. However, if ILoggerFactory is not available, logs can alternatively be enabled and configured through the instructions for .NET Core apps. Для получения дополнительной информации см. логирование в .NET Core и ASP.NET Core.

Очистить ресурсы

If you don't want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

1. Войдите в Azure portal и выберите Resource groups.
2. В поле Фильтр по имени введите название вашей группы ресурсов.
3. В списке результатов выберите имя группы ресурсов, чтобы увидеть обзор.
4. Select Delete resource group.
5. Вам предлагается подтвердить удаление группы ресурсов. Введите имя вашей группы ресурсов для подтверждения и выберите Удалить.

Через несколько мгновений группа ресурсов и все ее ресурсы будут удалены.

Следующие шаги

В этом руководстве вы настроили ваше веб-приложение ASP.NET Core для динамического обновления настроек конфигурации из App Configuration. Чтобы узнать, как использовать управляемую идентификацию Azure для упрощения доступа к конфигурации приложений, перейдите к следующему учебному руководству.