Partilhar via

Provedor de configuração .NET

Microsoft.Extensions.Configuration.AzureAppConfiguration

A Configuração da Aplicação Azure é um serviço gerido que ajuda os programadores a centralizar as respetivas configurações de aplicações de forma simples e segura. A biblioteca do provedor de configuração .NET permite carregar a configuração de um repositório de Configuração de Aplicativo do Azure de forma gerenciada. Esta biblioteca de cliente adiciona funcionalidade adicional ao SDK do Azure para .NET.

Configuração de carga

O provedor de configuração .NET de Configuração de Aplicativo do Azure integra-se ao sistema de configuração .NET, facilitando o carregamento de valores de configuração de sua loja de Configuração de Aplicativo 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 .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 fornecedor de configuração da sua aplicação.

A biblioteca do provedor de configuração implementa um Padrão de Opções e um Padrão do Construtor combinados 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 seu repositório de Configuração de Aplicativo do Azure, chame o método Connect na instância AzureAppConfigurationOptions, que retorna o mesmo objeto de opções para habilitar o encadeamento de métodos.

Você pode usar o DefaultAzureCredential, ou qualquer outra implementação de credencial de token, para autenticar em sua loja de configuração de aplicativos. Siga as instruções para atribuir à sua credencial a função de Leitor de Dados de Configuração do Aplicativo.

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

Observação

Em uma aplicação ASP.NET Core ou em um serviço em segundo plano, pode-se chamar AddAzureAppConfiguration em builder.Configuration.

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

Configuração de consumo

Depois de adicionar o provedor de Configuração de Aplicativo 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 de tipos estritos

// 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, vá para a documentação.

Tratamento de tipo de conteúdo JSON

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

Observação

A partir da versão 8.4.0 do Microsoft.Extensions.Configuration.AzureAppConfiguration, o provedor de configuração permite comentários, conforme definido em (JSONC), em pares-chave-valor com um tipo de conteúdo application/json.

Carregue valores-chave específicos usando seletores

Por padrão, o provedor de configuração carrega todos os valores-chave sem rótulo da Configuração da Aplicação. Você pode carregar seletivamente valores-chave do seu repositório de 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-chave com rótulos específicos para carregar, e o terceiro parâmetro especifica uma coleção de filtros de tag que todos devem estar presentes em um valor-chave para carregar.

Observação

Quando várias Select chamadas incluem chaves sobrepostas, as chamadas posteriores têm precedência sobre as anteriores.

Filtro principal

O parâmetro de filtro de chave determina quais chaves de configuração devem ser incluídas:

  • Correspondência exata: Usar uma sequência de caracteres específica faz corresponder apenas as chaves que correspondem exatamente ao filtro.
  • Correspondência de prefixo: Adicionar um asterisco (*) no final cria um filtro de prefixo (por exemplo, carrega todas as chaves que começam com "App:Settings:").
  • Seleção de várias chaves: O uso de 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.).

Observação

Não é possível combinar correspondência de prefixo curinga com filtros separados por vírgulas na mesma chamada Select. Por exemplo, abc*,def não é suportado, mas você pode fazer chamadas separadas Select com abc* e def.

Filtro de etiquetas

O parâmetro label filter seleciona valores-chave com um rótulo específico. Se não for especificado, o LabelFilter.Null integrado é usado.

Observação

Os caracteres asterisco (*) e vírgula (,), não são suportados para o filtro de rótulo. O caractere de barra invertida (\) é reservado e deve ser escapado usando outro caractere de barra invertida (\).

Filtros de tags

O parâmetro tag filters seleciona valores-chave com tags específicas. Um valor-chave só é carregado se tiver todas as tags e valores correspondentes especificados nos filtros. Para especificar um valor nulo para uma tag, o built-in TagValue.Null pode ser usado.

Observação

Os caracteres asterisco (*), vírgula (,) e barra inversa (\) são reservados e devem ser escapados com uma barra inversa quando usados num filtro de etiqueta.

Cortar prefixo das teclas

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 enquanto mantém a organização em sua loja 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 a sua loja de Configuração de Aplicações contiver uma chave com o nome TestApp:Settings:Message, esta estará acessível na sua aplicação como Settings:Message depois de cortar o prefixo TestApp: .

Mapeamento de definições de configuração

Ao carregar valores-chave da Configuração do Aplicativo do Azure, o provedor primeiro os recupera como ConfigurationSetting objetos antes de adicioná-los ao sistema de configuração .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 método Map aceita uma função delegada que recebe um objeto ConfigurationSetting, 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 tempo de execução.

O exemplo a seguir demonstra o uso da Map API 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 do 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);
        });
});

Sugestão

A Map operação é aplicada a todas as definições de configuração recuperadas da Configuração do aplicativo, portanto, certifique-se de que sua lógica de transformação manipule todos os formatos de chave possíveis corretamente.

Atualização de configuração

A configuração da atualização permite que o aplicativo extraia os valores mais recentes da App Configuration Store sem precisar reiniciar. Você pode chamar o método ConfigureRefresh para configurar a atualização 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 do Aplicativo a recarregar a configuração sempre que ele detetar uma alteração em qualquer um dos valores-chave selecionados (aqueles que começam com TestApp: e não têm rótulo).

Você pode adicionar uma chamada ao SetRefreshInterval método 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 é de 30 segundos.

Acionar a atualização

Para acionar a atualização, é necessário chamar o método TryRefreshAsync do IConfigurationRefresher. A Configuração de Aplicativo do Azure fornece vários padrões para implementação, dependendo da arquitetura do seu aplicativo.

1. Injeção de dependência

Para aplicações que usam injeção de dependência (incluindo ASP.NET Core e serviços em segundo plano), registe 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 IConfigurationRefreshProvider serviço ao contêiner DI, que lhe dá acesso às atualizações de todas as fontes de Configuração de Aplicativo do Azure na configuração do aplicativo.

ASP.NET Aplicações principais

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

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

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

...

// 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 se há 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, pode-se injetar o serviço IConfigurationRefresherProvider e atualizar manualmente cada um dos refrescadores 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 a atualização 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"]);

Observação

Mesmo que a chamada de atualização falhe por qualquer motivo, seu aplicativo continuará a usar a configuração em cache. Outra tentativa é feita após um curto período com base na atividade do seu aplicativo. A chamada da função refresh é realizada como um no-op antes de o intervalo de atualização configurado decorrer, portanto, o impacto no desempenho é mínimo, mesmo que seja chamado com frequência.

Atualizar a 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-chave selecionados. Quando uma alteração é detetada, seu aplicativo atualiza todos os valores de configuração.

Essa abordagem é útil ao atualizar vários valores-chave. Ao atualizar a chave sentinela somente depois que todas as outras alterações de configuração forem concluídas, você garante que seu aplicativo recarregue 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);
        });
});

Importante

Os valores-chave não são registrados automaticamente para monitoramento de atualização. Você deve chamar ConfigureRefresh explicitamente e registrar chaves usando o RegisterAll método (para monitorar todas as chaves carregadas) ou o Register método (para monitorar uma chave individual).

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

Sinalizador de recurso

Os sinalizadores de recursos na Configuração de Aplicativo 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 explicitamente carregados usando o UseFeatureFlags método. Você pode configurar o FeatureFlagOptions para carregar sinalizadores de recursos específicos usando seletores e definir o intervalo de atualização dos sinalizadores 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 UseFeatureFlags método, você chama o Select método para carregar seletivamente sinalizadores de recurso. Você pode usar filtro de chave, filtro de rótulo e filtros de tag para selecionar os sinalizadores de recursos 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, os flags de funcionalidades são registados automaticamente para atualização sem exigir 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.

Gestão 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. Instale o pacote Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

Você pode ligar AddFeatureManagement para registrar IVariantFeatureManager e serviços relacionados no contêiner DI. Este registo torna a funcionalidade de 'feature flag' disponível através de toda a sua aplicação por meio de injeção de dependências.

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 gerenciador de recursos por meio da injeção de dependência:

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, vá para o início rápido do sinalizador de recursos.

Telemetria da bandeira de funcionalidades

Quando a telemetria de feature flag está ativada, o provedor Azure App Configuration injeta propriedades adicionais nos dados de telemetria de feature flag. Estas propriedades fornecem mais contexto sobre a feature flag e a sua avaliação:

  • AllocationID: Um identificador único que representa o estado da alocação da feature flag.
  • ETag: O ETag atual para o sinalizador de funcionalidade.
  • FeatureFlagReference: Uma referência à feature flag no formato de <your_store_endpoint>kv/<feature_flag_key>. Quando uma etiqueta está presente, a referência inclui-a como parâmetro de consulta: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

O esquema completo pode ser encontrado na definição do esquema App Configuration Feature Evaluation Event. Para mais informações sobre como usar a telemetria de feature flags, consulte a orientação prática de ativação da telemetria para feature flags.

Referência do Cofre da Chave

A Configuração de Aplicativo do Azure dá suporte à referência de segredos armazenados no Cofre da Chave do Azure. Na Configuração do Aplicativo, você pode criar chaves que mapeiam para segredos armazenados no Cofre da Chave. Os segredos são armazenados com segurança no Cofre da Chave, mas podem ser acessados como qualquer outra configuração uma vez carregados.

A biblioteca do provedor de configuração recupera referências do Cofre da Chave, assim como faz para quaisquer outras chaves armazenadas na Configuração do aplicativo. Como o cliente reconhece as chaves como referências do Cofre da Chave, elas têm um tipo de conteúdo exclusivo e o cliente se conecta ao Cofre da Chave para recuperar seus valores para seu aplicativo.

Conectar-se ao Cofre da Chave

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

1. Registrar SecretClient instância

Você pode registrar instâncias especificadas SecretClient a serem usadas para resolver referências de 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. Utilize a credencial

Você pode definir a credencial usada para autenticar em cofres de chaves sem registo 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. Use o resolvedor secreto personalizado

Você também pode chamar SetSecretResolver para adicionar um resolvedor secreto personalizado, que é utilizado quando nenhum SecretClient registrado está disponível ou quando a credencial fornecida não consegue autenticar-se no Key Vault. Este método aceita uma função de delegação que resolve um URI do Cofre de Chaves para um valor secreto. O exemplo a seguir demonstra o uso de um resolvedor secreto que recupera um segredo de variáveis de ambiente em desenvolvimento e usa valores de fallback quando 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");
                }
            });
        });
});

Observação

Ao resolver referências do Key Vault, o provedor segue esta ordem:

  1. Instâncias registadas SecretClient
  2. Credencial padrão
  3. Resolvedor secreto personalizado

Importante

Se o seu aplicativo carregar valores-chave contendo referências do Cofre da Chave sem a configuração adequada do Cofre da Chave, uma exceção será lançada na inicialização. Certifique-se de ter configurado corretamente o acesso ao Cofre da Chave ou o resolvedor de segredos.

Sugestão

Você pode usar um resolvedor secreto personalizado para lidar com casos em que as referências do Cofre de Chaves são adicionadas acidentalmente à sua loja de Configuração de Aplicativos. O resolvedor pode fornecer valores de fallback, registrar avisos ou lidar eficazmente com a ausência de credenciais apropriadas para acessar o Cofre das Chaves em vez de lançar exceções.

Atualização de segredos do Cofre de Chaves

A Configuração de Aplicativo do Azure permite configurar intervalos de atualização secretos independentemente do seu ciclo de atualização de configuração. Isso é crucial para a segurança porque, embora o URI de referência do Cofre da Chave na Configuração do Aplicativo permaneça inalterado, o segredo subjacente no Cofre da Chave pode ser girado como parte de suas práticas de segurança.

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

  • A sua aplicação chama IConfigurationRefresher.TryRefreshAsync
  • O intervalo de atualização configurado para o segredo decorreu

Esse mecanismo funciona mesmo quando nenhuma alteração é detetada na sua loja de configuração de aplicações, garantindo que a sua aplicação permaneça sincronizada com segredos rodados.

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 Cofre da Chave, vá para o Tutorial: Usar referências do Cofre da Chave em um aplicativo ASP.NET Core.

Instantâneo

Snapshot é um subconjunto nomeado e imutável dos valores-chave de uma App Configuration Store. Os valores-chave que compõem um instantâneo são escolhidos durante o tempo de criação através do uso de filtros de chave e rótulo. Depois que um snapshot é criado, os valores-chave dentro têm a garantia de permanecer inalterados.

Você pode chamar SelectSnapshot para carregar valores-chave a partir 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 definição de configuração que faz referência a um instantâneo na mesma loja de configuração de aplicativos. Quando carregado, o provedor resolve e adiciona todos os valores-chave desse instantâneo. O uso de referências de snapshot permite alternar entre snapshots 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 snapshot.

Observação

Para usar referências de instantâneo, use a versão 8.4.0 ou posterior do Microsoft.Extensions.Configuration.AzureAppConfiguration.

Repetição de 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 Aplicativo do Azure implementa um mecanismo de repetição robusto durante a carga de configuração inicial. Isso ajuda a proteger seu aplicativo contra problemas de rede transitórios que, de outra forma, poderiam 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);
        });
});

Georreplicação

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

Rastreio distribuído

O provedor .NET de 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 chamado "Microsoft.Extensions.Configuration.AzureAppConfiguration" que inicia Activity para operações importantes, como o carregamento e atualização da 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 OpenTelemetry no .NET, consulte a documentação do OpenTelemetry .NET.

Exame de saúde

O provedor .NET de Configuração de Aplicativo do Azure dá suporte a verificações de integridade do aplicativo .NET. Para habilitar as verificações de integridade, você pode chamar AddAzureAppConfiguration() o método no 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 como 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óximos passos

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

Habilitar a configuração dinâmica em um aplicativo Web ASP.NET

  • Last updated on