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

Статья
14.12.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

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

dotnet add package Aspire.Hosting.Azure.Storage

XML

<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 для добавления ресурсов хранилища BLOB-объектов, очередей и таблиц. Другими словами, перед добавлением любого из других ресурсов хранилища необходимо добавить AzureStorageResource.

Важно!

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

Созданное ресурсное обеспечение Bicep

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

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' }.

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

В учетную запись хранения добавляются следующие назначения ролей, чтобы предоставить вашему приложению доступ. Дополнительные сведения см. о встроенных ролях управления доступом на основе ролей 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. Хост приложения внедряет эту строку подключения в качестве переменной среды во все зависимые ресурсы, например:

JSON

{
    "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(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(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 за пределами жизненного цикла контейнера. В контейнере Azurite том данных монтируется по пути /data, а если параметр 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, установите пакет NuGet 📦Aspire.Azure.Data.Tables в проекте, использующем клиента, то есть в проекте приложения, использующего клиента таблицы данных Azure. Интеграция клиента таблиц данных Azure регистрирует экземпляр TableServiceClient, который можно использовать для взаимодействия с Azure Table Storage.

.NET CLI
PackageReference

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

dotnet add package Aspire.Azure.Data.Tables

XML

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

Добавьте клиента Azure Table Storage

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

builder.AddAzureTableClient("tables");

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

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, который настраивает некоторые параметры:

JSON

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

Для полной схемы клиентской интеграции с таблицами данных AzureJSON см. в разделе 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 для идентификации клиента:

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.

См. также

Совместная работа с нами на GitHub

Источник этого содержимого можно найти на GitHub, где также можно создавать и просматривать проблемы и запросы на вытягивание. Дополнительные сведения см. в нашем руководстве для участников.

Отзыв о .NET Aspire

.NET Aspire — это проект с открытым исходным кодом. Выберите ссылку, чтобы оставить отзыв:

Открыть проблему с документацией Отзыв о продукте

Дополнительные ресурсы

Документация

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

Узнайте, как использовать интеграцию .NET AspireAzure Blob Storage, которая включает как хостинг, так и интеграцию с клиентами.
интеграция хранилища очереди .NET AspireAzure - .NET Aspire

В этой статье описываются функции и возможности интеграции хранилища очередей .NET AspireAzure.
Подключение приложения ASP.NET Core к интеграции с хранилищем .NET Aspire - .NET Aspire

Узнайте, как подключить приложение ASP.NET Core к интеграции хранилища .NET Aspire.
интеграция функций .NET AspireAzure (предварительная версия) - .NET Aspire

Узнайте, как интегрировать функции Azure с .NET Aspire.
интеграция .NET AspireAzure Web PubSub - .NET Aspire

В этой статье описываются функции и возможности интеграции .NET AspireAzure Web PubSub.
Локальная настройка Azure - .NET Aspire

Узнайте, как использовать Azure ресурсы в локальной среде разработки.
Обзор интеграций Azure - .NET Aspire

Обзор интеграций Azure, доступных в .NET Aspire.
.NET Aspire Azure Event Hubs интеграция - .NET Aspire

В этой статье описываются функции и возможности интеграции .NET AspireиAzure Event Hubs.

Обучение

Схема обучения

Use advance techniques in canvas apps to perform custom updates and optimization - Training

Use advance techniques in canvas apps to perform custom updates and optimization

Сертификация

Сертификация Майкрософт: специальность "Разработчик Azure Cosmos DB" - Certifications

Создавайте эффективные запросы, создавайте политики индексирования, управляйте и подготавливайте ресурсы в API SQL и пакете SDK с помощью Microsoft Azure Cosmos DB.

AI Skills Fest

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