Biblioteca de cliente partilhada do Azure Core para .NET – versão 1.30.0

O Azure.Core fornece primitivos partilhados, abstrações e auxiliares para bibliotecas de cliente modernas do SDK do .NET do Azure. Estas bibliotecas seguem as Diretrizes de Estrutura do SDK do Azure para .NET e podem ser facilmente identificadas por nomes de pacotes e espaços de nomes a partir do "Azure", por exemplo, Azure.Storage.Blobs. Pode encontrar uma lista mais completa das bibliotecas de cliente com o Azure.Core aqui.

O Azure.Core permite que as bibliotecas de cliente exponham funcionalidades comuns de forma consistente, para que, assim que aprender a utilizar estas APIs numa biblioteca de cliente, saiba como utilizá-las noutras bibliotecas de cliente.

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

Introdução

Normalmente, não terá de instalar o Azure.Core; será instalado automaticmente quando instalar uma das bibliotecas de cliente que a utilizar. Caso pretenda instalá-la explicitamente (para implementar a sua própria biblioteca de cliente, por exemplo), pode encontrar o pacote NuGet aqui.

Conceitos-chave

Os principais conceitos partilhados do Azure.Core (e, por isso, bibliotecas do SDK do Azure com o Azure.Core) incluem:

• Configurar clientes de serviço, por exemplo, configurar repetições, registo (ClientOptions).
• Aceder aos detalhes da resposta HTTP (Response, Response<T>).
• Chamar operações de execução prolongada (Operation<T>).
• Fluxos paginados e assíncronos (AsyncPageable<T>).
• Exceções para comunicar erros de pedidos de serviço de forma consistente. (RequestFailedException).
• A personalizar o pedido (RequestContext).
• Abstrações para representar credenciais do SDK do Azure. (TokenCredentials).

Abaixo, encontrará secções que explicam estes conceitos partilhados mais detalhadamente.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Opções de | cliente Aceder à resposta | Operações de execução prolongada | Lidar com falhas | Diagnósticos | A gozar | Duração do cliente

Exemplos

NOTA: Os exemplos neste ficheiro aplicam-se apenas aos pacotes que seguem as Diretrizes de Estrutura do SDK do Azure. Normalmente, os nomes desses pacotes começam com Azure.

Configurar Clientes de Serviço com ClientOptions

Normalmente, as bibliotecas de cliente do SDK do Azure expõem um ou mais tipos de cliente de serviço que são os principais pontos de partida para chamar os serviços do Azure correspondentes. Pode encontrar facilmente estes tipos de cliente à medida que os respetivos nomes terminam com a palavra Cliente. Por exemplo, BlockBlobClient pode ser utilizado para chamar o serviço de armazenamento de blobs e KeyClient pode ser utilizado para aceder Key Vault chaves criptográficas do serviço.

Estes tipos de cliente podem ser instanciados ao chamar um construtor simples ou à sua sobrecarga que utiliza várias opções de configuração. Estas opções são transmitidas ClientOptions como um parâmetro que expande a classe exposta pelo Azure.Core. Geralmente, são adicionadas várias opções específicas do serviço às respetivas subclasses, mas um conjunto de opções ao nível do SDK estão disponíveis 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 nos exemplos de configuração do cliente

Aceder aos Detalhes da Resposta HTTP Com Response<T>

Os clientes de serviço têm métodos que podem ser utilizados para chamar serviços do Azure. Referimo-nos a estes métodos de serviço de métodos de cliente. Os métodos de serviço devolvem um tipo Response<T> partilhado Azure.Core (em casos raros, o respetivo elemento colateral não genérico, um valor bruto Response). Este tipo fornece acesso ao resultado anular a serialização da chamada de serviço e aos detalhes da resposta HTTP devolvida pelo 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 informações sobre tipos de resposta em exemplos de resposta

Configurar o registo da consola

Para criar um serviço de escuta de registos do SDK do Azure que produz mensagens para a consola, utilize AzureEventSourceListener.CreateConsoleLogger o método .

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

Mais informações sobre o registo nos exemplos de diagnóstico

Comunicar Erros RequestFailedException

Quando uma chamada de serviço falha Azure.RequestFailedException , é emitida. O tipo de exceção fornece uma propriedade Status com um código de estado HTTP 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

A Devolver Métodos de Serviço De Consumo AsyncPageable<T>

Se uma chamada de serviço devolver vários valores em páginas, devolverá Pageable<T>/AsyncPageable<T> como resultado. 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 as respostas paginadas, veja Pagination with the Azure SDK for .NET (Paginação com o SDK do Azure para .NET).

Consumir Operações de Long-Running Com Operation<T>

Algumas operações demoram muito tempo a concluir e requerem consulta para o seu estado. Os métodos que iniciam operações de execução prolongada devolvem *Operation<T> tipos.

O WaitForCompletionAsync método é uma forma fácil de esperar pela 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 informações sobre operações de execução prolongada em exemplos de operação de execução prolongada

Personalizar o Pedido Com RequestContext

Além da configuração geral dos clientes de serviço atravésClientOptionsdo , é possível personalizar os pedidos enviados pelos clientes de serviço através de 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 pedidos em exemplos requestContext

A gozar

Uma das funcionalidades cruzadas mais importantes das nossas novas bibliotecas de cliente com o Azure.Core é que foram concebidas para simulação. A simulação é ativada por:

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

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

// 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 gozar com amostras de simulação

Rastreio distribuído com o Application Insights

O Application Insights, uma funcionalidade do Azure Monitor, é um serviço extensível de APM (Gestão de Desempenho de Aplicações) para programadores e profissionais do DevOps. Utilize-a para monitorizar as suas aplicações em direto. Detetará automaticamente anomalias de desempenho e inclui ferramentas de análise avançadas para o ajudar a diagnosticar problemas e a compreender o que os utilizadores realmente fazem com a sua aplicação

Se a sua aplicação já utilizar o ApplicationInsights, a coleção automática de rastreios do SDK do Azure é suportada desde a versão 2.12.0.

Para configurar o applicationInsights tracking para a sua aplicação, siga o guia Iniciar Aplicação de Monitorização .

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

Resolução de problemas

Três formas principais de resolver problemas de falhas são inspecionar exceções, ativar o registo e rastreio distribuído

Passos seguintes

Explorar e instalar bibliotecas do SDK do Azure disponíveis.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Só terá de o fazer uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.