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. Você aprenderá a:

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

Explorar 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:

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 registro em log, lidar com tempos de vida do serviço de DI e gerenciamento de credenciais de autenticação.
Azure.Identity habilita o suporte à autenticação de ID do Microsoft Entra no SDK do Azure. Ele fornece um conjunto de implementações TokenCredential para construir clientes do SDK do Azure que dão suporte à autenticação do 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 de DI

As bibliotecas de clientes 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 Azure Key Vault. Registre esses serviços com o contêiner de dependência no arquivo do Program.cs seu aplicativo para disponibilizá-los por meio da injeção de dependência.

Conclua as etapas a seguir para registrar os serviços necessários:

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 clientes 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 por meio 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 de aplicativo ASP.NET Core, 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.

Autenticação usando o Microsoft Entra ID

A autenticação baseada em token com a ID do Microsoft Entra é 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 de um usuário e nas funções atribuídas.

Use a biblioteca de Identidades do Azure para obter o suporte à autenticação baseada em token mencionado acima. A biblioteca fornece classes para DefaultAzureCredential simplificar a configuração de conexões seguras. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação 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.

Observação

Muitos serviços do Azure também permitem que você autorize solicitações usando chaves. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor as chaves 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 método de extensão da Microsoft.Extensions.Azure 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 as credenciais disponíveis no ambiente atual e as usa para autenticar nos serviços do Azure. Para obter a ordem e os locais nos quais 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 de 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 em linha 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 do 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 arquivo para configurações de appsettings.Development.json desenvolvimento e o appsettings.Production.json arquivo para configurações de 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 destacadas:
```
{
  "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 AddClient métodos de 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 key são mapeados para os argumentos das sobrecargas , SecretClient(Uri, TokenCredential, SecretClientOptions)ServiceBusClient(String), e BlobServiceClient(Uri, TokenCredential, BlobClientOptions) do construtor, respectivamente. As variantes TokenCredential dos construtores são usadas porque um padrão TokenCredential é definido por meio da chamada do método UseCredential(TokenCredential).

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, talvez você queira usar configurações de repetição diferentes ou usar uma versão de API de serviço diferente. 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 o registro em log

As bibliotecas de clientes do SDK do Azure para .NET podem registrar operações de biblioteca de clientes 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 novas tentativas, recuperação de token e eventos específicos de serviço de vários clientes. Quando você registra um cliente do SDK do Azure usando o AddAzureClients método de 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 para permite que você use a configuração de log padrão do ASP.NET Core para registro em log.

A tabela a seguir descreve como o SDK do Azure para .NET EventLevel mapeia para o ASP.NET CoreLogLevel. 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.

SDK do Azure `EventLevel`	ASP.NET Core `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 de configuração de 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"
  }
}

Compartilhar via