интеграция .NET AspireAzure Blob Storage

Статья
12/15/2024

Включает:интеграция размещения и Client интеграции

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

Хостинг-интеграция

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

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

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

.NET Интерфейс командной строки
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).

Роль или идентификатор	Описание
Вкладчик данных блоб-объектов хранилища `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 предоставляет бесплатную локальную среду для тестирования ваших приложений 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...

Приведенный выше код настраивает существующие конечные точки blob, queueи table контейнера Azurite для прослушивания на портах 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 для подключения к правильным портам.

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

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

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

Добавить ресурс Azure Blob Storage

В проекте узла приложения зарегистрируйте интеграцию Azure Blob Storage путем цепочки вызова AddBlobs в экземпляре IResourceBuilder<IAzureStorageResource>, возвращенном AddAzureStorage. В следующем примере показано, как добавить ресурс Azure Blob Storage с именем storage и контейнер BLOB-объектов с именем blobs:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(blobs)
       .WaitFor(blobs);

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

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

Добавляет ресурс хранилища Azure с именем storage.
Вызывает вызов RunAsEmulator, чтобы настроить ресурс хранилища для локального запуска с помощью эмулятора. Эмулятор в этом случае Azurite.
Добавляет контейнер BLOB-объектов с именем blobs в ресурс хранилища.
Добавляет ресурс blobs в ExampleProject и ожидает его готовности перед запуском проекта.

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

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

интеграция Client

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

.NET Интерфейс командной строки
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

Добавьте Azure Blob Storageclient

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

builder.AddAzureBlobClient("blobs");

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

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

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

Интеграция .NET AspireAzure Blob Storage предоставляет несколько вариантов настройки BlobServiceClient на основе требований и соглашений проекта.

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

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

builder.AddAzureBlobClient("blobs");

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

URI службы

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

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

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

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

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

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

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

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

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

Полную схему интеграции Azure Blob StorageclientJSON см. Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

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

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

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

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

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

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

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

Интеграция .NET AspireAzure Blob Storage:

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

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

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

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

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

Azure.Core
Azure.Identity

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

Интеграция .NET AspireAzure Blob Storage испускает следующие активности трассировки с помощью OpenTelemetry:

Azure.Storage.Blobs.BlobContainerClient

Метрика

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

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