Compartilhar via

Biblioteca de clientes compartilhados do Azure Core para .NET – versão 1.35.0

  • Artigo

O Azure.Core fornece primitivos compartilhados, abstrações e auxiliares para bibliotecas de clientes modernas do SDK do Azure do .NET. Essas bibliotecas seguem as Diretrizes de Design do SDK do Azure para .NET e podem ser facilmente identificadas por nomes de pacotes e namespaces começando com 'Azure', por exemplo. Azure.Storage.Blobs. Uma lista mais completa de bibliotecas de clientes usando o Azure.Core pode ser encontrada aqui.

O Azure.Core permite que as bibliotecas de clientes exponham a funcionalidade comum de forma consistente, para que, depois de aprender a usar essas APIs em uma biblioteca de clientes, você saiba como usá-las em outras bibliotecas de clientes.

Código-fonte | Pacote (NuGet) | Documentação de referência da API

Introdução

Normalmente, você não precisará instalar o Azure.Core; ele será instalado para você quando você instalar uma das bibliotecas de cliente usando-a. Caso deseje instalá-lo explicitamente (para implementar sua própria biblioteca de clientes, por exemplo), você pode encontrar o pacote NuGet aqui.

Principais conceitos

Os conceitos compartilhados main do Azure.Core (e, portanto, bibliotecas do SDK do Azure usando o Azure.Core) incluem:

  • Configuração de clientes de serviço, por exemplo, configuração de repetições, registro em log (ClientOptions).
  • Acessando detalhes da resposta HTTP (Response, Response<T>).
  • Chamando operações de longa execução (Operation<T>).
  • Paginação e fluxos assíncronos (AsyncPageable<T>).
  • Exceções para relatar erros de solicitações de serviço de forma consistente. (RequestFailedException).
  • Personalizando solicitações (RequestContext).
  • Abstrações para representar credenciais do SDK do Azure. (TokenCredentials).

Abaixo, você encontrará seções explicando esses conceitos compartilhados com mais detalhes.

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 prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

NOTA: Os exemplos neste arquivo se aplicam somente a pacotes que seguem as Diretrizes de Design do SDK do Azure. Os nomes desses pacotes geralmente começam com Azure.

Configurando clientes de serviço usando ClientOptions

As bibliotecas de cliente do SDK do Azure normalmente expõem um ou mais tipos de cliente de serviço que são os pontos de partida main para chamar os serviços correspondentes do Azure. Você pode encontrar facilmente esses tipos de cliente conforme seus nomes terminam com a palavra Cliente. Por exemplo, BlockBlobClient pode ser usado para chamar o serviço de armazenamento de blobs e KeyClient pode ser usado para acessar Key Vault chaves criptográficas de serviço.

Esses tipos de cliente podem ser instanciados chamando um construtor simples ou sua sobrecarga que usa várias opções de configuração. Essas opções são passadas ClientOptions como um parâmetro que estende a classe exposta pelo Azure.Core. Várias opções específicas do serviço geralmente são adicionadas às suas subclasses, mas um conjunto de opções em todo o SDK está disponível diretamente no ClientOptions.

SecretClientOptions options = new SecretClientOptions()
{
    Retry =
    {
        Delay = TimeSpan.FromSeconds(2),
        MaxRetries = 10,
        Mode = RetryMode.Fixed
    },
    Diagnostics =
    {
        IsLoggingContentEnabled = true,
        ApplicationId = "myApplicationId"
    }
};

SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options);

Mais informações sobre a configuração do cliente em exemplos de configuração de cliente.

Acessando detalhes de resposta HTTP usando Response<T>

Os clientes de serviço têm métodos que podem ser usados para chamar serviços do Azure. Nos referimos a esses métodos de serviço de métodos de cliente. Os métodos de serviço retornam um tipo Response<T> compartilhado do Azure.Core (em casos raros, seu irmão não genérico, um bruto Response). Esse tipo fornece acesso ao resultado desserializado da chamada de serviço e aos detalhes da resposta HTTP retornada do servidor.

// create a client
var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// call a service method, which returns Response<T>
Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName");

// Response<T> has two main accessors.
// Value property for accessing the deserialized result of the call
KeyVaultSecret secret = response.Value;

// .. and GetRawResponse method for accessing all the details of the HTTP response
Response http = response.GetRawResponse();

// for example, you can access HTTP status
int status = http.Status;

// or the headers
foreach (HttpHeader header in http.Headers)
{
    Console.WriteLine($"{header.Name} {header.Value}");
}

Mais sobre tipos de resposta em exemplos de resposta.

Configuração do registro em log do console

Para criar um ouvinte de log do SDK do Azure que gera mensagens para o método de uso AzureEventSourceListener.CreateConsoleLogger do console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Mais informações sobre como fazer logon em diagnóstico exemplos.

Erros de relatório RequestFailedException

Quando uma chamada de serviço falha Azure.RequestFailedException , ela é lançada. O tipo de exceção fornece uma propriedade Status com um código http status e uma propriedade ErrorCode com um código de erro específico do serviço.

try
{
    KeyVaultSecret secret = client.GetSecret("NonexistentSecret");
}
// handle exception with status code 404
catch (RequestFailedException e) when (e.Status == 404)
{
    // handle not found error
    Console.WriteLine("ErrorCode " + e.ErrorCode);
}

Mais informações sobre como lidar com respostas em exemplos de resposta.

Consumindo métodos de serviço retornando AsyncPageable<T>

Se uma chamada de serviço retornar vários valores em páginas, ela retornará Pageable<T>/AsyncPageable<T> como resultado. Você pode iterar AsyncPageable diretamente ou em páginas.

// call a service method, which returns AsyncPageable<T>
AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecretProperties)
{
    Console.WriteLine(secretProperties.Name);
}

Para obter mais informações sobre respostas paginada, consulte Paginação com o SDK do Azure para .NET.

Consumindo operações de Long-Running usando Operation<T>

Algumas operações levam muito tempo para serem concluídas e exigem sondagem para seus status. Métodos que iniciam operações de execução longa retornam *Operation<T> tipos.

O WaitForCompletionAsync método é uma maneira fácil de aguardar a conclusão da operação e obter o valor resultante.

// create a client
SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// Start the operation
DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName");

Response<DeletedSecret> response = await operation.WaitForCompletionAsync();
DeletedSecret value = response.Value;

Console.WriteLine(value.Name);
Console.WriteLine(value.ScheduledPurgeDate);

Mais sobre operações de longa execução em exemplos de operação de execução prolongada.

Personalizando solicitações usando RequestContext

Além da configuração geral de clientes de serviço por meio ClientOptionsdo , é possível personalizar as solicitações enviadas por clientes de serviço usando métodos de protocolo ou APIs de conveniência que expõem RequestContext como um parâmetro.

var context = new RequestContext();
context.AddClassifier(404, isError: false);

Response response = await client.GetPetAsync("pet1", context);

Mais informações sobre a personalização de solicitação em exemplos requestContext.

Simulação

Um dos recursos de corte cruzado mais importantes de nossas novas bibliotecas de clientes usando o Azure.Core é que elas foram projetadas para zombar. A simulação é habilitada por:

  • fornecendo um construtor sem parâmetros protegido em tipos de cliente.
  • tornando os métodos de serviço virtuais.
  • fornecendo APIs para construir tipos de modelo retornados de métodos de serviço virtual. Para localizar esses métodos de fábrica, procure tipos com o sufixo ModelFactory , por exemplo, SecretModelFactory.

Por exemplo, o método ConfigurationClient.Get pode ser ridicularizado (com o Moq) da seguinte maneira:

// Create a mock response
var mockResponse = new Mock<Response>();

// Create a mock value
var mockValue = SecretModelFactory.KeyVaultSecret(
    SecretModelFactory.SecretProperties(new Uri("http://example.com"))
);

// Create a client mock
var mock = new Mock<SecretClient>();

// Setup client method
mock.Setup(c => c.GetSecret("Name", null, default))
    .Returns(Response.FromValue(mockValue, mockResponse.Object));

// Use the client mock
SecretClient client = mock.Object;
KeyVaultSecret secret = client.GetSecret("Name");

Mais informações sobre como simular em Teste de unidade e zombar com o SDK do Azure para .NET.

Rastreamento distribuído com o Application Insights

O Application Insights, um recurso do Azure Monitor, é um serviço de APM (gerenciamento de desempenho de aplicativos) extensível para desenvolvedores e profissionais de DevOps. Use-o para monitorar seus aplicativos ativos. Ele detectará automaticamente anomalias de desempenho e inclui ferramentas de análise avançadas para ajudá-lo a diagnosticar problemas e entender o que os usuários realmente fazem com seu aplicativo

Se o aplicativo já usa o ApplicationInsights, há suporte para a coleção automática de rastreamentos do SDK do Azure desde a versão 2.12.0.

Para configurar o acompanhamento do ApplicationInsights para seu aplicativo, siga o guia Iniciar Aplicativo de Monitoramento .

Mais informações sobre diagnóstico em exemplos de diagnóstico.

Solução de problemas

Três main maneiras de solucionar problemas de falhas são inspecionar exceções, habilitar registro em log e rastreamento distribuído

Próximas etapas

Explore e instale as bibliotecas disponíveis do SDK do Azure.

Contribuição

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 https://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 usando 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.

Impressões