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

  • Статья

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

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

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

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

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

Добавление ключа Sentinel

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

  1. В портал Azure откройте хранилище Конфигурация приложений и выберите " > Конфигурация Обозреватель создать > ключ-значение".
  2. В поле Ключ введите TestApp:Settings:Sentinel. В поле Значение введите 1. Оставьте поля Метка и Тип содержимого пустыми.
  3. Выберите Применить.

Перезагрузка данных из App Configuration

  1. Откройте Program.cs и обновите метод, добавленный AddAzureAppConfiguration ранее во время краткого руководства.

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

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

    В методе вы регистрируете ConfigureRefresh ключи, которые необходимо отслеживать для изменений в хранилище Конфигурация приложений. Параметр refreshAll метода Register указывает, что все конфигурации, указанные методом, Select будут перезагружены при изменении зарегистрированного ключа.

    Совет

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

  2. Добавьте Конфигурация приложений Azure ПО промежуточного слоя в коллекцию служб приложения.

    Обновите 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 . Оно позволяет приложению использовать по промежуточному слоям Конфигурация приложений для автоматического обновления конфигурации.

    Обновите 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 во время краткого руководства. Когда базовая конфигурация приложения обновляется с Конфигурация приложений, ваш строго типизированный Settings объект, полученный с помощьюIOptionsSnapshot<T>, обновляется автоматически. Обратите внимание, что не следует использовать IOptions<T> динамическое обновление конфигурации, так как оно не считывает данные конфигурации после запуска приложения.

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

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

  • Если запрос на Конфигурация приложений для обнаружения изменений завершается ошибкой, приложение продолжит использовать кэшированную конфигурацию. Новые попытки проверка изменений будут периодически вноситься во время новых входящих запросов к приложению.
  • Обновление конфигурации выполняется асинхронно при обработке входящих запросов приложения. Она не будет блокировать или замедлять входящий запрос, который активировал обновление. Запрос, активировав обновление, может не получить обновленные значения конфигурации, но последующие запросы получат новые значения конфигурации.
  • Чтобы обеспечить активацию ПО промежуточного слоя, вызовите app.UseAzureAppConfiguration() метод как можно раньше в конвейере запроса, чтобы другое ПО промежуточного слоя не пропускалось в приложении.

Создание и запуск приложения локально

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

        dotnet build

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

        dotnet run

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

    Launching quickstart app locally

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

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

    Ключ Значение
    TestApp:Settings:BackgroundColor зеленый
    TestApp:Settings:FontColor lightGray
    TestApp:Settings:FontSize Данные из Azure App Configuration — теперь с обновлениями в реальном времени!
    TestApp:Settings:Sentinel 2

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

    Launching updated quickstart app locally

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

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

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

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

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

    Вы можете включить ведение журнала на Debug уровне журнала, добавив следующий пример в appsettings.json файл. Этот пример также применяется ко всем другим уровням журналов.

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

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

    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'

Использование ILogger является предпочтительным методом в ASP.NET приложениях и имеет приоритет в качестве источника ведения журнала, если ILoggerFactory экземпляр присутствует. Однако, если ILoggerFactory это недоступно, журналы можно также включить и настроить с помощью инструкций для приложений .NET Core. Дополнительные сведения см. в разделе ведения журнала в .NET Core и ASP.NET Core.

Примечание.

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

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

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

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

Внимание

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

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

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

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

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

Доступ к Конфигурации приложений с использованием управляемого удостоверения