Provedor de configuração do .NET

A Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizarem as configurações de seus aplicativos de maneira simples e segura. A biblioteca do provedor de configuração do .NET permite carregar a configuração de um repositório de Configuração de Aplicativos do Azure de maneira gerenciada. Essa biblioteca de clientes adiciona funcionalidades adicionais sobre o SDK do Azure para .NET.

Configuração de carregamento

O provedor de configuração do .NET da Configuração de Aplicativos do Azure integra-se ao sistema de configuração do .NET, facilitando o carregamento de valores de configuração do repositório da Configuração de Aplicativos do Azure. Você pode adicionar o provedor durante a inicialização do aplicativo e usá-lo junto com outras fontes de configuração.

Para usar o provedor de configuração do .NET, instale o pacote:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Você chama o método de extensão AddAzureAppConfiguration em IConfigurationBuilder para adicionar a Configuração de Aplicativos do Azure como sendo um provedor de configuração do seu aplicativo.

A biblioteca do provedor de configuração implementa um padrão de opções combinado e um padrão de construtor para fornecer uma maneira limpa e declarativa de configurar o AzureAppConfigurationOptions. O AddAzureAppConfiguration método aceita um Action<AzureAppConfigurationOptions> parâmetro delegado que permite configurar o provedor por meio de uma API fluente.

Para se conectar ao repositório de Configuração de Aplicativos do Azure, chame o Connect método na AzureAppConfigurationOptions instância, que retorna o mesmo objeto de opções para habilitar o encadeamento de métodos.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("AppConfigurationEndpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

Consumir configuração

Depois de adicionar o provedor de Configuração de Aplicativos do Azure, você pode acessar seus valores de configuração de várias maneiras:

1. Acesso direto

A abordagem mais simples é recuperar valores diretamente da IConfiguration instância:

// Directly get the configuration
string message = configuration["TestApp:Settings:Message"];

IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");

2. Injeção de dependência com IConfiguration

Em serviços ou controladores, você pode injetar e usar a IConfiguration interface diretamente:

public class WeatherService
{
    private readonly IConfiguration _configuration;

    public WeatherService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public Task<WeatherForecast> GetForecastAsync()
    {
        // Access configuration values directly from the injected instance
        string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];

        ...

        return Task.FromResult(new WeatherForecast());
    }
}

3. Padrão de opções para configuração fortemente tipificada

// Define a strongly-typed settings class
public class Settings
{
    public string BackgroundColor { get; set; }
    public long FontSize { get; set; }
    public string FontColor { get; set; }
    public string Message { get; set; }
}

builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

Para obter mais informações sobre o padrão de opções no .NET, acesse a documentação.

Tratamento de tipo de conteúdo JSON

Você pode criar valores de chave JSON na Configuração de Aplicativos. Quando um valor-chave com o tipo de conteúdo "application/json" é lido, o provedor de configuração o nivelará em configurações individuais dentro de IConfiguration. Para obter mais informações, acesse Usar o tipo de conteúdo para armazenar valores de chave JSON na Configuração de Aplicativos.

Carregar valores de chave específicos usando seletores

Por padrão, o provedor de configuração carrega todos os valores-chave sem rótulo da Configuração de Aplicativos. Você pode carregar seletivamente os valores-chave do repositório da Configuração de Aplicativos chamando o método Select em AzureAppConfigurationOptions.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and no label
        .Select("App:Settings:*")
        // Load configuration values with prefix "TestApp:" and "Prod" label
        .Select("App:Settings:*", "Prod")
        // Load configuration values with prefix "TestApp:" and "Prod" label that have the tag "Group" with value "Contoso"
        .Select("App:Settings:*", "Prod", new[] { "Group=Contoso" })
});

O Select método usa três parâmetros. O primeiro parâmetro é um filtro de chave que especifica quais chaves carregar, o segundo parâmetro é um filtro de rótulo que especifica quais valores de chave com rótulos específicos carregar e o terceiro parâmetro especifica uma coleção de filtros de marca que todos devem estar presentes em um valor-chave a ser carregado.

Filtro de chave

O parâmetro de filtro de chave determina quais chaves de configuração incluir:

• Correspondência exata: o uso de uma cadeia de caracteres específica corresponde apenas às chaves que correspondem exatamente ao filtro.
• Correspondência de prefixo: adicionar um asterisco (*) no final cria um filtro de prefixo (por exemplo, App:Settings:* carrega todas as chaves começando com "App:Settings:").
• Seleção de várias chaves: usar uma vírgula (,) permite a seleção de várias chaves explícitas (por exemplo, Key1,Key2,Key3).
• Caracteres reservados: os caracteres asterisco (*), vírgula (,) e barra invertida (\) são reservados e devem ser escapados com uma barra invertida quando usados em nomes de chave (por exemplo, o filtro a\\b\,\*c* de chave retorna todos os valores-chave cuja chave começa com a\b,*c.).

Filtro de rótulo

O parâmetro de filtro de rótulo seleciona valores-chave com um rótulo específico. Se não for especificado, a opção interna LabelFilter.Null será usada.

Filtros de etiqueta

O parâmetro de filtros de rótulo seleciona pares chave-valor com rótulos específicos. Um valor-chave só será carregado se ele tiver todas as marcas e valores correspondentes especificados nos filtros. Para especificar um valor nulo para uma tag, o recurso interno TagValue.Null pode ser usado.

Cortar prefixo de chaves

Ao carregar valores de configuração com prefixos específicos, você pode usar o TrimKeyPrefix método para remover esses prefixos das chaves em sua configuração. Isso cria chaves de configuração mais limpas em seu aplicativo, mantendo a organização em seu repositório de Configuração de Aplicativos.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and trim the prefix
        .Select("TestApp:*")
        .TrimKeyPrefix("TestApp:");
});

Por exemplo, se o repositório de Configuração de Aplicativos contiver uma chave nomeada TestApp:Settings:Message, ela estará acessível em seu aplicativo como Settings:Message depois de cortar o TestApp: prefixo.

Mapeamento de configurações

Ao carregar valores-chave da Configuração de Aplicativos do Azure, o provedor os recupera primeiro como ConfigurationSetting objetos antes de adicioná-los ao sistema de configuração do .NET. A Map API permite que você transforme essas configurações durante esse pipeline, dando a você controle sobre como as configurações aparecem em seu aplicativo.

O Map método aceita uma função delegada que recebe um ConfigurationSetting objeto, permite modificá-lo e retorna um ValueTask<ConfigurationSetting>. Isso é particularmente útil para transformações de nome de chave ou formatação de valor com base em condições de runtime.

O exemplo a seguir demonstra o uso da API Map para substituir sublinhados duplos (__) por dois-pontos (:) em chaves de configuração. Essa transformação preserva a estrutura hierárquica esperada pela configuração do .NET quando as chaves precisam usar caracteres alternativos na Configuração de Aplicativo:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .Map((setting) =>
        {
            // Transform keys from format "App__Settings__Message" to "App:Settings:Message"
            setting.Key = setting.Key.Replace("__", ":");
            
            return new ValueTask<ConfigurationSetting>(setting);
        });
});

Atualização de configuração

A configuração da atualização permite que o aplicativo extraia os valores mais recentes do repositório de Configuração de Aplicativos sem precisar reiniciar. Você pode chamar o método ConfigureRefresh para configurar a atualização de chave-valor.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh when any selected key changes.
            refreshOptions.RegisterAll()
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Dentro do ConfigureRefresh método, você chama o RegisterAll método para instruir o provedor de Configuração de Aplicativos a recarregar a configuração sempre que detectar uma alteração em qualquer um dos valores de chave selecionados (aqueles que começam com TestApp: e sem rótulo).

Você pode adicionar uma chamada para o método SetRefreshInterval para especificar o tempo mínimo entre as atualizações de configuração. Se não estiver definido, o intervalo de atualização padrão será de 30 segundos.

Iniciar atualização

Para disparar a atualização, você precisa chamar o TryRefreshAsync método do IConfigurationRefresher. A Configuração de Aplicativos do Azure fornece vários padrões para implementação, dependendo da arquitetura do aplicativo.

1. Injeção de dependência

Para aplicativos que usam injeção de dependência (incluindo ASP.NET Core e serviços em segundo plano), registre o serviço de atualização:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromSeconds(60));
           })
});

// Register refresher service with the DI container
builder.Services.AddAzureAppConfiguration();

builder.Services.AddAzureAppConfiguration() adiciona o serviço IConfigurationRefreshProvider ao contêiner de DI, que fornece acesso aos atualizadores de todas as fontes da Configuração de Aplicativos do Azure na configuração do aplicativo.

Aplicativos do ASP.NET Core

Para aplicativos ASP.NET Core, você pode usar o Microsoft.Azure.AppConfiguration.AspNetCore pacote para obter a atualização de configuração controlada por solicitação com um middleware interno.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Depois de registrar o serviço, chame UseAzureAppConfiguration para adicionar o AzureAppConfigurationRefreshMiddleware ao pipeline de sua aplicação para atualizar automaticamente a configuração em solicitações de entrada.

...

// Call the AddAzureAppConfiguration to add refresher service to the DI container
builder.Services.AddAzureAppConfiguration();

var app = builder.Build();

// Call the app.UseAzureAppConfiguration() method as early as appropriate in your request pipeline so another middleware doesn't skip it
app.UseAzureAppConfiguration();

// Continue with other middleware registration
app.UseRouting();
...

O AzureAppConfigurationRefreshMiddleware verifica automaticamente alterações de configuração no intervalo de atualização configurado. Essa abordagem é eficiente, pois só é atualizada quando ambas as condições são atendidas: uma solicitação HTTP é recebida e o intervalo de atualização decorrido.

Serviços em segundo plano

Para serviços em segundo plano, você pode injetar o serviço IConfigurationRefresherProvider e atualizar manualmente cada um dos atualizadores registrados.

public class Worker : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly IEnumerable<IConfigurationRefresher> _refreshers;

    public Worker(IConfiguration configuration, IConfigurationRefresherProvider refresherProvider)
    {
        _configuration = configuration;
        _refreshers = refresherProvider.Refreshers;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        foreach (IConfigurationRefresher refresher in _refreshers)
        {
            refresher.TryRefreshAsync();
        }

        ...
    }
}

2. Acesso direto

Para aplicativos que não usam injeção de dependência, você pode obter o atualizador diretamente das opções:

IConfigurationRefresher refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
               refreshOptions.RegisterAll();
           });

    // Store the refresher for later use
    refresher = options.GetRefresher();
});

IConfiguration config = builder.Build();

// Later in your code, trigger refresh when needed
if (refresher != null)
{
    await refresher.TryRefreshAsync()
}

Console.WriteLine(config["TestApp:Settings:Message"]);

Atualizar na chave sentinela

Uma chave sentinela é uma chave que você atualiza depois de concluir a alteração de todas as outras chaves. O provedor de configuração monitora a chave sentinela em vez de todos os valores de chave selecionados. Quando uma alteração é detectada, o aplicativo atualiza todos os valores de configuração.

Essa abordagem é útil ao atualizar vários valores-chave. Atualizando a chave sentinela somente depois que todas as outras alterações de configuração forem concluídas, verifique se o aplicativo recarrega a configuração apenas uma vez, mantendo a consistência.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh only if the `SentinelKey` changes.
            refreshOptions.Register("SentinelKey", refreshAll: true);
        });
});

Para obter mais informações sobre a configuração de atualização, acesse Tutorial: Usar a configuração dinâmica em um aplicativo ASP.NET Core.

Sinalizador de recurso

Os sinalizadores de recursos na Configuração de Aplicativos do Azure fornecem uma maneira moderna de controlar a disponibilidade de recursos em seus aplicativos. Ao contrário dos valores de configuração regulares, os sinalizadores de recursos devem ser carregados explicitamente usando o UseFeatureFlags método. Você pode configurar em FeatureFlagOptions para carregar sinalizadores de recursos específicos usando seletores e definir o intervalo de atualização do sinalizador de recursos.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .UseFeatureFlags(featureFlagOptions => {
            // Load feature flags with prefix "TestApp:" and "dev" label
            featureFlagOptions.Select("TestApp:*", "dev")
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

Dentro do método UseFeatureFlags, chame o método Select para carregar seletivamente sinalizadores de recursos. Você pode usar filtro de chave, filtro de rótulo e filtros de marca para selecionar os sinalizadores de recurso que deseja carregar. Se nenhum Select método for chamado, UseFeatureFlags carregará todos os sinalizadores de recursos sem rótulo por padrão.

Diferente dos valores-chave, as flags de funcionalidades são registradas automaticamente para atualização automática sem a necessidade de se fazer uma chamada explícita ConfigureRefresh. Você pode especificar o tempo mínimo entre as atualizações do sinalizador de recurso por meio do SetRefreshInterval método. O intervalo de atualização padrão é de 30 segundos.

Gerenciamento de funcionalidades

A biblioteca de gerenciamento de recursos fornece uma maneira de desenvolver e expor a funcionalidade do aplicativo com base em sinalizadores de recursos. A biblioteca de gerenciamento de recursos foi projetada para funcionar em conjunto com a biblioteca do provedor de configuração. Instalar o pacote Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

Você pode chamar AddFeatureManagement para registrar IVariantFeatureManager e serviços relacionados no contêiner de DI. Esse registro disponibiliza a funcionalidade do sinalizador de recursos em todo o aplicativo por meio da injeção de dependência.

using Microsoft.FeatureManagement;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Use feature flags
    options.UseFeatureFlags();
});

// Register feature management services
builder.Services.AddFeatureManagement();

O exemplo a seguir demonstra como usar o serviço do gerenciador de funcionalidades por meio da injeção de dependências.

public class WeatherForecastController : ControllerBase
{
    private readonly IFeatureManager _featureManager;

    public WeatherForecastController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        // Check if a feature flag is enabled
        if (await _featureManager.IsEnabledAsync("WeatherForecast"))
        {
            var forecast = GenerateWeatherForecast();
            return Ok(forecast);
        }
        
        return NotFound("Weather forecast feature is not available");
    }
}

Para obter mais informações sobre como usar a biblioteca de gerenciamento de recursos, acesse o início rápido do sinalizador de recursos.

Telemetria de sinalizador de recursos

Quando a telemetria do sinalizador de recursos está habilitada, o provedor de Configuração de Aplicativos do Azure injeta propriedades adicionais aos dados de telemetria do sinalizador de recursos. Essas propriedades fornecem mais contexto sobre o sinalizador de recursos e sua avaliação:

• AllocationID: um identificador exclusivo que representa o estado da alocação do flag de característica.
• ETag: a ETag atual para o sinalizador de recursos.
• FeatureFlagReference: uma referência ao sinalizador de recurso no formato de <your_store_endpoint>kv/<feature_flag_key>. Quando um rótulo está presente, a referência o inclui como um parâmetro de consulta: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

O esquema completo pode ser encontrado na definição de esquema de evento de avaliação de recursos de configuração de aplicativo. Para obter mais informações sobre como usar a telemetria do sinalizador de recurso, acesse o passo a passo habilitar a telemetria para sinalizadores de recursos .

Referência do Key Vault

A Configuração de Aplicativos do Azure dá suporte à referência a segredos armazenados no Azure Key Vault. Na Configuração de Aplicativos, você pode criar chaves que mapeiam para segredos armazenados no Key Vault. Os segredos são armazenados com segurança no Key Vault, mas podem ser acessados como qualquer outra configuração depois de carregadas.

A biblioteca do provedor de configuração recupera as referências do Key Vault, assim como faz para qualquer outra chave armazenada na Configuração de Aplicativos. Como o cliente reconhece as chaves como referências do Key Vault, elas têm um tipo de conteúdo exclusivo e o cliente se conecta ao Key Vault para recuperar seus valores para seu aplicativo.

Conectar-se ao Key Vault

Você precisa chamar o ConfigureKeyVault método para configurar como se conectar ao Key Vault. O provedor de Configuração de Aplicativos do Azure oferece várias maneiras de autenticar e acessar seus segredos do Key Vault.

1. Registrar a instância SecretClient

Você pode registrar instâncias SecretClient especificadas a serem usadas para resolver referências do cofre de chaves para segredos do cofre de chaves associado.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

...

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Register a SecretClient instance
            kv.Register(secretClient);
        });
});

2. Usar credencial

Você pode definir a credencial usada para autenticar em cofres de chaves que não têm nenhum registro SecretClient.

using Azure.Identity;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Use DefaultAzureCredential to access all Key Vaults
            kv.SetCredential(new DefaultAzureCredential());
        });
});

3. Usar resolvedor de segredo personalizado

Você também pode chamar SetSecretResolver para adicionar um resolvedor de segredo personalizado, que é utilizado caso não haja um SecretClient registrado disponível ou a credencial fornecida não consiga autenticar no Key Vault. Esse método aceita uma função delegada que resolve um URI do Key Vault para um valor secreto. O exemplo a seguir demonstra o uso de um resolvedor de segredo que recupera um segredo de variáveis de ambiente no desenvolvimento e usa valores de fallback quando ele não consegue obter o segredo do Key Vault.

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Add a custom secret resolver function
            kv.SetSecretResolver(async (Uri secretUri) =>
            {                
                if (builder.Environment.IsDevelopment())
                {
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }

                try 
                {
                    var secret = await secretClient.GetSecretAsync(secretName);
                    return secret.Value;
                }
                catch (Exception ex)
                {
                    logger.LogWarning($"Failed to retrieve secret from {secretUri}: {ex.Message}");
                    
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }
            });
        });
});

Atualização de segredos do Key Vault

A Configuração de Aplicativos do Azure permite que você configure intervalos de atualização secretos independentemente do ciclo de atualização de configuração. Isso é crucial para a segurança porque, embora o URI de referência do Key Vault na Configuração de Aplicativos permaneça inalterado, o segredo subjacente no Key Vault poderá ser girado como parte de suas práticas de segurança.

Para garantir que seu aplicativo sempre use os valores de segredo mais atuais, configure o SetSecretRefreshInterval método. Isso força o provedor a recuperar novos valores secretos do Key Vault quando:

• Seu aplicativo chama IConfigurationRefresher.TryRefreshAsync
• O intervalo de atualização configurado para o segredo já transcorreu.

Esse mecanismo funciona mesmo quando nenhuma alteração é detectada no repositório da Configuração de Aplicativos, garantindo que seu aplicativo permaneça sincronizado com segredos girados.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureKeyVault(kv =>
        {
            kv.SetCredential(new DefaultAzureCredential());

            // Option 1: Set refresh interval for specific secrets
            kv.SetSecretRefreshInterval("ApiKey", TimeSpan.FromHours(12)); 
            
            // Option 2: Set a global refresh interval for all secrets with no refresh interval specified
            kv.SetSecretRefreshInterval(TimeSpan.FromHours(24));
        })
        .ConfigureRefresh(refreshOptions => refreshOptions.RegisterAll());
});

Para obter mais informações sobre como usar a referência do Key Vault, acesse o Tutorial: Usar referências do Key Vault em um aplicativo ASP.NET Core.

Instantâneo

O instantâneo é um subconjunto nomeado e imutável dos valores-chave de um repositório da Configuração de Aplicativos. Os pares chave-valor que compõem um instantâneo são escolhidos no momento da criação por meio do uso de filtros de chave e rótulo. Depois que um instantâneo é criado, os pares chave-valor nele contidos têm a garantia de permanecer inalterados.

Você pode chamar SelectSnapshot para carregar valores-chave de um instantâneo.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Select an existing snapshot by name. This adds all of the key-values and feature flags from the snapshot to this application's configuration.
    options.SelectSnapshot("SnapshotName");
});

Para obter informações sobre como usar instantâneos, vá para Criar e usar instantâneos.

Referência de instantâneo

Uma referência de instantâneo é uma configuração que faz referência a um instantâneo no mesmo repositório de Configuração de Aplicativos. Quando carregado, o provedor a resolverá e adicionará todos os pares de chave-valor desse instantâneo. O uso de referências de instantâneo permite a comutação entre instantâneos em tempo de execução, ao contrário de SelectSnapshot("..."), que requer alterações de código e/ou reinicializações para alternar para um novo instantâneo.

Tentar novamente a inicialização

O carregamento de configuração é uma operação de caminho crítico durante a inicialização do aplicativo. Para garantir a confiabilidade, o provedor de Configuração de Aplicativos do Azure implementa um mecanismo de repetição robusto durante a carga de configuração inicial. Isso ajuda a proteger seu aplicativo contra problemas transitórios de rede que, de outra forma, podem impedir a inicialização bem-sucedida.

Você pode personalizar esse comportamento usando o ConfigureStartupOptions método:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureStartupOptions(startupOptions =>
        {
            // Set the time-out for the initial configuration load
            startupOptions.Timeout = TimeSpan.FromSeconds(60);
        });
});

Replicação geográfica

Para obter informações sobre como usar a replicação geográfica, acesse Habilitar a replicação geográfica.

Rastreamento distribuído

O provedor .NET da Configuração de Aplicativo do Azure inclui suporte interno para rastreamento distribuído, permitindo que você monitore e solucione problemas de operações de configuração em seu aplicativo. O provedor expõe um ActivitySource nomeado "Microsoft.Extensions.Configuration.AzureAppConfiguration" que inicia Activity para operações essenciais, como carregar a configuração e atualizar a configuração.

O exemplo a seguir demonstra como configurar o OpenTelemetry para capturar e monitorar rastreamentos distribuídos gerados pelo provedor de configuração:

List<Activity> exportedActivities = new();
builder.Services.AddOpenTelemetry()
    .WithTracing(traceBuilder => {
        traceBuilder.AddSource(["Microsoft.Extensions.Configuration.AzureAppConfiguration"]);
            .AddInMemoryExporter(exportedActivities)
    });

Para obter mais informações sobre o OpenTelemetry no .NET, consulte a documentação do .NET do OpenTelemetry.

Verificação de saúde

O provedor .NET da Configuração de Aplicativo do Azure dá suporte a verificações de integridade do aplicativo .NET. Para habilitar verificações de integridade, você pode chamar o método AddAzureAppConfiguration() em IHealthChecksBuilder, que adicionará um IHealthCheck com um nome de registro padrão de "Microsoft.Extensions.Configuration.AzureAppConfiguration".

builder.Configuration.AddAzureAppConfiguration(options => 
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential()));

builder.Services.AddHealthChecks()
    .AddAzureAppConfiguration();

O provedor .NET será considerado não íntegro quando a última tentativa de carregamento ou atualização falhar.

Para obter mais informações sobre verificações de integridade no .NET, consulte a documentação de monitoramento de integridade do .NET.

Próximas etapas

Para saber como usar o provedor de configuração do .NET, prossiga para o tutorial a seguir.