Использование пакета SDK Azure для .NET в приложениях ASP.NET Core

Статья
11/16/2024

Пакет SDK Azure для .NET позволяет ASP.NET приложения Core интегрироваться с различными службами Azure. В этой статье вы узнаете о рекомендациях и шагах по внедрению пакета SDK Azure для .NET в приложениях ASP.NET Core. Вы изучите следующие темы:

Зарегистрируйте службы для внедрения зависимостей.
Проверка подлинности в Azure без использования паролей или секретов.
Реализуйте централизованную стандартизованную конфигурацию.
Настройте распространенные проблемы веб-приложения, такие как ведение журнала и повторные попытки.

Знакомство с общими клиентскими библиотеками Azure SDK

ASP.NET Основные приложения, которые подключаются к службам Azure, обычно зависят от следующих клиентских библиотек Azure SDK:

Microsoft.Extensions.Azure предоставляет вспомогательные методы для регистрации клиентов в коллекции служб внедрения зависимостей и обработки различных проблем, таких как настройка ведения журнала, обработка времени существования службы DI и управление учетными данными проверки подлинности.
Azure.Identity обеспечивает поддержку проверки подлинности идентификатора Microsoft Entra в пакете SDK Azure. Он предоставляет набор реализаций TokenCredential для создания клиентов пакета SDK Azure, поддерживающих проверку подлинности Microsoft Entra.
Azure.<service-namespace> библиотеки, такие как Azure.Storage.Blobs и Azure.Messaging.ServiceBus, предоставляют клиенты служб и другие типы, помогающие подключаться к определенным службам Azure и использовать их. Полный список этих библиотек см. в разделе "Библиотеки" с помощью Azure.Core.

В следующих разделах вы узнаете, как реализовать приложение ASP.NET Core, использующее эти библиотеки.

Регистрация клиентов Azure SDK в коллекции служб DI

Клиентские библиотеки Azure SDK для .NET предоставляют клиентам службы подключение приложения к службам Azure, таким как Хранилище BLOB-объектов Azure и Azure Key Vault. Зарегистрируйте эти службы в контейнере зависимостей в Program.cs файле приложения, чтобы сделать их доступными с помощью внедрения зависимостей.

Выполните следующие действия, чтобы зарегистрировать необходимые службы:

Добавьте пакет Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```

Добавьте соответствующие Azure.* пакеты клиента службы:

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

Program.cs В файле приложения вызовите AddAzureClients метод расширения из Microsoft.Extensions.Azure библиотеки, чтобы зарегистрировать клиент для взаимодействия с каждой службой Azure. Некоторые клиентские библиотеки предоставляют дополнительные подклиенты для определенных подгрупп функций службы Azure. Вы можете зарегистрировать такие подклиенты для внедрения зависимостей с помощью 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);
    }

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

Вставьте зарегистрированные клиенты в компоненты приложения ASP.NET Core, службы или конечную точку API:

Минимальный API
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");
    }

Дополнительные сведения см. в статье об внедрении зависимостей с помощью пакета SDK Azure для .NET.

Проверка подлинности с помощью идентификатора Microsoft Entra

Проверка подлинности на основе маркеров с помощью идентификатора Microsoft Entra — это рекомендуемый подход для проверки подлинности запросов к службам Azure. Чтобы авторизовать эти запросы, управление доступом на основе ролей Azure (RBAC) управляет доступом к ресурсам Azure на основе удостоверения Microsoft Entra пользователя и назначенных ролей.

Используйте библиотеку удостоверений Azure для поддержки проверки подлинности на основе токенов. Библиотека предоставляет классы, такие как DefaultAzureCredential упрощение настройки безопасных подключений. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды. Дополнительные сведения об этих разделах см. в разделе "Проверка подлинности " пакета SDK Azure для .NET.

Примечание.

Многие службы Azure также позволяют авторизовать запросы с помощью ключей. Однако этот подход следует использовать с осторожностью. Разработчики должны тщательно следить за тем, чтобы не раскрыть ключи доступа в незащищенном расположении. Любой пользователь, имеющий ключ доступа, может авторизовать запросы к связанному ресурсу Azure.

Добавьте пакет Azure.Identity:
```
dotnet add package Azure.Identity
```
Program.cs В файле приложения вызовите UseCredential метод расширения из Microsoft.Extensions.Azure библиотеки, чтобы задать общий DefaultAzureCredential экземпляр для всех зарегистрированных клиентов службы 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);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});
```
DefaultAzureCredential обнаруживает доступные учетные данные в текущей среде и использует их для проверки подлинности в службах Azure. Порядок и расположения, в которых DefaultAzureCredential выполняется проверка учетных данных, см. в обзоре DefaultAzureCredential. Использование общего DefaultAzureCredential экземпляра гарантирует использование базового кэша маркеров, что повышает устойчивость приложений и производительность из-за меньшего количества запросов на новый маркер.

Применение конфигураций

Клиенты службы SDK Azure поддерживают конфигурации для изменения поведения по умолчанию. Существует два способа настройки клиентов служб.

Файлы конфигурации JSON обычно являются рекомендуемыми способами, так как они упрощают управление различиями в развертываниях приложений между средами.
Встроенные конфигурации кода можно применять при регистрации клиента службы. Например, в разделе Register client and subclients вы явно передали переменные URI конструкторам клиента.

IConfiguration Правила приоритета соблюдаются Microsoft.Extensions.Azure методами расширения, которые подробно описаны в документации по поставщикам конфигурации.

Выполните действия, описанные в следующих разделах, чтобы обновить приложение, чтобы использовать конфигурацию JSON-файла для соответствующих сред. appsettings.Development.json Используйте файл для параметров разработки и appsettings.Production.json файла для параметров рабочей среды. Вы можете добавить параметры конфигурации, имена которых являются общедоступными свойствами класса в ClientOptions JSON-файл.

Настройка зарегистрированных служб

appsettings.<environment>.json Обновите файл в приложении с выделенными конфигурациями службы:
```
{
  "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"
  }
}
```
В предыдущем примере JSON:
- Имена ключей верхнего уровня, KeyVaultServiceBusа также Storageпроизвольные имена используются для ссылки на разделы конфигурации из кода. Эти имена AddClient передаются методам расширения для настройки заданного клиента. Все остальные имена ключей сопоставляются с определенными параметрами клиента, а сериализация JSON выполняется без учета регистра.
- Значения KeyVault:VaultUriключей ServiceBus:Namespaceи Storage:ServiceUri параметров сопоставляют аргументы перегрузки конструктора SecretClient(Uri, TokenCredential, SecretClientOptions)и BlobServiceClient(Uri, TokenCredential, BlobClientOptions) аргументов ServiceBusClient(String)соответственно. Варианты TokenCredential конструкторов используются, так как значение по умолчанию TokenCredential устанавливается с помощью UseCredential(TokenCredential) вызова метода.

Program.cs Обновите файл, чтобы получить конфигурации ФАЙЛОВ JSON с помощью IConfiguration и передать их в регистрации службы:

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

Настройка значений по умолчанию и повторных попыток Azure

Возможно, вы хотите изменить конфигурации клиентов Azure по умолчанию глобально или для конкретного клиента службы. Например, могут потребоваться разные параметры повторных попыток или использовать другую версию API службы. Вы можете задавать параметры повтора глобально или же отдельно для каждой службы.

Обновите файл конфигурации, чтобы задать параметры Azure по умолчанию, например новую политику повторных попыток по умолчанию, которую будут использовать все зарегистрированные клиенты Azure:

{
  "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 В файле вызовите ConfigureDefaults метод расширения, чтобы получить параметры по умолчанию и применить их к клиентам службы:

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

Настройка журнала

Клиентские библиотеки Пакета SDK Azure для .NET могут регистрировать операции клиентской библиотеки для отслеживания запросов и ответов на службы Azure. Клиентские библиотеки также могут регистрировать различные другие события, включая повторные попытки, извлечение маркеров и события, относящиеся к службе, от различных клиентов. При регистрации клиента Пакета SDK Azure с помощью AddAzureClients метода AzureEventSourceLogForwarder расширения регистрируется в контейнере внедрения зависимостей. Пересылает AzureEventSourceLogForwarder сообщения журнала из источников событий Azure SDK, чтобы ILoggerFactory позволить использовать стандартную конфигурацию ведения журнала ASP.NET Core для ведения журнала.

В следующей таблице показано, как пакет Azure SDK для .NET EventLevel сопоставляется с ASP.NET Core LogLevel. Дополнительные сведения об этих разделах и других сценариях см. в статье "Ведение журнала с помощью пакета SDK Azure для .NET" и внедрения зависимостей с помощью пакета SDK Azure для .NET.

Пакет SDK Azure `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Вы можете изменить уровни журналов по умолчанию и другие параметры, используя те же конфигурации JSON, описанные в разделе настройки проверки подлинности . Например, переключите ServiceBusClient уровень Debug журнала, Logging:LogLevel:Azure.Messaging.ServiceBus задав ключ следующим образом:

{
  "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"
  }
}

Поделиться через