интеграция очередей хранилища .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:

Переключение Azure хранилище Bicep.

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

param principalId string

param principalType 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) Azure.

Роль или идентификатор	Описание
Участник данных 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 со значением NamePremiumZrs.
- Тег добавляется в учетную запись хранения с ключом 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 предоставляет бесплатную локальную среду для тестирования приложений Azure BLOB-объектов, хранилища очередей и хранилища таблиц, и это идеальный компаньон интеграции размещения .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("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 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}. Дополнительные сведения о томах данных и о том, почему они предпочтительнее, чем привязки , см. в документации Docker о томах.

Настройка контейнера 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...

Важный

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

Подключения привязки данных зависят от файловой системы хост-компьютера, чтобы сохранить данные 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 хранилища очередей client, установите пакет NuGet 📦Aspire.Azure.Storage.Queues в проект, использующий client, то есть проект для приложения, которое использует Azure хранилище очередей client. Интеграция Azure хранилища очередей client регистрирует экземпляр QueueServiceClient, который можно использовать для взаимодействия с хранилищем очередей Azure.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

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

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

builder.AddAzureQueueClient("queue");

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

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 QueuesclientJSON см. в Aspire.Azure. Data.Queues/ConfigurationSchema.json.

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

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

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

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

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

Client контроль состояния интеграции

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

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

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

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

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

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

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

Azure.Core
Azure.Identity

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

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

Azure.Storage.Queues.QueueClient

Метрика

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

См. также

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

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