Partilhar via

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

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 de aplicações web, como logs e repetições.

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 para construir clientes do SDK do TokenCredential Azure que oferecem 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 na coleção de serviços de 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:

  1. Adicione o pacote Microsoft.Extensions.Azure :

    dotnet add package Microsoft.Extensions.Azure

  2. 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

  3. No ficheiro Program.cs do seu aplicativo, invoque o método de extensão AddAzureClients da biblioteca Microsoft.Extensions.Azure para registar um cliente que comunique 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 tais subclientes para injeção de dependência via o método de extensão AddClient.

    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);
    }
});

var app = builder.Build();

  4. Injete os clientes registados nos componentes, serviços ou endpoints da sua aplicação ASP.NET Core.

    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");

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 disponibiliza classes, como o DefaultAzureCredential, para 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.

  1. Adicione o pacote Azure.Identity :

    dotnet add package Azure.Identity

  2. No ficheiro da sua aplicação Program.cs, invoque o método de extensão AddAzureClients da biblioteca Microsoft.Extensions.Azure para definir uma instância compartilhada DefaultAzureCredential para todos os clientes de serviço registados do Azure.

    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);
    }
});

var app = builder.Build();

    DefaultAzureCredential descobre credenciais disponíveis no ambiente atual e as usa para autenticar nos serviços do Azure. Para a ordem e os locais em que DefaultAzureCredential procura credenciais, consulte a Visão geral do 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 extensão Microsoft.Extensions.Azure, que são detalhados na documentação dos fornecedores 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 appsettings.Development.json para configurações de desenvolvimento e o arquivo appsettings.Production.json 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

  1. Atualize o arquivo appsettings.<environment>.json na sua aplicação 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 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 valores-chave KeyVault:VaultUri, ServiceBus:Namespace e Storage:ServiceUri são mapeados para os argumentos das sobrecargas do construtor SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String) e BlobServiceClient(Uri, TokenCredential, BlobClientOptions), respectivamente.

  2. 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 predefinições e repetições 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.

  1. 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"
  }
}

  2. No arquivo Program.cs, chame o método de extensão ConfigureDefaults 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);
    }

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

var app = builder.Build();

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 registar uma variedade de outros eventos, incluindo reaquisições, recuperação de token e eventos específicos do serviço de diferentes clientes. Quando registras um cliente do SDK do Azure utilizando o método de extensão AddAzureClients, o AzureEventSourceLogForwarder é registado no contentor de injeção de dependência. O AzureEventSourceLogForwarder encaminha mensagens de log de fontes de eventos do SDK do Azure para ILoggerFactory, permitindo-lhe usar a configuração padrão de registo do ASP.NET Core.

A tabela abaixo demonstra como o SDK do Azure para .NET EventLevel se integra com o ASP.NET Core LogLevel. Para obter mais informações sobre esses tópicos e outros cenários, consulte Registo de logs com o SDK do Azure para .NET e Injeção de dependências 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"
  }
}
  • Last updated on