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

Статья
04/18/2023

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

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

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

Предварительные требования

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

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

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

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

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

Откройте Файл Program.cs и обновите AddAzureAppConfiguration метод, добавленный ранее при выполнении краткого руководства.
- .NET 6.0+
- .NET Core 3.x
```
// 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));
});
```
```
public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureAppConfiguration(config =>
            {
                //Retrieve the Connection String from the secrets manager
                IConfiguration settings = config.Build();
                string connectionString = settings.GetConnectionString("AppConfig");

                // Load configuration from Azure App Configuration
                config.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));
                });
            });

            webBuilder.UseStartup<Startup>();
        });
```
Метод Select используется для загрузки всех значений "ключ-ключ", имя которых начинается с TestApp: и не имеет метки. Метод можно вызвать Select несколько раз, чтобы загрузить конфигурации с разными префиксами или метками. Если вы используете один Конфигурация приложений магазин с несколькими приложениями, этот подход позволяет загружать конфигурацию только для текущего приложения, а не загружать все данные из магазина.

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

Совет

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

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

.NET 6.0+
.NET Core 3.x

Обновите Файл 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
// ... ...

Откройте файл Startup.cs и измените метод ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    // Add Azure App Configuration middleware to the container of services.
    services.AddAzureAppConfiguration();

    // Bind configuration "TestApp:Settings" section to the Settings object
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
}

Вызовите метод UseAzureAppConfiguration. Это позволяет приложению использовать ПО промежуточного слоя Конфигурация приложений для автоматического обновления конфигурации.

.NET 6.0+
.NET Core 3.x

Обновите Файл 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
// ... ...

Обновите Configure метод в Файле Startup.cs.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    // Use Azure App Configuration middleware for dynamic configuration refresh.
    app.UseAzureAppConfiguration();

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

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

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

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

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

Чтобы создать приложение с помощью .NET Core CLI, выполните следующую команду в оболочке командной строки:
```
    dotnet build
```
Когда создание завершится, запустите веб-приложение локально с помощью следующей команды:
```
    dotnet run
```
Откройте окно браузера и перейдите по URL-адресу, указанному в выходных данных dotnet run.
Войдите на портал Azure. Щелкните Все ресурсы и выберите хранилище Конфигурации приложений, которое вы создали по инструкциям из краткого руководства.

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

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

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

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

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

Значение по умолчанию ILoggerFactory добавляется автоматически при services.AddAzureAppConfiguration() вызове . Поставщик Конфигурация приложений использует его 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

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

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

Важно!

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

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

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

Дальнейшие действия

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

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