Руководство. Использование динамической конфигурации в приложении .NET

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

Вы можете выполнять шаги в этом учебнике с помощью любого редактора кода. Visual Studio Code — отличный вариант, доступный на платформах Windows, macOS и Linux.

В этом руководстве вы узнаете, как:

Предпосылки

Если у вас нет подписки Azure, создайте бесплатную учетную запись Azure перед началом работы.

Завершите работу с кратким руководством по созданию приложения .NET с помощью конфигурации приложений.

Обновление конфигурации, инициированное действиями

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

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

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

}

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

Метод SetRefreshInterval указывает минимальное время, которое должно пройти, прежде чем будет выполнен новый запрос в службу "Конфигурация приложений" для проверки на наличие каких-либо изменений конфигурации. В этом примере с целью демонстрации вы переопределяете срок действия по умолчанию (30 секунд), устанавливая 10-секундный интервал.

Вызов метода ConfigureRefresh сам по себе не приведет к автоматическому обновлению конфигурации. Для активации обновления необходимо вызвать метод TryRefreshAsync из интерфейса IConfigurationRefresher. Это позволяет избежать запросов, отправленных в Конфигурация приложений даже если приложение неактивно. Вы должны включить вызов TryRefreshAsync там, где вы считаете ваше приложение активным. Например, при обработке входящего сообщения, заказа или итерации сложной задачи. Это также может находиться в режиме таймера, если ваше приложение активно постоянно. В этом примере вы вызываете TryRefreshAsync каждый раз, когда нажимаете клавишу ВВОД. Даже если вызов TryRefreshAsync завершается сбоем по какой-либо причине, приложение продолжает использовать кэшированную конфигурацию. Новая попытка совершается после истечения настроенного интервала обновления, и вызов TryRefreshAsync снова активируется в результате активности вашего приложения. Вызов TryRefreshAsync — это no-op до истечения заданного интервала обновления, поэтому его влияние на производительность минимально, даже если оно часто вызывается.

Обновление конфигурации с помощью внедрения зависимостей

В предыдущем коде вы вручную сохраняете экземпляр IConfigurationRefresher, чтобы вызвать TryRefreshAsync. Кроме того, если вы используете внедрение зависимостей для разрешения ваших служб, вы можете ссылаться на следующие шаги.

1. Зарегистрируйте необходимые службы конфигурации приложений, вызвав AddAzureAppConfiguration на вашем компьютере IServiceCollection.

   Добавьте следующий код в Program.cs.

   // Existing code in Program.cs
   // ... ...
   
   // Add Azure App Configuration services to IServiceCollection
   builder.Services.AddAzureAppConfiguration();
   

2. Обновите конфигурацию, получив экземпляр IConfigurationRefresherProvider из вашей коллекции служб и вызвав метод TryRefreshAsync на каждом из его обновляющих объектов.

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

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

1. Задайте переменную среды с именем Endpoint в конечной точке хранилища конфигурации приложений, найденную в разделе "Обзор магазина" на портале Azure.

   Если вы используете командную строку Windows, выполните следующую команду и перезапустите командную строку, чтобы изменения вступили в силу:

   setx Endpoint "<endpoint-of-your-app-configuration-store>"
   

   Если вы используете PowerShell, выполните следующую команду:

   $Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
   

   Если вы используете macOS или Linux, выполните следующую команду:

   export Endpoint='<endpoint-of-your-app-configuration-store>'
   

2. Чтобы создать консольное приложение, выполните следующую команду:

    dotnet build
   

3. Когда создание завершится, запустите приложение локально с помощью следующей команды:

    dotnet run
   

   

4. Войдите на портал Azure. Выберите все ресурсы и выберите экземпляр Магазина конфигурации приложений, созданный в кратком руководстве.

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

   Ключ	Ценность
   TestApp:Настройки:Сообщение	Данные из конфигурации приложений Azure — обновлены

6. Нажмите клавишу ВВОД, чтобы активировать обновление и распечатать обновленное значение в командной строке или окне PowerShell.

   

   Замечание

   Так как интервал обновления был установлен на 10 секунд с помощью SetRefreshInterval метода при указании конфигурации для операции обновления, значение параметра конфигурации будет обновлено только в том случае, если с момента последнего обновления этого параметра прошло не менее 10 секунд.

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

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

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

  Уровень событий	Описание
  Многословный	Логи включают ключ и метку ключ-значений, которые ваше приложение отслеживает на предмет изменений в вашем хранилище конфигураций приложений. Информация также включает в себя, изменилось ли значение ключа по сравнению с тем, что ваше приложение уже загрузило. Включите ведение журналов на этом уровне, чтобы устранить проблемы в приложении, если изменение конфигурации не произошло так, как ожидалось.
  Информационный	Журналы включают ключи параметров конфигурации, обновленные во время обновления конфигурации. Значения настроек конфигурации исключены из журнала, чтобы избежать утечки конфиденциальных данных. Вы можете отслеживать журналы на этом уровне, чтобы убедиться, что ваше приложение применяет ожидаемые изменения конфигурации.
  Предупреждение	Журналы содержат сбои и исключения, которые возникли в ходе обновления конфигурации. Случайные происшествия могут игнорироваться, так как поставщик конфигурации будет продолжать использовать кэшированные данные и в следующий раз будет пытаться обновить конфигурацию. Вы можете отслеживать журналы на этом уровне детализации с целью обнаружения повторяющихся предупреждений, которые могут указывать на потенциальные проблемы. Например, вы изменили строку подключения, но забыли обновить своё приложение.

  Вы можете включить ведение журнала на Verbose уровне событий, указав EventLevel.Verbose параметр, как показано в следующем примере. Эти инструкции также применяются ко всем остальным уровням событий. Этот пример также включает только логи для категории Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh.

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

• Категория журналирования — это Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, которая появляется перед каждым журналом. Ниже приведены некоторые примеры журналов на каждом уровне событий:

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

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

Если вы не планируете в дальнейшем использовать ресурсы, созданные при работе с этой статьей, удалите созданную группу ресурсов, чтобы избежать расходов.

1. Войдите на портал Azure и выберите группы ресурсов.
2. В поле "Фильтр по имени " введите имя группы ресурсов.
3. В списке результатов выберите имя группы ресурсов, чтобы просмотреть общие сведения.
4. Выберите "Удалить группу ресурсов".
5. Вам предлагается подтвердить удаление группы ресурсов. Введите имя группы ресурсов, чтобы подтвердить, и нажмите кнопку "Удалить".

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

Дальнейшие шаги

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