Usar o SDK do Azure para .NET em aplicativos ASP.NET Core

Artigo
11/16/2024

O SDK do Azure para .NET permite que os aplicativos ASP.NET Core se integrem a muitos serviços diferentes do Azure. Neste artigo, você aprenderá as práticas recomendadas e as etapas para adotar o SDK do Azure para .NET em seus aplicativos ASP.NET Core. Saberá como:

Registrar serviços para injeção de dependência.
Autentique-se no Azure sem usar senhas ou segredos.
Implemente uma configuração centralizada e padronizada.
Configure preocupações comuns com aplicativos Web, como registro em log e tentativas.

Explore bibliotecas de cliente comuns do SDK do Azure

ASP.NET aplicativos principais que se conectam aos serviços do Azure geralmente dependem das seguintes bibliotecas de cliente do SDK do Azure:

O Microsoft.Extensions.Azure fornece métodos auxiliares para registrar clientes com a coleção de serviços de injeção de dependência e lida com várias preocupações para você, como configurar o log, lidar com tempos de vida de serviço DI e gerenciamento de credenciais de autenticação.
Azure.Identity habilita o suporte à autenticação do Microsoft Entra ID no SDK do Azure. Ele fornece um conjunto de implementações TokenCredential para construir clientes SDK do Azure que oferecem suporte à autenticação Microsoft Entra.
Azure.<service-namespace> bibliotecas, como Azure.Storage.Blobs e Azure.Messaging.ServiceBus, fornecem clientes de serviço e outros tipos para ajudá-lo a se conectar e consumir serviços específicos do Azure. Para obter um inventário completo dessas bibliotecas, consulte Bibliotecas usando Azure.Core.

Nas seções a seguir, você explorará como implementar um aplicativo ASP.NET Core que usa essas bibliotecas.

Registrar clientes do SDK do Azure com a coleção de serviços DI

As bibliotecas de cliente do SDK do Azure para .NET fornecem clientes de serviço para conectar seu aplicativo aos serviços do Azure, como o Armazenamento de Blobs do Azure e o Cofre da Chave do Azure. Registre esses serviços com o contêiner de dependência no Program.cs arquivo do seu aplicativo para disponibilizá-los por meio da injeção de dependência.

Conclua as seguintes etapas para registrar os serviços de que precisa:

Adicione o pacote Microsoft.Extensions.Azure :

dotnet add package Microsoft.Extensions.Azure

Adicione os pacotes de cliente de serviço relevantes Azure.* :

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Messaging.ServiceBus

Program.cs No arquivo do seu aplicativo, invoque o AddAzureClients método de extensão da Microsoft.Extensions.Azure biblioteca para registrar um cliente para se comunicar com cada serviço do Azure. Algumas bibliotecas de cliente fornecem subclientes adicionais para subgrupos específicos da funcionalidade de serviço do Azure. Você pode registrar esses subclientes para injeção de dependência através do método de AddClient extensão.

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Injete os clientes registrados em seus componentes ASP.NET aplicativo principal, serviços ou ponto de extremidade da API:

API mínima
Blazor

app.MapGet("/reports", async (
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory) =>
{
    // Create the named client
    ServiceBusSender serviceBusSender = senderFactory.CreateClient("queue1");

    await serviceBusSender.SendMessageAsync(new ServiceBusMessage("Hello world"));

    // Use the blob client
    BlobContainerClient containerClient
        = blobServiceClient.GetBlobContainerClient("reports");

    List<BlobItem> reports = new();
    await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
    {
        reports.Add(blobItem);
    }

    return reports;
})
.WithName("GetReports");

@page "/"
@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models
@using Azure.Messaging.ServiceBus
@using Microsoft.Extensions.Azure;

<h1>Reports</h1>

<ul>
    @foreach (var report in reports)
    {
        <li>@report.Name</li>
    }
</ul>

@code {
    List<BlobItem> reports = new();

    private BlobServiceClient _blobServiceClient;
    private ServiceBusSender _serviceBusSender;

    public Home(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
         _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("queue1");
    }

Para obter mais informações, consulte Injeção de dependência com o SDK do Azure para .NET.

Autenticar usando o Microsoft Entra ID

A autenticação baseada em tokens com o Microsoft Entra ID é a abordagem recomendada para autenticar solicitações para serviços do Azure. Para autorizar essas solicitações, o RBAC (controle de acesso baseado em função) do Azure gerencia o acesso aos recursos do Azure com base na identidade do Microsoft Entra e nas funções atribuídas de um usuário.

Use a biblioteca de Identidade do Azure para o suporte de autenticação baseada em token acima mencionado. A biblioteca fornece classes como DefaultAzureCredential simplificar a configuração de conexões seguras. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente. Visite a seção Autenticação dos documentos do SDK do Azure para .NET para obter mais detalhes sobre esses tópicos.

Nota

Muitos serviços do Azure também permitem que você autorize solicitações usando chaves. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor a chave de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações no recurso do Azure associado.

Adicione o pacote Azure.Identity :
```
dotnet add package Azure.Identity
```

Program.cs No arquivo do seu aplicativo, invoque o UseCredential Microsoft.Extensions.Azure método de extensão da biblioteca para definir uma instância compartilhada DefaultAzureCredential para todos os clientes de serviço do Azure registrados:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

DefaultAzureCredential descobre credenciais disponíveis no ambiente atual e as usa para autenticar nos serviços do Azure. Para obter a ordem e os locais em que DefaultAzureCredential as verificações de credenciais, consulte Visão geral de DefaultAzureCredential. O uso de uma instância compartilhada DefaultAzureCredential garante que o cache de token subjacente seja usado, o que melhora a resiliência e o desempenho do aplicativo devido a menos solicitações para um novo token.

Aplicar configurações

Os clientes de serviço do SDK do Azure dão suporte a configurações para alterar seus comportamentos padrão. Há duas maneiras de configurar clientes de serviço:

Os arquivos de configuração JSON geralmente são a abordagem recomendada porque simplificam o gerenciamento de diferenças nas implantações de aplicativos entre ambientes.
As configurações de código embutido podem ser aplicadas quando você registra o cliente de serviço. Por exemplo, na seção Registrar clientes e subclientes , você passou explicitamente as variáveis de URI para os construtores de cliente.

IConfiguration as regras de precedência são respeitadas pelos métodos de Microsoft.Extensions.Azure extensão, que são detalhados na documentação dos Provedores de Configuração .

Conclua as etapas nas seções a seguir para atualizar seu aplicativo para usar a configuração de arquivo JSON para os ambientes apropriados. Use o appsettings.Development.json arquivo para configurações de desenvolvimento e o arquivo para configurações de appsettings.Production.json ambiente de produção. Você pode adicionar definições de configuração cujos nomes são propriedades públicas na ClientOptions classe ao arquivo JSON.

Configurar serviços registrados

Atualize o appsettings.<environment>.json arquivo em seu aplicativo com as configurações de serviço realçadas:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}
```
No exemplo JSON anterior:
- Os nomes de chave de nível superior, KeyVault, ServiceBus, e Storage, são nomes arbitrários usados para fazer referência às seções de configuração do seu código. Você passará esses nomes para métodos de AddClient extensão para configurar um determinado cliente. Todos os outros nomes de chave são mapeados para opções específicas do cliente, e a serialização JSON é executada de maneira que não diferencia maiúsculas de minúsculas.
- Os KeyVault:VaultUrivalores , ServiceBus:Namespace, e Storage:ServiceUri chave são mapeados para os argumentos das sobrecargas , SecretClient(Uri, TokenCredential, SecretClientOptions)ServiceBusClient(String), e BlobServiceClient(Uri, TokenCredential, BlobClientOptions) construtor, respectivamente. As TokenCredential variantes dos construtores são usadas porque um padrão TokenCredential é definido através da chamada de UseCredential(TokenCredential) método.

Atualize o Program.cs arquivo para recuperar as configurações do arquivo JSON usando IConfiguration e passá-las para seus registros de serviço:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

Configurar padrões e novas tentativas do Azure

Talvez você queira alterar as configurações padrão do cliente do Azure globalmente ou para um cliente de serviço específico. Por exemplo, você pode querer configurações de repetição diferentes ou usar uma versão diferente da API de serviço. Você pode definir as configurações de repetição globalmente ou por serviço.

Atualize seu arquivo de configuração para definir as configurações padrão do Azure, como uma nova política de repetição padrão que todos os clientes registrados do Azure usarão:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Program.cs No arquivo, chame o ConfigureDefaults método de extensão para recuperar as configurações padrão e aplicá-las aos seus clientes de serviço:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    // Register a subclient for each Azure Service Bus Queue
    string[] queueNames = [ "queue1", "queue2" ];
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    clientBuilder.UseCredential(new DefaultAzureCredential());

    // Set up any default settings
    clientBuilder.ConfigureDefaults(
        builder.Configuration.GetSection("AzureDefaults"));
});

Configurar registo

O SDK do Azure para bibliotecas de cliente .NET pode registrar operações de biblioteca de cliente para monitorar solicitações e respostas aos serviços do Azure. As bibliotecas de cliente também podem registrar uma variedade de outros eventos, incluindo tentativas, recuperação de token e eventos específicos do serviço de vários clientes. Quando você registra um cliente do SDK do Azure usando o método de AddAzureClients extensão, o AzureEventSourceLogForwarder é registrado com o contêiner de injeção de dependência. O AzureEventSourceLogForwarder encaminha mensagens de log de fontes de eventos do SDK do Azure para ILoggerFactory o permite que você use a configuração padrão de log do ASP.NET Core para log.

A tabela a seguir mostra como o SDK do Azure para .NET EventLevel mapeia para o ASP.NET Core LogLevel. Para obter mais informações sobre esses tópicos e outros cenários, consulte Registro em log com o SDK do Azure para .NET e Injeção de dependência com o SDK do Azure para .NET.

Azure SDK `EventLevel`	ASP.NET Núcleo `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Você pode alterar os níveis de log padrão e outras configurações usando as mesmas configurações JSON descritas na seção configurar autenticação . Por exemplo, alterne o nível de ServiceBusClient log para Debug definindo a Logging:LogLevel:Azure.Messaging.ServiceBus chave da seguinte maneira:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Partilhar via