Sdílet prostřednictvím

Přehled integrace .NET AspireAzure

  • Článek

Azure je nejoblíbenější cloudovou platformou pro sestavování a nasazování aplikací .NET. Sada Azure SDK pro .NET umožňuje snadnou správu a používání služeb Azure. .NET Aspire poskytuje sadu integrací se službami Azure, kde můžete zdarma přidávat nové prostředky nebo se připojovat k existujícím. Tento článek podrobně popisuje některé běžné aspekty všech integrací Azure v .NET Aspire a má vám pomoct pochopit, jak je používat.

Přidat připojení k existujícím prostředkům Azure

.NET .NET Aspire umožňuje připojit se ke stávajícím prostředkům, včetně prostředků Azure. Vyjádření připojovacích řetězců je užitečné, když máte existující zdroje Azure, které chcete použít ve své aplikaci .NET Aspire. Rozhraní API AddConnectionString se používá s kontextem spouštění hostitele aplikace k podmíněnému přidání připojovacího řetězce do modelu aplikace.

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Podívejte se na následující příklad, kdy v režimu publikování přidáte prostředek úložiště Azure, zatímco v režimu spuštění přidáte připojovací řetězec do existujícího úložiště 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...

Předchozí kód:

  • Vytvoří novou instanci builder.
  • Přidá Azure prostředek úložiště s názvem storage v režimu publikování.
  • Přidá připojovací řetězec do existujícího Azure Storage s názvem storage v režimu spuštění.
  • Přidá do sestavovatele projekt s názvem api.
  • Projekt api odkazuje na storage zdroj bez ohledu na režim.

Projekt rozhraní API využívá informace o připojovacím řetězci bez znalostí o tom, jak ho hostitel aplikace nakonfiguroval. V publikačním režimu kód přidá nový prostředek Úložiště Azure, který se odpovídajícím způsobem projeví v manifestu nasazení . Pokud je v režimu spuštění, připojovací řetězec odpovídá konfigurační hodnotě viditelné pro hostitele aplikace. Předpokládá se, že všechna přiřazení rolí pro cílový prostředek jsou nakonfigurována. To znamená, že byste pravděpodobně nakonfigurovali proměnnou prostředí nebo tajný klíč uživatele pro uložení připojovacího řetězce. Konfigurace se vyřeší z konfiguračního klíče ConnectionStrings__storage (nebo ConnectionStrings:storage). Tyto konfigurační hodnoty se dají zobrazit při spuštění aplikace. Další informace najdete v tématu Podrobnosti o prostředku.

Přidejte prostředky Azure

Všechny integrace hostování .NET AspireAzure zpřístupňují Azure prostředky a podle konvence se přidávají pomocí rozhraní API AddAzure*. Když přidáte tyto prostředky do hostitele aplikace .NET Aspire, budou představovat službu Azure. Rozhraní API AddAzure* vrátí IResourceBuilder<T>, kde T je typ prostředku Azure. Tato rozhraní IResourceBuilder<T> (tvůrce) poskytují plynulé API, které umožňuje konfigurovat základní prostředek Azure v rámci modelu aplikace .

Typické prostředí pro vývojáře

Když hostitel aplikace obsahuje prostředky a spustíte ho místně (typický vývojář F5 nebo prostředí ), zřídí se prostředky ve vašem předplatném. To vám umožní jako vývojářům ladit proti nim lokálně, v rámci kontextu hostitele vaší aplikace.

cílem .NET.NET Aspire je minimalizovat náklady tím, že se ve výchozím režimu použijí Základní nebo Standardnískladové jednotky (SKU) pro jejich integrace Azure. I když jsou k dispozici tyto rozumné výchozí hodnoty, můžete přizpůsobit Azure prostředky tak, aby vyhovovaly vašim potřebám. Kromě toho některé integrace podporují emulátory nebo kontejnery, které jsou užitečné pro místní vývoj, testování a ladění. Když aplikaci spustíte místně, prostředky Azure ve výchozím nastavení používají skutečnou službu Azure. Můžete je ale nakonfigurovat tak, aby používaly místní emulátory nebo kontejnery, a vyhnout se tak nákladům spojeným se skutečnými Azure službami během místního vývoje.

Místní emulátory

Některé Azure služby je možné spouštět místně v emulátorech. V současné době .NET Aspire podporuje následující emulátory Azure:

Integrace hostování Popis
Azure Cosmos DB Voláním AzureCosmosExtensions.RunAsEmulator na IResourceBuilder<AzureCosmosDBResource> nakonfigurujte prostředek Cosmos DB tak, aby se emuloval pomocírozhraní API NoSQL.
Azure Event Hubs Zavolejte AzureEventHubsExtensions.RunAsEmulator na IResourceBuilder<AzureEventHubsResource>, abyste nakonfigurovali prostředek Event Hubs tak, aby se emuloval.
Azure Úložiště Voláním AzureStorageExtensions.RunAsEmulator na IResourceBuilder<AzureStorageResource> nakonfigurujte prostředek úložiště, aby byl emulován jako pomocí Azurite.

Pokud chcete, aby vaše Azure prostředky používaly místní emulátory, propojte volání metody RunAsEmulator v sestavovateli prostředků Azure. Tato metoda nakonfiguruje prostředek Azure tak, aby místo skutečné služby Azure používal místní emulátor.

Důležitý

Volání některého z dostupných rozhraní API RunAsEmulator prostřednictvím nástroje pro tvorbu prostředků Azure nemá vliv na publikační manifest . Při publikování aplikace vygenerovaný soubor Bicep odráží skutečnou službu Azure, nikoli místní emulátor.

Místní kontejnery

Některé Azure služby je možné spouštět místně v kontejnerech. Pokud chcete místně spustit službu Azure v kontejneru, zřetězte volání metody RunAsContainer na builderu zdrojů Azure. Tato metoda nakonfiguruje prostředek Azure tak, aby se spouštěl místně v kontejneru místo skutečné služby Azure.

V současné době .NET Aspire podporuje jako kontejnery následující služby Azure:

Integrace hostování Podrobnosti
Azure Cache for Redis Voláním AzureRedisExtensions.RunAsContainer na IResourceBuilder<AzureRedisCacheResource> ji nakonfigurujte tak, aby se spouštěla místně v kontejneru na základě image docker.io/library/redis.
flexibilní AzurePostgreSQLServer Voláním AzurePostgresExtensions.RunAsContainer na IResourceBuilder<AzurePostgresFlexibleServerResource> ji nakonfigurujte tak, aby se spouštěla místně v kontejneru na základě image docker.io/library/postgres.
Azure SQL Server Voláním AzureSqlExtensions.RunAsContainer na IResourceBuilder<AzureSqlServerResource> ji nakonfigurujte tak, aby se spouštěla místně v kontejneru na základě image mcr.microsoft.com/mssql/server.

Poznámka

Podobně jako emulátory nemá volání RunAsContainer v tvůrci prostředků Azure vliv na manifestu publikování. Když publikujete svou aplikaci, soubor Bicep vygenerovaný odráží skutečnou službu Azure, nikoli místní kontejner.

Pochopit rozhraní API pro integraci Azure

.NET .NET Aspiresíla spočívá v jeho schopnosti poskytovat úžasný vývojový cyklus pro vývojáře. Integrace Azure se nijak neliší. Poskytují sadu běžných rozhraní API a vzorů, které se sdílejí napříč všemi prostředky Azure. Tato rozhraní API a vzory jsou navržená tak, aby usnadnila práci s Azure prostředky konzistentním způsobem.

V předchozí části o kontejnerech jste viděli, jak místně spustit služby Azure v kontejnerech. Pokud znáte .NET.NET Aspire, možná vás zajímá, čím se liší volání AddAzureRedis("redis").RunAsContainer() k získání místního kontejneru docker.io/library/redis od AddRedis("redis")– protože obojí vede ke stejnému místnímu kontejneru.

Odpověď je, že při místním spuštění není žádný rozdíl. Když ale publikujete, získáte různé prostředky:

API Režim spuštění Režim publikování
AddAzureRedis("redis").RunAsContainer() Místní kontejner Redis Azure Cache for Redis
AddRedis("redis") Místní kontejner Redis Azure Container App s obrazem Redis

Totéž platí pro služby SQL a PostgreSQL:

API Režim spuštění Režim publikování
AddAzurePostgresFlexibleServer("postgres"). RunAsContainer() Místní kontejner PostgreSQL flexibilní AzurePostgreSQLServer
AddPostgres("postgres") Místní kontejner PostgreSQL Azure Container App s obrazem PostgreSQL
AddAzureSqlServer("sql").RunAsContainer() Místní kontejner SQL Server Azure SQL Server
AddSqlServer("sql") Místní kontejner SQL Server Azure Container App s obrazem SQL Server

Další informace o rozdílu mezi režimy spuštění a publikování najdete v tématu .NET.NET Aspire hostitel aplikace: Kontext spuštění.

Infrastruktura jako kód

Sada Azure SDK pro .NET poskytuje 📦Azure. Balíček NuGet pro zřizování a sada balíčků pro zřizování služeb specifických pro Azure. Tyto zřizovací knihovny Azure usnadňují deklarativní specifikování Azure infrastruktury přímo v .NET. Jejich rozhraní API umožňují psát objektově orientovanou infrastrukturu v jazyce C#, a tak vzniká Bicep. Bicep je jazyk specifický pro doménu (DSL) pro deklarativní Azure nasazení prostředků.

I když je možné prostředky Azure zřizovat ručně, .NET Aspire proces zjednodušuje tím, že poskytuje sadu rozhraní API pro vyjádření Azure prostředků. Tato rozhraní API jsou k dispozici jako rozšiřující metody v .NET AspireAzure hostitelských knihovnách, které rozšiřují rozhraní IDistributedApplicationBuilder. Když přidáte Azure prostředky do aplikačního hostitele, příslušné funkce zřizování se implicitně přidají. Jinými slovy, nemusíte volat žádné provisioning API přímo.

Vzhledem k tomu, že .NET Aspire modeluje Azure zdroje v rámci integrace hostingu Azure, je sada nástrojů Azure SDK používána k zajištění těchto zdrojů. Generují se soubory Bicep, které definují potřebné Azure prostředky. Vytvořené soubory Bicep jsou vyhotoveny spolu se soubory manifestu, když publikujete svou aplikaci.

Vygenerované soubory Bicep můžete ovlivnit několika způsoby:

Místní zřizování a Azure.Provisioning

Aby se zabránilo zaměňování pojmů a pomohlo při rozlišení pojmů "zřizování", je důležité pochopit rozdíl mezi místním zřizováním a Azure zřizováním:

  • Místní zřizování:

    Ve výchozím nastavení se při volání některého z Azure hostování rozhraní API integrace pro přidání Azure prostředků volá rozhraní API AddAzureProvisioning(IDistributedApplicationBuilder) implicitně. Toto rozhraní API registruje služby v kontejneru zavádění závislostí (DI), který se používá k poskytnutí Azure prostředků při spuštění aplikace. Tento koncept se označuje jako místní zřizování. Další informace naleznete v místním Azure zřizování.

  • Azure.Provisioning:

    Azure.Provisioning odkazuje na balíček NuGet a je sada knihoven, která umožňuje vygenerovat Bicep pomocí jazyka C#. Azure hostování integrací v .NET Aspire tyto knihovny používat v rámci krytů ke generování souborů Bicep, které definují potřebné Azure prostředky. Další informace naleznete v tématu Azure.Provisioning přizpůsobení.

přizpůsobení Azure.Provisioning

Všechny integrace hostingu .NET AspireAzure zpřístupňují různé prostředky Azure a všechny jsou podtřídami typu AzureProvisioningResource, který sám dědí z AzureBicepResource. Tímto se umožňují rozšíření, která jsou obecně omezena na tento typ, což umožňuje plynulé API k přizpůsobení infrastruktury podle vašich představ. I když .NET.NET Aspire poskytuje výchozí hodnoty, máte volnost ovlivnit generovaný Bicep pomocí těchto rozhraní API.

Konfigurace infrastruktury

Bez ohledu na prostředek Azure, se kterým pracujete, abyste nakonfigurovali jeho podkladovou infrastrukturu, zřetězíte volání metody rozšíření ConfigureInfrastructure. Tato metoda umožňuje přizpůsobit infrastrukturu prostředku Azure pomocí delegáta configure typu Action<AzureResourceInfrastructure>. Typ AzureResourceInfrastructure je podtřídou Azure.Provisioning.Infrastructure. Tento typ zveřejňuje rozsáhlou plochu rozhraní API pro konfiguraci základní infrastruktury prostředku Azure.

Podívejte se na následující příklad:

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)
        };
    });

Předchozí kód:

  • Přidá parametr s názvem storage-sku.
  • Přidává Azure Storage pomocí rozhraní API AddAzureStorage nazvaného storage.
  • Zřetězí volání ConfigureInfrastructure a přizpůsobí infrastrukturu Azure Storage:

Tento příklad znázorňuje tok externího parametru do infrastruktury Azure Storage, což vede k vygenerovanému souboru Bicep odrážejícího požadovanou konfiguraci.

Přidat infrastrukturu Azure

Ne všechny Azure služby jsou dostupné jako integrace .NET Aspire. I když mohou být dostupné později, můžete stále zřizovat služby, které jsou k dispozici v Azure.Provisioning.* knihovnách. Představte si scénář, ve kterém máte pracovní službu, která zodpovídá za správu služby Azure Container Registry. Teď si představte, že hostitelský projekt aplikace využívá závislost na 📦Azure.Provisioning.ContainerRegistry balíčku NuGet.

Pomocí rozhraní AddAzureInfrastructure API můžete do hostitele aplikace přidat infrastrukturu služby Azure Container Registry:

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));

Předchozí kód:

  • Volá AddAzureInfrastructure s názvem acr.
  • Poskytuje configureInfrastructure delegáta pro přizpůsobení infrastruktury služby Azure Container Registry:
    • Vytvoří instanci ContainerRegistryService s názvem acr a standardním SKU.
    • Přidá službu Azure Container Registry do proměnné infra.
    • Vytvoří instanci ProvisioningOutput s názvem registryName, typem stringa hodnotou, která odpovídá názvu Azure Container Registry.
    • Přidá výstup do proměnné infra.
  • Přidá do sestavovatele projekt s názvem worker.
  • Zavolá funkci WithEnvironment a zřetězí ji tak, aby nastavila proměnnou prostředí ACR_REGISTRY_NAME v projektu na hodnotu, kterou vrací výstup registryName.

Funkce předvádí, jak do hostitelského projektu aplikace přidat Azure infrastrukturu, a to i v případě, že služba Azure není přímo zpřístupněná jako integrace .NET Aspire. Dále ukazuje, jak plynout výstup služby Azure Container Registry do prostředí závislého projektu.

Podívejte se na výsledný soubor 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

Soubor Bicep odráží požadovanou konfiguraci služby Azure Container Registry, jak je definováno rozhraním API AddAzureInfrastructure.

Použijte vlastní šablony Bicep

Když cílíte na Azure jako požadovaný poskytovatel cloudu, můžete pomocí Bicep definovat infrastrukturu jako kód. Cílem je výrazně zjednodušit vytváření obsahu s čistější syntaxí a lepší podporou modularity a opětovného použití kódu.

I když .NET.NET Aspire poskytuje sadu předem připravených šablon Bicep, může se stát, že budete chtít šablony přizpůsobit nebo vytvořit vlastní. Tato část vysvětluje koncepty a odpovídající rozhraní API, která můžete použít k přizpůsobení šablon Bicep.

Důležitý

Tato část není určená k výuce Bicep, ale spíše k poskytování pokynů k vytváření vlastních šablon Bicep pro použití s .NET.NET Aspire.

V rámci scénáře nasazení Azure pro .NET Aspireposkytuje Azure Developer CLI (azd) porozumění projektu .NET Aspire a možnost ho nasadit do Azure. Rozhraní příkazového řádku azd využívá šablony Bicep k nasazení aplikace na Azure.

Instalace balíčku Aspire.Hosting.Azure

Pokud chcete odkazovat na soubory Bicep, je možné, že nepoužíváte žádnou z Azure hostování integrací. V tomto případě můžete nadále odkazovat na soubory Bicep tím, že nainstalujete balíček Aspire.Hosting.Azure. Tento balíček poskytuje potřebná rozhraní API pro práci se soubory Bicep a přizpůsobení prostředků Azure.

Spropitné

Pokud používáte některou z Azure hostování integrací, nemusíte instalovat balíček Aspire.Hosting.Azure, protože se jedná o tranzitivní závislost.

Pokud chcete použít některou z těchto funkcí, musí být nainstalován balíček NuGet: 📦Aspire.Hosting.Azure

dotnet add package Aspire.Hosting.Azure

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Co očekávat od příkladů

Všechny příklady v této části předpokládají, že používáte obor názvů Aspire.Hosting.Azure. Kromě toho příklady předpokládají, že máte instanci IDistributedApplicationBuilder:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Ve výchozím nastavení se při volání některého z rozhraní API souvisejících s Bicep provede také volání AddAzureProvisioning, které přidává podporu generování Azure prostředků dynamicky během spouštění aplikace. Další informace najdete v tématu Místní zřizování a Azure.Provisioning.

Referenční soubory Bicep

Představte si, že máte šablonu Bicep v souboru s názvem storage.bicep, která zřizuje účet pro ukládání 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'
  }
}

Chcete-li přidat odkaz na soubor Bicep na disku, zavolejte metodu AddBicepTemplate. Podívejte se na následující příklad:

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

Předchozí kód přidá odkaz na soubor Bicep umístěný v ../infra/storage.bicep. Cesty k souborům by měly být relativní k hostiteli aplikace a projektu. Tento odkaz má za následek přidání AzureBicepResource do kolekce prostředků aplikace s názvem "storage" a rozhraní API vrátí instanci IResourceBuilder<AzureBicepResource>, kterou lze použít k dalšímu přizpůsobení prostředku.

Odkaz na vložený bicep

I když mít soubor Bicep na disku je nejběžnějším scénářem, můžete také přidávat šablony Bicep přímo. Vložené šablony můžou být užitečné, když chcete definovat šablonu v kódu nebo když chcete šablonu vygenerovat dynamicky. Pokud chcete přidat vloženou šablonu Bicep, zavolejte metodu AddBicepTemplateString se šablonou Bicep jako string. Podívejte se na následující příklad:

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
            }
          }
        }
        """
    );

V tomto příkladu je šablona Bicep definována jako vložená string a přidána do kolekce prostředků aplikace s názvem "ai". Tento příklad nastaví prostředek Azure AI.

Předání parametrů do šablon Bicep

Bicep podporuje přijímání parametrů, které lze použít k přizpůsobení chování šablony. Pokud chcete předat parametry do šablony Bicep z .NET.NET Aspire, zřetězte volání metody WithParameter tak, jak je ukázáno v následujícím příkladu:

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

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

Předchozí kód:

  • Přidá parametr s názvem "region" do instance builder.
  • Přidá odkaz k souboru Bicep umístěnému v ../infra/storage.bicep.
  • Předá parametr "region" šabloně Bicep, který je vyřešen pomocí standardního rozlišení parametrů.
  • Předá parametr "storageName" šabloně Bicep s pevně zakódovanou hodnotou .
  • Předá parametr "tags" šabloně Bicep s polem řetězců.

Další informace naleznete v tématu Externí parametry.

Známé parametry

.NET .NET Aspire poskytuje sadu známých parametrů, které lze předat šabloně Bicep. Tyto parametry slouží k poskytování informací o aplikaci a prostředí šablonám Bicep. K dispozici jsou následující dobře známé parametry:

Pole Popis Hodnota
AzureBicepResource.KnownParameters.KeyVaultName Název prostředku trezoru klíčů sloužícího k ukládání výstupů tajných kódů. "keyVaultName"
AzureBicepResource.KnownParameters.Location Umístění prostředku. To se vyžaduje pro všechny zdroje. "location"
AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId ID prostředku pracovního prostoru služby Log Analytics. "logAnalyticsWorkspaceId"
AzureBicepResource.KnownParameters.PrincipalId Hlavní ID aktuálního uživatele nebo spravované identity. "principalId"
AzureBicepResource.KnownParameters.PrincipalName Hlavní název aktuálního uživatele nebo spravované identity. "principalName"
AzureBicepResource.KnownParameters.PrincipalType Hlavní typ aktuálního uživatele nebo spravované identity. Buď User, nebo ServicePrincipal. "principalType"

Chcete-li použít dobře známý parametr, předejte název parametru metodě WithParameter, například WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Nepředáváte hodnoty pro dobře známé parametry, protože .NET.NET Aspire je vyřeší vaším jménem.

Představte si příklad, ve kterém chcete nastavit webhook služby Event Grid Azure. Šablonu Bicep můžete definovat takto:

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

Tato šablona Bicep definuje několik parametrů, včetně topicName, webHookEndpoint, principalId, principalTypea volitelného location. Pokud chcete šabloně Bicep předat tyto parametry, můžete použít následující fragment kódu:

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);
  • Projekt webHookApi se přidá jako odkaz na builder.
  • Parametru topicName se předává pevně zakódovaná hodnota jména.
  • Parametr webHookEndpoint se předává jako výraz, který se překládá na adresu URL z "https" koncového bodu referencí projektu api s trasou /hook.
  • Parametry principalId a principalType se předávají jako dobře známé parametry.

Známé parametry jsou založené na konvencích a neměly by být doprovázeny odpovídající hodnotou při předání pomocí rozhraní WithParameter API. Známé parametry zjednodušují některé běžné funkce, například přiřazení rolí, při přidání do šablon Bicep, jak je znázorněno v předchozím příkladu. K odesílání událostí do zadaného koncového bodu se vyžadují přiřazení rolí pro webhook služby Event Grid. Další informace najdete v tématu přiřazení role odesílatele dat event gridu.

Získání výstupů z odkazů Bicep

Kromě předávání parametrů do šablon Bicep můžete také získat výstupy ze šablon Bicep. Představte si následující šablonu Bicep, protože definuje output s názvem 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 definuje výstup pojmenovaný jako endpoint. Pokud chcete získat výstup ze šablony Bicep, zavolejte metodu GetOutput v instanci IResourceBuilder<AzureBicepResource>, jak je znázorněno v následujícím fragmentu kódu jazyka C#:

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

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

V tomto příkladu se načte a uloží výstup ze šablony Bicep do proměnné endpoint. Obvykle byste tento výstup předali jako proměnnou prostředí jinému prostředku, který na něj spoléhá. Pokud jste například měli ASP.NET Core minimální projekt rozhraní API, který závisí na tomto koncovém bodu, můžete výstup předat do projektu jako proměnnou prostředí pomocí následujícího fragmentu kódu:

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);

Pro více informací se podívejte do výstupů Bicep.

Získání tajných výstupů z referencí Bicep

Při práci s Bicep je důležité vyhnout se výstupům tajných kódů. Pokud je výstup považován za tajný, což znamená, že by neměl být vystaven v protokolech nebo na jiných místech, můžete s ním zacházet jako s takovým. Toho lze dosáhnout uložením tajného kódu do Azure Key Vault a odkazováním na něj v šabloně Bicep. .NET Aspireintegrace Azure poskytuje vzor pro bezpečné ukládání výstupů ze šablony Bicep tím, že umožňuje prostředkům používat parametr keyVaultName k ukládání tajných kódů do Azure Key Vault.

Představte si následující šablonu Bicep jako příklad, která vám pomůže předvést tento koncept zabezpečení výstupů tajných kódů:

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

Předchozí šablona Bicep očekává kromě několika dalších parametrů parametr keyVaultName. Pak definuje prostředek Azure Cosmos DB a uloží tajný kód do Azure Key Vaultpod názvem connectionString, který představuje plně kvalifikovaný připojovací řetězec k instanci Cosmos DB. Pro přístup k této hodnotě připojovacího řetězce tajného kódu můžete použít následující fragment kódu:

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);

V předchozím fragmentu kódu se šablona cosmos Bicep přidá jako odkaz na builder. Výstup tajného kódu connectionString se načte ze šablony Bicep a uloží se do proměnné. Výstup tajného kódu se pak předá do projektu ConnectionStrings__cosmos jako proměnná prostředí (api). Tato proměnná prostředí slouží k připojení k instanci Cosmos DB.

Po nasazení tohoto prostředku se základní mechanismus nasazení automaticky referenční tajné kódy z Azure Key Vault. Pokud chcete zaručit izolaci tajných kódů, .NET.NET Aspire vytvoří službu Key Vault pro každý zdroj.

Poznámka

V místním režimu zřizování se tajný kód extrahuje ze služby Key Vault a nastaví ho v proměnné prostředí. Další informace naleznete v místním Azure zřizování.

Publikování

Při publikování aplikace se Azure zřizování vygenerované bicep používá Azure Developer CLI k vytvoření Azure prostředků ve vašem Azure předplatném. .NET .NET Aspire vytváří manifest publikování , který je také důležitou součástí procesu publikování. Azure Developer CLI je nástroj příkazového řádku, který poskytuje sadu příkazů pro správu Azure prostředků.

Další informace o publikování a nasazení najdete v tématu Nasazení projektu .NET Aspire pro Azure Container Apps pomocí Azure Developer CLI (podrobný průvodce).