Configuração de Aplicativos do Azure biblioteca de clientes para .NET – versão 1.2.1

A Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizar seus aplicativos e suas configurações de recursos de maneira simples e segura.

Use a biblioteca de clientes para Configuração de Aplicativos para:

• Criar e gerenciar definições de configuração de aplicativo armazenado centralmente

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Configuração de Aplicativos do Azure para .NET com o NuGet:

dotnet add package Azure.Data.AppConfiguration

Pré-requisitos

• Uma assinatura do Azure.
• Um Repositório de Configurações existente.

Se você precisar criar um Repositório de Configurações, poderá usar o Portal do Azure ou a CLI do Azure.

Você pode usar a CLI do Azure para criar o Repositório de Configurações com o seguinte comando:

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

Autenticar o cliente

Para interagir com o serviço Configuração de Aplicativos, você precisará criar uma instância da classe Cliente de Configuração. Para tornar isso possível, você precisará da cadeia de conexão do Repositório de Configurações.

Obter credenciais

Use o snippet da CLI do Azure abaixo para obter a cadeia de conexão do Repositório de Configurações.

az appconfig credential list --name <config-store-name>

Como alternativa, obtenha a cadeia de conexão no Portal do Azure.

Criar ConfigurationClient

Depois de ter o valor da cadeia de conexão, você poderá criar o ConfigurationClient:

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);

Criar ConfigurationClient com a Credencial do Azure Active Directory

A autenticação de chave de assinatura do cliente é usada na maioria dos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote Azure.Identity:

dotnet add package Azure.Identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao Repositório de Configurações atribuindo a "App Configuration Data Reader" função ou "App Configuration Data Owner" à entidade de serviço.

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET.

string endpoint = "<endpoint>";
var client = new ConfigurationClient(new Uri(endpoint), new DefaultAzureCredential());

Principais conceitos

Definição de configuração

Uma Definição de Configuração é o recurso fundamental dentro de um Repositório de Configurações. Em sua forma mais simples, é uma chave e um valor. No entanto, há propriedades adicionais, como o tipo de conteúdo modificável e os campos de marcas que permitem que o valor seja interpretado ou associado de maneiras diferentes.

A propriedade Label de uma Configuração fornece uma maneira de separar as Definições de Configuração em dimensões diferentes. Essas dimensões são definidas pelo usuário e podem assumir qualquer forma. Alguns exemplos comuns de dimensões a serem usadas para um rótulo incluem regiões, versões semânticas ou ambientes. Muitos aplicativos têm um conjunto necessário de chaves de configuração que têm valores variados à medida que o aplicativo existe em diferentes dimensões.

Por exemplo, MaxRequests pode ser 100 em "NorthAmerica" e 200 em "WestEurope". Ao criar uma Configuração chamada MaxRequests com um rótulo "NorthAmerica" e outro, somente com um valor diferente, com um rótulo "WestEurope", um aplicativo pode recuperar perfeitamente as Definições de Configuração conforme é executado nessas duas dimensões.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | clienteAcessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço de Configuração. Observe que há métodos de sincronização e assíncronos disponíveis para ambos.

• Criar uma configuração
• Recuperar uma configuração
• Atualizar uma configuração existente
• Excluir uma configuração

Criar uma configuração

Crie uma Configuração a ser armazenada no Repositório de Configurações. Há duas maneiras de armazenar uma Configuração:

• AddConfigurationSetting criará uma configuração somente se a configuração ainda não existir no repositório.
• SetConfigurationSetting criará uma configuração se ela não existir ou substituir uma configuração existente.

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
var settingToCreate = new ConfigurationSetting("some_key", "some_value");
ConfigurationSetting setting = client.SetConfigurationSetting(settingToCreate);

Recuperar uma configuração

Recupere uma configuração armazenada anteriormente chamando GetConfigurationSetting. Esse snippet pressupõe que a configuração "some_key" existe no repositório de configuração.

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.GetConfigurationSetting("some_key");

Atualizar uma configuração existente

Atualize uma configuração existente chamando SetConfigurationSetting. Esse snippet pressupõe que a configuração "some_key" existe no repositório de configuração.

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.SetConfigurationSetting("some_key", "new_value");

Excluir uma configuração

Exclua uma configuração existente chamando DeleteConfigurationSetting. Esse snippet pressupõe que a configuração "some_key" existe no repositório de configuração.

string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
client.DeleteConfigurationSetting("some_key");

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Próximas etapas

Mais códigos de exemplo

Várias Configuração de Aplicativos exemplos de biblioteca de clientes estão disponíveis para você neste repositório GitHub. Estão incluídos:

• Olá, mundo: crie e exclua uma configuração.
• Olá, mundo assíncrono com rótulos: crie, atualize e exclua as configurações de forma assíncrona com rótulos.
• Faça uma configuração de configuração somente leitura: torne uma configuração somente leitura e, em seguida, retorne-a a um estado de leitura/gravação.
• Ler histórico de revisão: leia o histórico de revisão de uma configuração que foi alterada.
• Obter uma configuração se alterada: salve a largura de banda usando uma solicitação condicional para recuperar uma configuração somente se ela for diferente da sua cópia local.
• Atualize uma configuração se ela não tiver sido alterada: evite atualizações perdidas usando simultaneidade otimista para atualizar uma configuração somente se suas atualizações locais foram aplicadas à mesma versão que o recurso no repositório de configuração.
• Criar um cliente fictício: simular um cliente para teste.

Para obter mais detalhes, consulte os exemplos README.

Participante

Consulte a Configuração de Aplicativos CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.