Использование пакета 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 ID — это рекомендуемый подход для проверки подлинности запросов к службам 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:
- Имена ключей верхнего уровня, KeyVault, ServiceBus, а также Storage, являются произвольными и используются для ссылки на разделы конфигурации из вашего кода. Вы передадите эти имена методам расширения AddClient для настройки данного клиента. Все другие имена ключей сопоставляются с конкретными параметрами клиента, причем сериализация JSON выполняется без учета регистра.
- Значения KeyVault:VaultUri, ServiceBus:Namespace и Storage:ServiceUri ключей сопоставляются с аргументами перегрузок конструктора SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String) и BlobServiceClient(Uri, TokenCredential, BlobClientOptions) соответственно. Варианты 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. Клиентские библиотеки также могут регистрировать различные другие события, включая повторные попытки, получение токенов и события, специфичные для различных служб. При регистрации клиента Azure SDK с помощью метода расширения AddAzureClients, 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"
  }
}

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