интеграция очередей хранилища .NET AspireAzure

Статья
12/12/2024

включает в себя: интеграцию хостинга и Client интеграцию

Azure хранилище очередей — это служба для хранения большого количества сообщений, к которым можно обращаться из любой точки мира через прошедшие проверку подлинности вызовы. Интеграция хранилища очередей .NET AspireAzure позволяет подключаться к существующим экземплярам хранилища очередей Azure или создавать новые экземпляры с помощью приложений .NET.

Интеграция хостинга

.NET .NET Aspire Azure интеграция хранилища моделирует различные ресурсы хранения в виде следующих типов:

AzureStorageResource. Представляет ресурс хранилища Azure.
AzureStorageEmulatorResource: представляет ресурс эмулятора хранилища Azure (Azurite).
AzureBlobStorageResource: представляет объект Blob-хранилища Azure.
AzureQueueStorageResource: представляет ресурс хранилища очередей Azure.
AzureTableStorageResource: представляет ресурс хранилища таблиц Azure.

Чтобы получить доступ к этим типам и API для их выражения, добавьте пакет NuGet 📦Aspire.Hosting.Azure.Storage в проект хоста приложения .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в .NET приложениях.

Добавление ресурса хранилища Azure

В проекте узла приложения вызовите AddAzureStorage, чтобы добавить и вернуть построитель ресурсов хранилища Azure.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

// After adding all resources, run the app...

При добавлении AzureStorageResource в хост приложения это предоставляет другие полезные API-интерфейсы для добавления Azure ресурсов хранилища BLOB-объектов, очередей и таблиц. Другими словами, перед добавлением любого из других ресурсов хранилища необходимо добавить AzureStorageResource.

Важный

Когда вызывается AddAzureStorage, он неявно инициирует вызов AddAzureProvisioning, что добавляет поддержку генерации ресурсов Azure динамически при запуске приложения. Приложение должно настроить соответствующую подписку и локацию. Дополнительные сведения см. в разделе Локальная подготовка: конфигурация.

Сгенерированное развертывание Bicep

Если вы не знакомы с Bicep, это предметно-ориентированный язык для описания ресурсов Azure. При использовании .NET.NET Aspire вам нет необходимости вручную писать Bicep, вместо этого API конфигурации создают Bicep за вас. При публикации приложения сгенерированный код Bicep выводится вместе с файлом манифеста. При добавлении ресурса хранения Azure создается следующий Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

Предыдущий Bicep — это модуль, который подготавливает учетную запись хранения Azure со следующими значениями по умолчанию:

kind: тип учетной записи хранения. Значение по умолчанию — StorageV2.
sku: номер SKU учетной записи хранения. Значение по умолчанию — Standard_GRS.
properties: свойства учетной записи хранения:
- accessTier: уровень доступа учетной записи хранилища. Значение по умолчанию — Hot.
- allowSharedKeyAccess: логическое значение, указывающее, разрешает ли учетная запись хранения авторизовать запросы с помощью ключа доступа к учетной записи. Значение по умолчанию — false.
- minimumTlsVersion: минимальная поддерживаемая версия TLS для учетной записи хранения. Значение по умолчанию — TLS1_2.
- networkAcls: Сетевые ACL для учетной записи хранения. Значение по умолчанию — { defaultAction: 'Allow' }.

Помимо учетной записи хранения, также создается контейнер Blob.

В учетную запись хранения добавляются следующие назначения ролей, чтобы предоставить доступ вашему приложению. Для получения дополнительной информации см. встроенные роли управления доступом на основе ролей (Azure RBAC).

Роль или идентификатор	Описание
Вкладчик данных хранилища BLOB `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Чтение, запись и удаление контейнеров и BLOB-объектов хранилища Azure.
Вкладчик данных в таблицу хранилища `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Чтение, запись и удаление таблиц и сущностей хранилища Azure.
Участник управления данными очереди хранилища `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Чтение, запись и удаление очередей хранилища Azure и сообщений очереди.

Созданный файл Bicep является отправной точкой и его можно настроить в соответствии с вашими специфическими требованиями.

Настройка инфраструктуры подготовки

Все .NET AspireAzure ресурсы — это подклассы типа AzureProvisioningResource. Этот тип позволяет настраивать созданный Bicep, предоставляя удобный API для конфигурации ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Например, можно настроить kind, sku, propertiesи многое другое. В следующем примере показано, как настроить ресурс хранилища Azure:

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

Предыдущий код:

Связывает вызов с API ConfigureInfrastructure:
- Параметр infra является экземпляром типа AzureResourceInfrastructure.
- Ресурсы, которые могут быть задействованы, извлекаются через вызов метода GetProvisionableResources().
- Извлекается один StorageAccount.
- StorageAccount.AccessTier назначается StorageAccountAccessTier.Cool.
- StorageAccount.Sku назначается новому StorageSku со значением Name от PremiumZrs.
- Тег добавляется в учетную запись хранения с ключом ExampleKey и значением Example value.

Существует множество дополнительных параметров конфигурации для настройки ресурса хранилища Azure. Дополнительные сведения см. в Azure.Provisioning.Storage.

Подключение к существующей учетной записи хранения Azure

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

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

// After adding all resources, run the app...

Заметка

Строки подключения используются для представления широкого диапазона сведений о подключении, включая подключения к базе данных, брокеры сообщений, URI конечной точки и другие службы. В .NET.NET Aspire номенклатуре термин "строка подключения" используется для представления любой информации о подключении.

Строка подключения настраивается в конфигурации узла приложения, как правило, в разделе Секреты пользователейв разделе ConnectionStrings. Хост приложения встраивает эту строку подключения в качестве переменной среды во все зависимые ресурсы, например:

{
    "ConnectionStrings": {
        "blobs": "https://{account_name}.blob.core.windows.net/"
    }
}

Зависимый ресурс может получить доступ к внедренной строке подключения, вызвав метод GetConnectionString и передав имя подключения в качестве параметра, в этом случае "blobs". API GetConnectionString является сокращением для IConfiguration.GetSection("ConnectionStrings")[name].

Добавление ресурса эмулятора хранилища Azure

Чтобы добавить ресурс эмулятора хранилища Azure, выполните цепочку вызовов IResourceBuilder<AzureStorageResource> в API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator();

// After adding all resources, run the app...

При вызове RunAsEmulatorон настраивает ресурсы хранилища для локального запуска с помощью эмулятора. Эмулятор в этом случае — Azurite. Эмулятор с открытым исходным кодом Azurite предоставляет бесплатную локальную среду для тестирования приложений для хранилищ Blob, Queue и Table, и это идеальный инструмент для интеграции размещения .NET AspireAzure. Azurite не установлен, но доступен в виде контейнера для .NET.NET Aspire. При добавлении контейнера на хост приложения, как показано в предыдущем примере с изображением mcr.microsoft.com/azure-storage/azurite, контейнер создается и запускается при запуске хоста приложения. Дополнительные сведения см. в жизненном цикле ресурсов контейнера .

Настройка контейнера Azurite

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

Настройка портов контейнеров Azurite

По умолчанию контейнер Azurite, когда настроен с помощью .NET.NET Aspire, предоставляет следующие конечные точки:

Конечная точка	Порт контейнера	Порт хоста
`blob`	10 000	динамический
`queue`	10001	динамический
`table`	10002	динамический

По умолчанию прослушиваемый порт является динамическим. При запуске контейнера порты сопоставляются со случайным портом на хост-компьютере. Чтобы настроить порты конечной точки, используйте цепочку вызовов на построителе ресурсов контейнера, предоставленном методом RunAsEmulator, как показано в следующем примере:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(27002);
                     });

// After adding all resources, run the app...

Приведенный выше код настраивает существующие конечные точки контейнера Azurite: blob, queueи table, для прослушивания портов 27000, 27001и 27002соответственно. Порты контейнера Azurite сопоставляются с портами узла, как показано в следующей таблице:

Имя конечной точки	Сопоставление портов (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Настройка контейнера Azurite с постоянным временем существования

Чтобы настроить контейнер Azurite с постоянным временем существования, вызовите метод WithLifetime в ресурсе контейнера Azurite и передайте ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

Для получения дополнительной информации см. время существования ресурса контейнера.

Настройка контейнера Azurite с объемом данных

Чтобы добавить том данных в ресурс эмулятора хранилища Azure, вызовите метод WithDataVolume в ресурсе эмулятора хранилища Azure:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataVolume();
                     });

// After adding all resources, run the app...

Том данных используется для сохранения данных Azurite за пределами жизненного цикла контейнера. Том данных монтируется по пути /data в контейнере Azurite; если параметр name не предоставлен, имя форматируется как .azurite/{resource name}. Дополнительную информацию о томах данных и подробности о том, почему они предпочтительнее маунтов , можно найти в документации : Томы.

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

Чтобы добавить привязку данных к ресурсу эмулятора хранилища Azure, вызовите метод WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataBindMount("../Azurite/Data");
                     });

// After adding all resources, run the app...

Важный

Привязки данных имеют ограниченную функциональность по сравнению с томами, которые обеспечивают более высокую производительность, портативность и безопасность, что делает их более подходящими для производственных сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, идеально подходит для разработки и тестирования, в которых требуются изменения в режиме реального времени.

Привязка данных типа 'mount' зависит от файловой системы хост-компьютера для сохранения данных Azurite при перезапуске контейнера. Точка монтирования данных расположена по пути ../Azurite/Data на хост-машине относительно каталога хоста приложения (IDistributedApplicationBuilder.AppHostDirectory) в контейнере Azurite. Дополнительные сведения о подключениях привязки данных см. в документации по Docker: привязка подключений.

Подключение к ресурсам хранилища

При запуске узла приложения .NET.NET Aspire доступ к ресурсам хранилища можно получить внешними средствами, такими как обозреватель хранилища Azure. Если ресурс хранилища выполняется локально с помощью Azurite, он автоматически будет обнаружен в Обозревателе Хранилища Azure.

Заметка

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

Чтобы подключиться к ресурсу хранилища из Storage Explorer Azure, выполните следующие действия.

Запустите хост приложения .NET.NET Aspire.
Откройте обозреватель хранилища Azure.
Просмотрите область обозревателя.
Выберите ссылку Обновить все, чтобы обновить список учетных записей хранения.
Разверните узел подключенного эмулятора &.
Разверните узел учетных записей хранения.
Вы должны увидеть учетную запись хранения с именем ресурса в качестве префикса:

Вы можете свободно изучать учетную запись хранения и её содержимое с помощью Azure Storage Explorer. Дополнительные сведения об использовании обозревателя службы хранилища Azure см. в разделе «Начало работы с обозревателем хранилища» .

Добавить ресурс хранилища очередей Azure

В вашем проекте хоста приложения зарегистрируйте интеграцию хранилища очередей Azure, осуществив цепочку вызова AddQueues на экземпляре IResourceBuilder<IAzureStorageResource>, который возвращается AddAzureStorage. В следующем примере показано, как добавить ресурс хранилища очередей Azure с именем storage и ресурс очереди с именем queues:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

// After adding all resources, run the app...

Предыдущий код:

Добавляет ресурс хранилища Azure с именем storage.
Добавляет очередь с именем queues в ресурс хранилища.
Добавляет ресурс storage в ExampleProject и ожидает его готовности перед запуском проекта.

Проверка работоспособности интеграции хостинга

Интеграция хостинга хранилища Azure автоматически добавляет проверку работоспособности ресурса хранилища. Он добавляется только при запуске в качестве эмулятора и проверяет, запущен ли контейнер Azurite и что к нему можно установить подключение. Интеграция хостинга зависит от пакета NuGet 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs.

интеграция Client

Чтобы приступить к интеграции клиента хранилища очередей .NET AspireAzure, установите пакет NuGet 📦Aspire.Azure.Storage.Queues в проект, использующий клиент, то есть в проект приложения, который использует клиент хранилища очередей Azure. Интеграция клиента хранилища очередей Azure регистрирует экземпляр QueueServiceClient, который можно использовать для взаимодействия с хранилищем очередей Azure.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

<PackageReference Include="Aspire.Azure.Storage.Queues"
                  Version="*" />

Добавление клиента хранилища очередей Azure

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения AddAzureQueueClient для любой IHostApplicationBuilder, чтобы зарегистрировать QueueServiceClient для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

builder.AddAzureQueueClient("queue");

Затем можно получить экземпляр QueueServiceClient с помощью внедрения зависимостей. Например, чтобы извлечь клиента из службы.

public class ExampleService(QueueServiceClient client)
{
    // Use client...
}

Конфигурация

Интеграция хранилища очередей .NET AspireAzure предоставляет множество опций для настройки QueueServiceClient в соответствии с требованиями и соглашениями вашего проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

Затем строка подключения извлекается из раздела конфигурации ConnectionStrings и поддерживаются два формата подключения:

URI службы

Рекомендуемый подход — использовать ServiceUri, которая работает со свойством AzureStorageQueuesSettings.Credential для установления подключения. Если учетные данные не настроены, используется Azure.Identity.DefaultAzureCredential.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}

Строка подключения

Кроме того, можно использовать строку подключения к хранилищу .

{
  "ConnectionStrings": {
    "queue": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

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

Использование поставщиков конфигураций

Интеграция .NET AspireAzure с хранилищем очередей поддерживает Microsoft.Extensions.Configuration. Он загружает AzureStorageQueuesSettings и QueueClientOptions из конфигурации, используя ключ Aspire:Azure:Storage:Queues. Следующий фрагмент кода является примером файла appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Полной схемы интеграции клиента Azure Storage QueuesJSON см. в Aspire.Azure. Data.Queues/ConfigurationSchema.json.

Использование встроенных делегатов

Можно также передать делегат Action<AzureStorageQueuesSettings> configureSettings для настройки некоторых или всех встроенных параметров, например для настройки проверок работоспособности:

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

Вы также можете настроить QueueClientOptions с помощью делегата Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, второго параметра метода AddAzureQueueClient. Например, чтобы задать первую часть заголовков User-Agent для всех запросов, выполняемых этим клиентом:

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client проверка состояния интеграции

Интеграции .NET.NET Aspire по умолчанию включают проверки состояния для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

Интеграция с хранилищем очередей .NET AspireAzure:

Добавляет проверку работоспособности, когда AzureStorageQueuesSettings.DisableHealthChecks это false, которая пытается подключиться к хранилищу очередей Azure.
Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки состояния должны успешно выполняться, чтобы приложение считалось готовым принять трафик.

Наблюдаемость и телеметрия

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

Лесозаготовка

Интеграция хранилища очередей .NET AspireAzure использует следующие категории журналов:

Azure.Core
Azure.Identity

Отслеживание

Интеграция с хранилищем очередей .NET AspireAzure создает следующие действия трассировки с использованием OpenTelemetry.

Azure.Storage.Queues.QueueClient

Метрика

Интеграция .NET AspireAzure для хранилища очередей в настоящее время не поддерживает метрики по умолчанию из-за ограничений SDK Azure.

См. также

Azure Документация по хранилищу очередей
интеграции .NET.NET Aspire
.NET Aspire GitHub репо

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