Общие сведения об интеграции .NET AspireAzure

Статья
12/17/2024

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

Добавление подключения к существующим ресурсам Azure

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

Заметка

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

Рассмотрим следующий пример: в режиме публикации вы добавляете ресурс хранилища Azure, а в режиме выполнения вы добавляете строку подключения к существующему хранилищу Azure.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

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

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

Создает новый экземпляр builder.
Добавляет ресурс хранилища Azure с именем storage в режиме публикации.
Добавляет строку подключения к существующему хранилищу Azure с именем storage в режиме выполнения.
Добавляет проект с именем api в сборщик.
Проект api ссылается на ресурс storage независимо от режима.

В проекте API для потребления используется информация о строке подключения без информации о том, как она была настроена хостом приложения. В режиме публикации код добавляет новый ресурс хранилища , который будет отражен в манифесте развертывания соответствующим образом. При использовании режима запуска строка подключения соответствует значению конфигурации, видимому узлу приложения. Предполагается, что все назначения ролей для целевого ресурса настроены. Это означает, что вы, скорее всего, настроите переменную среды или секрет пользователя для хранения строки подключения. Конфигурация определяется с помощью ключа конфигурации ConnectionStrings__storage (или ConnectionStrings:storage). Эти значения конфигурации можно просмотреть при запуске приложения. Для получения дополнительной информации см. сведения о ресурсе.

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

Все .NET AspireAzure интеграции размещения делают доступными Azure ресурсы и по общепринятому соглашению добавляются с помощью AddAzure* API. При добавлении данных ресурсов в хост приложения .NET Aspire, они выступают в качестве службы Azure. API AddAzure* возвращает IResourceBuilder<T>, где T является типом ресурса Azure. Эти интерфейсы IResourceBuilder<T> (построителя) предоставляют простой API, который позволяет настроить базовый ресурс Azure в модели приложений.

Типичный интерфейс разработчика

Если узел приложения .NET Aspire содержит Azure ресурсы, и вы запускаете его локально (опыт типичного разработчика F5 или dotnet run), Azure ресурсы подготавливаются в подписке Azure. Это позволяет разработчику отлаживать их локально в контексте узла приложения.

.NET .NET Aspire стремится свести к минимуму затраты, используя по умолчанию базовую или стандартнуюединицу складского учета (SKU) для своих интеграций Azure. Хотя эти разумные значения по умолчанию предоставляются, вы можете настроить ресурсы Azure в соответствии с вашими потребностями. Кроме того, некоторые интеграции поддерживают эмуляторы или контейнеров, которые полезны для локальной разработки, тестирования и отладки. По умолчанию при локальном запуске приложения ресурсы Azure используют фактическую службу Azure. Однако их можно настроить для использования локальных эмуляторов или контейнеров, избегая затрат, связанных с фактической службой Azure во время локальной разработки.

Локальные эмуляторы

Некоторые службы Azure могут выполняться локально в эмуляторах. В настоящее время .NET Aspire поддерживает следующие эмуляторы Azure:

Интеграция хостинга	Описание
Azure Cosmos DB	Вызовите AzureCosmosExtensions.RunAsEmulator в `IResourceBuilder<AzureCosmosDBResource>`, чтобы настроить ресурс Cosmos DB для эмуляции с помощьюAPI NoSQL.
Azure Event Hubs	Вызовите AzureEventHubsExtensions.RunAsEmulator в `IResourceBuilder<AzureEventHubsResource>`, чтобы настроить ресурс Центров событий для эмуляции.
Azure хранилище	Вызовите AzureStorageExtensions.RunAsEmulator на `IResourceBuilder<AzureStorageResource>`, чтобы настроить ресурс хранилища для того, чтобы он был эмулирован с помощью Azurite.

Чтобы ресурсы Azure использовали локальные эмуляторы, выполните цепочку вызова метода RunAsEmulator в построителе ресурсов Azure. Этот метод настраивает ресурс Azure для использования локального эмулятора вместо фактической службы Azure.

Важный

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

Локальные контейнеры

Некоторые службы Azure могут выполняться локально в контейнерах. Чтобы запустить службу Azure локально в контейнере, последовательно вызовите метод RunAsContainer в построителе ресурсов Azure. Этот метод настраивает ресурс Azure для локального выполнения в контейнере вместо фактической службы Azure.

В настоящее время .NET Aspire поддерживает следующие службы Azure в виде контейнеров:

Интеграция хостинга	Подробности
Azure Cache for Redis	Вызовите AzureRedisExtensions.RunAsContainer на `IResourceBuilder<AzureRedisCacheResource>`, чтобы настроить его для работы локально в контейнере на основе образа `docker.io/library/redis`.
Azure PostgreSQL гибкие Server	Вызовите AzurePostgresExtensions.RunAsContainer на `IResourceBuilder<AzurePostgresFlexibleServerResource>`, чтобы настроить его для работы локально в контейнере на основе образа `docker.io/library/postgres`.
Azure SQL Server	Вызовите AzureSqlExtensions.RunAsContainer на `IResourceBuilder<AzureSqlServerResource>`, чтобы настроить его для работы локально в контейнере на основе образа `mcr.microsoft.com/mssql/server`.

Заметка

Как и эмуляторы, вызов RunAsContainer в построителе ресурсов Azure не влияет на манифест публикации. При публикации приложения созданный файл Bicep отражает реальную службу Azure, а не локальный контейнер.

Общие сведения об API интеграции Azure

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

В предыдущем разделе контейнеров вы узнали, как выполнять службы Azure локально в контейнерах. Если вы знакомы с .NET.NET Aspire, вы можете задаться вопросом, чем отличается вызов AddAzureRedis("redis").RunAsContainer() для получения локального контейнера docker.io/library/redis от вызова AddRedis("redis"), поскольку оба приводят к одному и тому же локальному контейнеру.

Ответ заключается в том, что при локальной работе нет никакой разницы. Однако при публикации вы получаете разные ресурсы:

интерфейс прикладного программирования (API)	Режим выполнения	Режим публикации
AddAzureRedis("redis").RunAsContainer()	Локальный контейнер Redis	Azure Cache for Redis
AddRedis("redis")	Локальный контейнер Redis	Контейнерное приложение Azure с образом Redis

То же самое верно для служб SQL и PostgreSQL:

интерфейс прикладного программирования (API)	Режим выполнения	Режим публикации
AddAzurePostgresFlexibleServer("postgres").RunAsContainer()	Локальный контейнер PostgreSQL	Azure PostgreSQL гибкие Server
AddPostgres("postgres")	Локальный контейнер PostgreSQL	Контейнерное приложение Azure с образом PostgreSQL
AddAzureSqlServer("sql").RunAsContainer()	Локальный контейнер SQL Server	Azure SQL Server
AddSqlServer("sql")	Локальный контейнер SQL Server	Контейнерное приложение Azure с образом SQL Server

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

Инфраструктура как код

Пакет SDK Azure для .NET предоставляет 📦Azure. Подготовка пакета NuGet и набора пакетов подготовки для конкретных служб Azure. Эти библиотеки управления Azure упрощают декларативное определение инфраструктуры Azure в .NET. Их API позволяют создавать объектно-ориентированную инфраструктуру в C#, что приводит к Bicep. Bicep — это предметно-ориентированный язык (DSL) для декларативного развертывания Azure ресурсов.

Хотя можно вручную подготовить ресурсы Azure, .NET Aspire упрощает процесс, предоставляя набор API для выражения Azure ресурсов. Эти API-интерфейсы представлены как методы расширения в библиотеке размещения .NET AspireAzure, расширяющие интерфейс IDistributedApplicationBuilder. При добавлении Azure ресурсов в узел приложения они добавляют соответствующие функции подготовки неявно. Другими словами, вам не нужно напрямую вызывать API для провиженинга.

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

Существует несколько способов влияния на созданные файлы Bicep:

Azure: Настройка обеспечения:
- Настройка инфраструктуры: кастомизация инфраструктуры ресурсов Azure.
- Добавьте инфраструктуру Azure: вручную добавьте инфраструктуру Azure на узел вашего приложения.
Использовать пользовательские шаблоны Bicep:
- справочные файлы Bicep: добавьте ссылку на файл Bicep, находящийся на диске.
- Справочник встроенного Bicep: добавьте встроенный шаблон Bicep.

Локальная настройка и `Azure.Provisioning`

Чтобы избежать объединения терминов и помочь дезамбигуировать "подготовку", важно понимать разграничение между локальной подготовкой и Azure подготовки:

Локальное обеспечение:

По умолчанию при вызове любого из API интеграции размещения Azure для неявного добавления ресурсов Azure вызывается API AddAzureProvisioning(IDistributedApplicationBuilder). Этот API регистрирует службы в контейнере внедрения зависимостей (DI), который используется для подготовки Azure ресурсов при запуске узла приложения. Эта концепция называется локальной подготовкой. Дополнительные сведения см. в локальном Azure обеспечении.
Azure.Provisioning:

Azure.Provisioning относится к пакету NuGet и представляет собой набор библиотек, которые позволяют использовать C# для создания Bicep. Интеграция Azure размещения в .NET Aspire использует эти библиотеки за кулисами для генерации файлов Bicep, которые определяют ресурсы Azure, необходимые вам. Дополнительные сведения см. в настройках Azure.Provisioning.

настройка `Azure.Provisioning`

Все хостинг-интеграции .NET AspireAzure предоставляют различные ресурсы Azure, и все они являются подклассами типа AzureProvisioningResource, который наследует от AzureBicepResource. Это позволяет расширениям, которые ограничены общим типом, использовать удобный API для настройки инфраструктуры в соответствии с вашими предпочтениями. Хотя .NET.NET Aspire предоставляет значения по умолчанию, вы можете повлиять на созданный Bicep с помощью этих API.

Настройка инфраструктуры

Независимо от того, с каким ресурсом Azure вы работаете, для настройки базовой инфраструктуры вы вызываете метод расширения ConfigureInfrastructure. Этот метод позволяет настроить инфраструктуру ресурса Azure путем передачи делегата configure типа Action<AzureResourceInfrastructure>. Тип AzureResourceInfrastructure является подклассом Azure.Provisioning.Infrastructure. Этот тип предоставляет массивную область поверхности API для настройки базовой инфраструктуры ресурса Azure.

Рассмотрим следующий пример:

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

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

Добавляет параметр с именем storage-sku.
Добавляет хранилище Azure с помощью API AddAzureStorage с именем storage.
Цепляет вызов ConfigureInfrastructure для настройки инфраструктуры хранилища Azure:
- Возвращает ресурсы, которые можно предоставить.
- Фильтрует до единой StorageAccount.
- Назначает параметр storage-sku свойству StorageAccount.Sku:
  - Новый экземпляр StorageSku имеет свое свойство Name, назначенное из результата API AsProvisioningParameter.

Этот пример направляет поток внешнего параметра в инфраструктуру хранилища Azure, что приводит к созданию файла Bicep, отражающего нужную конфигурацию.

Добавление инфраструктуры Azure

Не все службы Azure представлены в виде интеграций .NET Aspire. Хотя они могут быть предоставлены позже, вы по-прежнему можете предоставить службы, доступные в библиотеках Azure.Provisioning.*. Представьте себе сценарий, в котором у вас есть рабочая служба, которая отвечает за управление реестром контейнеров Azure. Теперь представьте, что проект размещения приложения имеет зависимость от пакета NuGet 📦Azure.Provisioning.ContainerRegistry.

API AddAzureInfrastructure можно использовать для добавления инфраструктуры реестра контейнеров Azure в хост приложения:

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

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

Вызывает AddAzureInfrastructure с именем acr.
Предоставляет делегат configureInfrastructure для настройки инфраструктуры реестра контейнеров Azure:
- Создает экземпляр ContainerRegistryService с именем acr и стандартным номером SKU.
- Добавляет службу реестра контейнеров Azure в переменную infra.
- Создает экземпляр ProvisioningOutput с именем registryName, типом stringи значением, которое соответствует названию реестра контейнеров Azure.
- Добавляет выходные данные в переменную infra.
Добавляет проект с именем worker в сборщик.
Вызывает цепочку вызова WithEnvironment, чтобы задать переменную среды ACR_REGISTRY_NAME в проекте значением вывода registryName.

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

Рассмотрим полученный файл Bicep:

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

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

Файл Bicep отражает нужную конфигурацию реестра контейнеров Azure, как определено API AddAzureInfrastructure.

Используйте пользовательские шаблоны Bicep

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

Хотя .NET.NET Aspire предоставляет набор предварительно созданных шаблонов Bicep, могут возникнуть моменты, когда вы хотите настроить шаблоны или создать собственные. В этом разделе описываются понятия и соответствующие API, которые можно использовать для настройки шаблонов Bicep.

Важный

Этот раздел не предназначен для обучения Bicep, а для предоставления рекомендаций по созданию пользовательских шаблонов Bicep для использования с .NET.NET Aspire.

В рамках истории развертывания Azure для .NET Aspire, Azure Developer CLI (azd) обеспечивает понимание вашего проекта .NET Aspire и возможность его развертывания на Azure. Интерфейс командной строки azd использует шаблоны Bicep для развертывания приложения в Azure.

Установка пакета `Aspire.Hosting.Azure`

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

Совет

Если вы используете любую из интеграции размещения Azure, вам не нужно устанавливать пакет Aspire.Hosting.Azure, так как это транзитивная зависимость.

Для использования любой из этих функций необходимо установить пакет NuGet 📦Aspire.Hosting.Azure:

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure

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

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

Что ожидать от примеров

Все примеры в этом разделе предполагают, что вы используете пространство имен Aspire.Hosting.Azure. Кроме того, в примерах предполагается, что у вас есть экземпляр IDistributedApplicationBuilder:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

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

Ссылки на файлы Bicep

Представьте, что у вас есть шаблон Bicep в файле с именем storage.bicep, который подготавливает учетную запись хранения Azure:

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Чтобы добавить ссылку на файл Bicep на диске, вызовите метод AddBicepTemplate. Рассмотрим следующий пример:

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

Приведенный выше код добавляет ссылку на файл Bicep, расположенный в ../infra/storage.bicep. Пути к файлам должны быть относительными к узлу приложения проекта. Эта ссылка приводит к добавлению AzureBicepResource в коллекцию ресурсов приложения с именем "storage", а API возвращает экземпляр IResourceBuilder<AzureBicepResource>, который можно использовать для дальнейшей настройки ресурса.

Ссылка на Bicep в онлайн-коде

Хотя файл Bicep на диске является наиболее распространенным сценарием, вы также можете добавить встроенные шаблоны Bicep. Встроенные шаблоны могут быть полезными, если вы хотите определить шаблон в коде или при динамическом создании шаблона. Чтобы добавить встроенный шаблон Bicep, вызовите метод AddBicepTemplateString с шаблоном Bicep в качестве string. Рассмотрим следующий пример:

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

В этом примере шаблон Bicep определяется как встроенный string и добавляется в коллекцию ресурсов приложения с именем "ai". В этом примере подготавливается ресурс Azure для ИИ.

Передача параметров в шаблоны Bicep

Bicep поддерживает прием параметров, которые можно использовать для настройки поведения шаблона. Чтобы передать параметры в шаблон Bicep из .NET.NET Aspire, вызовите цепочку методов WithParameter, как показано в следующем примере:

var region = builder.AddParameter("region");

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

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

Добавляет параметр с именем "region" в экземпляр builder.
Добавляет ссылку на файл Bicep, расположенный в ../infra/storage.bicep.
Передает параметр "region" шаблону Bicep, который разрешается с помощью стандартного метода разрешения параметров.
Передает параметр "storageName" шаблону Bicep со значением жестко закодированного.
Выполняется передача параметра "tags" в шаблон Bicep в виде массива строк.

Дополнительные сведения см. в разделе Внешние параметры.

Известные параметры

.NET .NET Aspire предоставляет набор известных параметров, которые можно передать в шаблоны Bicep. Эти параметры используются для предоставления сведений о приложении и окружении шаблонам Bicep. Доступны следующие известные параметры:

Поле	Описание	Ценность
AzureBicepResource.KnownParameters.KeyVaultName	Название ресурса хранилища ключей, используемого для хранения секретных выходных данных.	`"keyVaultName"`
AzureBicepResource.KnownParameters.Location	Расположение ресурса. Это необходимо для всех ресурсов.	`"location"`
AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId	Идентификатор ресурса рабочей области Log Analytics.	`"logAnalyticsWorkspaceId"`
AzureBicepResource.KnownParameters.PrincipalId	Основной идентификатор текущего пользователя или управляемого удостоверения.	`"principalId"`
AzureBicepResource.KnownParameters.PrincipalName	Основное имя текущего пользователя или управляемого удостоверения.	`"principalName"`
AzureBicepResource.KnownParameters.PrincipalType	Основной тип текущего пользователя или управляемого удостоверения. Либо `User`, либо `ServicePrincipal`.	`"principalType"`

Чтобы использовать известный параметр, передайте имя параметра в метод WithParameter, например WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Вы не передаете значения для известных параметров, так как .NET.NET Aspire обрабатывает их от вашего имени.

Рассмотрим пример, где вы хотите настроить веб-хук для Event Grid Azure. Вы можете определить шаблон Bicep следующим образом:

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

Этот шаблон Bicep определяет несколько параметров, включая topicName, webHookEndpoint, principalId, principalTypeи необязательный location. Чтобы передать эти параметры в шаблон Bicep, можно использовать следующий фрагмент кода:

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);

Проект webHookApi добавляется в качестве ссылки на builder.
Параметру topicName передается заранее заданное значение имени.
Параметр webHookEndpoint передается как выражение, результирующее в URL-адрес из ссылки 'https' конечной точки ссылок проекта api с маршрутом /hook.
Параметры principalId и principalType передаются как известные параметры.

Известные параметры основаны на соглашениях и не должны сопровождаться соответствующим значением при передаче с помощью API WithParameter. Известные параметры упрощают некоторые распространенные функции, такие как назначения ролей, при добавлении в шаблоны Bicep, как это видно на предыдущем примере. Назначения ролей необходимы для веб-перехватчика Event Grid, чтобы отправлять события в указанную конечную точку. Дополнительные сведения см. в разделе «Роль отправителя данных в сетке событий».

Получение выходных данных из ссылок Bicep

Помимо передачи параметров в шаблоны Bicep, вы также можете получить выходные данные из шаблонов Bicep. Рассмотрим следующий шаблон Bicep, так как он определяет output с именем endpoint:

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Bicep определяет выходные данные с именем endpoint. Чтобы получить выходные данные из шаблона Bicep, вызовите метод GetOutput для экземпляра IResourceBuilder<AzureBicepResource>, как показано в следующем фрагменте кода C#:

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

В этом примере выходные данные из шаблона Bicep извлекаются и хранятся в переменной endpoint. Как правило, вы передаете эти выходные данные в качестве переменной среды другому ресурсу, который использует его. Например, если у вас был проект ASP.NET Core минимального API, который зависит от этой конечной точки, можно передать выходные данные в качестве переменной среды в проект с помощью следующего фрагмента кода:

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

Дополнительные сведения см. в результатах "Bicep".

Получите секретные выходные данные из ссылок Bicep

Важно избежать выходных данных для секретов при работе с Bicep. Если выходные данные считаются секретом, то есть его не следует раскрывать в журналах или других местах, можно обращаться с ним соответствующим образом. Это можно сделать, сохраняя секрет в Azure Key Vault и ссылаясь на него в шаблоне Bicep. Интеграция .NET Aspireи Azure предоставляет шаблон для надежного хранения выходных данных из шаблона Bicep, позволяя использовать параметр keyVaultName для хранения секретов в Azure Key Vault.

Рассмотрим следующий шаблон Bicep в качестве примера, который помогает продемонстрировать эту концепцию защиты секретных выходных данных:

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

Предыдущий шаблон Bicep ожидает параметр keyVaultName среди нескольких других параметров. Затем он определяет ресурс Azure Cosmos DB и сохраняет секрет в Azure Key Vaultпод именем connectionString, которая представляет собой полную строку подключения к экземпляру Cosmos DB. Чтобы получить доступ к значению строки секретного подключения, можно использовать следующий фрагмент кода:

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

В предыдущем фрагменте кода шаблон Bicep cosmos добавляется в качестве ссылки на builder. Вывод секретного значения connectionString извлекается из шаблона Bicep и сохраняется в переменной. Затем выходные данные секрета передаются в качестве переменной среды (ConnectionStrings__cosmos) в проект api. Эта переменная среды используется для подключения к экземпляру Cosmos DB.

При развертывании этого ресурса базовый механизм развертывания автоматически справочные секреты из Azure Key Vault. Чтобы гарантировать изоляцию секретов, .NET.NET Aspire создает Key Vault для каждого источника.

Заметка

В режиме локальной подготовки секрет извлекается из Key Vault и устанавливается в переменную среды. Дополнительные сведения см. в локальном Azure обеспечении.

Издательство

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

Дополнительные сведения о публикации и развертывании см. в Развертывание проекта .NET Aspire в Azure Container Apps с помощью Azure Developer CLI (подробное руководство).

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

Общие сведения об интеграции .NET AspireAzure

Добавление подключения к существующим ресурсам Azure

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

Типичный интерфейс разработчика

Локальные эмуляторы

Локальные контейнеры

Общие сведения об API интеграции Azure

Инфраструктура как код

Локальная настройка и `Azure.Provisioning`

настройка `Azure.Provisioning`

Настройка инфраструктуры

Добавление инфраструктуры Azure

Используйте пользовательские шаблоны Bicep

Установка пакета `Aspire.Hosting.Azure`

Что ожидать от примеров

Ссылки на файлы Bicep

Ссылка на Bicep в онлайн-коде

Передача параметров в шаблоны Bicep

Известные параметры

Получение выходных данных из ссылок Bicep

Получите секретные выходные данные из ссылок Bicep

Издательство

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

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

Общие сведения об интеграции .NET AspireAzure

Добавление подключения к существующим ресурсам Azure

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

Типичный интерфейс разработчика

Локальные эмуляторы

Локальные контейнеры

Общие сведения об API интеграции Azure

Инфраструктура как код

Локальная настройка и Azure.Provisioning

настройка Azure.Provisioning

Настройка инфраструктуры

Добавление инфраструктуры Azure

Используйте пользовательские шаблоны Bicep

Установка пакета Aspire.Hosting.Azure

Что ожидать от примеров

Ссылки на файлы Bicep

Ссылка на Bicep в онлайн-коде

Передача параметров в шаблоны Bicep

Известные параметры

Получение выходных данных из ссылок Bicep

Получите секретные выходные данные из ссылок Bicep

Издательство

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

Локальная настройка и `Azure.Provisioning`

настройка `Azure.Provisioning`

Установка пакета `Aspire.Hosting.Azure`