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

  • Статья

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

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

В этом руководстве описано следующее:

  • Настройте приложение .NET для обновления конфигурации в ответ на изменения в хранилище Конфигурация приложений.
  • использование последней конфигурации в приложении.

Необходимые компоненты

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

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

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

Откройте файл Program.cs и замените код в нем следующим:

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

}

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

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

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

В предыдущем коде вы вручную сохраняете экземпляр 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. Задайте переменную среды с именем ConnectionString и укажите для нее ключ доступа к хранилищу службы "Конфигурация приложений". Если вы используете командную строку Windows, выполните следующую команду и перезапустите командную строку, чтобы изменения вступили в силу:

     setx ConnectionString "connection-string-of-your-app-configuration-store"

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

     $Env:ConnectionString = "connection-string-of-your-app-configuration-store"

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

     export ConnectionString='connection-string-of-your-app-configuration-store'

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

     dotnet build

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

     dotnet run

    Quickstart app launch local

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

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

    Ключ Значение
    TestApp:Settings:FontSize Данные из конфигурации приложений Azure. Обновлено

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

    Quickstart app refresh local

    Примечание.

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

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

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

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

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

    Вы можете включить ведение журнала на 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'

Примечание.

Ведение журнала доступно, если вы используете версию 6.0.0 или более позднюю версию любого из следующих пакетов.

  • Microsoft.Extensions.Configuration.AzureAppConfiguration
  • Microsoft.Azure.AppConfiguration.AspNetCore
  • Microsoft.Azure.AppConfiguration.Functions.Worker

Очистка ресурсов

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

Внимание

Удаление группы ресурсов — процесс необратимый. Группа ресурсов и все содержащиеся в ней ресурсы удаляются без возможности восстановления. Будьте внимательны, чтобы случайно не удалить не те ресурсы или группу ресурсов. Если ресурсы для работы с этой статьей созданы в группе ресурсов, которая содержит другие нужные ресурсы, удалите каждый ресурс отдельно в соответствующей области ресурса, чтобы не удалять группу ресурсов.

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

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

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

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

Руководство по интеграции с управляемыми удостоверениями Azure