интеграция таблиц данных .NET AspireAzure

Статья
12/14/2024

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

Azure Table Storage — это служба для хранения структурированных данных NoSQL. Интеграция таблиц данных .NET AspireAzure позволяет подключаться к существующим экземплярам Azure Table Storage или создавать новые экземпляры из .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' }.

Помимо учетной записи хранения, также создается контейнер блоб-объектов.

В учетную запись хранения добавляются следующие назначения ролей, чтобы предоставить вашему приложению доступ. Дополнительные сведения см. о встроенных ролях управления доступом на основе ролей Azure (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 предоставляет бесплатную локальную среду для тестирования приложений Azure Blob, хранилища очередей и хранилища таблиц и является идеальным компаньоном для интеграции размещения .NET AspireAzure. Azurite не установлен, вместо этого он доступен для .NET.NET Aspire в качестве контейнера. При добавлении контейнера в хост приложения, как показано в предыдущем примере с изображением mcr.microsoft.com/azure-storage/azurite, хост приложения создает и запускает контейнер при запуске. Для получения дополнительной информации см. жизненный цикл ресурса контейнера.

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

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

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

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

Конечная точка	Порт контейнера	Порт хоста
`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.
Просмотрите область обозревателя .
Выберите ссылку Обновить все, чтобы обновить список учетных записей хранения.
Разверните узел с подключенным эмулятором &.
Разверните узел учетных записей хранения .
Вы должны увидеть учетную запись хранения с именем ресурса в качестве префикса:

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

Добавление ресурса Azure Table Storage

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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

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

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

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

интеграция Client

Чтобы приступить к работе с .NET AspireAzure таблицами данных client интеграции, установите 📦Aspire.Azure. Data.Tables пакет NuGet в client-потребляющем проекте, то есть проект для приложения, использующего Azure таблицы данных client. Интеграция таблиц данных Azureclient регистрирует экземпляр TableServiceClient, который можно использовать для взаимодействия с Azure Table Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

Добавьте Azure Table Storageclient

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

builder.AddAzureTableClient("tables");

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

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

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

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

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

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

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

Полные Azure таблицы данных client схеме интеграции JSON см. в Aspire.Azure. Data.Tables/ConfigurationSchema.json.

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

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

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

Вы также можете настроить TableClientOptions с помощью делегата Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, второго параметра метода AddAzureTableClient. Например, чтобы установить идентификатор TableServiceClient для client:

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

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

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

Интеграция таблиц данных .NET AspireAzure:

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

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

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

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

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

Azure.Core
Azure.Identity

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

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

Azure.Data.Tables.TableServiceClient

Метрика

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

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