Поделиться через

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

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

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

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

Предпосылки

Завершите быструю настройку: Создайте приложение 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: и без ярлыка). Дополнительные сведения об изменениях конфигурации мониторинга см. в рекомендациях по обновлению конфигурации.

    Подсказка

    Вы можете добавить вызов метода 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. Это позволяет вашему приложению использовать ПО промежуточного слоя App Configuration для автоматического обновления конфигурации.

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

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

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

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

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

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

        dotnet build

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

        dotnet run

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

    Запуск приложения Quickstart локально

  4. Войдите на портал Azure. Выберите Все ресурсы и выберите хранилище App Configuration, которое вы создали в быстром старте.

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

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

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

    Запуск обновленного приложения quickstart локально

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

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

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

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

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

    Вы можете включить ведение журнала на уровне 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 portal и выберите Resource groups.
  2. В поле Фильтр по имени введите название вашей группы ресурсов.
  3. В списке результатов выберите имя группы ресурсов, чтобы увидеть обзор.
  4. Выберите команду Удалить группу ресурсов.
  5. Вам предлагается подтвердить удаление группы ресурсов. Введите имя вашей группы ресурсов для подтверждения и выберите Удалить.

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

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

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

Получите доступ к настройкам приложения, используя управляемую идентичность