Přehled integrace .NET AspireAzure

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ř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. API AddAzure* vrátí IResourceBuilder<T>, kde T je typ zdroje Azure. Tato rozhraní IResourceBuilder<T> (tvůrce) poskytují plynulé API, které umožňuje konfigurovat základní prostředek Azure v rámci modelu aplikace . Existují rozhraní API pro přidání nových Azure prostředků, označení prostředků jako existujících a konfiguraci chování prostředků v různých kontextech spuštění.

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

Když váš hostitel aplikace .NET Aspire obsahuje Azure prostředky a spustíte jej místně (typický vývojářský zážitek s F5 nebo dotnet run), Azure prostředky jsou zřízeny ve vašem Azure 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 lze emulovat, aby běžely místně. V současné době .NET Aspire podporuje následující emulátory Azure:

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.

Místní kontejnery

Některé Azure prostředky je možné nahradit místně pomocí opensourcových nebo místních kontejnerů. Pokud chcete nahradit prostředek Azure místně v kontejneru, zřetězte volání metody RunAsContainer v tvůrci prostředků Azure. Tato metoda nakonfiguruje Azure prostředek tak, aby místo skutečné služby Azure používal kontejnerizovanou verzi služby pro místní vývoj a testování.

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

Pochopte rozhraní API pro integraci Azure

.NET .NET Aspiresíla spočívá v jeho schopnosti poskytovat úžasný interní 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. Až ale budou zveřejněny, získáte různé zdroje:

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

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í.

Rozhraní API pro vyjádření Azure zdrojů v různých režimech

Distribuovaný tvůrce aplikací, součást hostitele aplikace , využívá návrhový vzor builder k AddAzure* prostředků do modelu aplikace . Vývojáři můžou tyto prostředky nakonfigurovat a definovat jejich chování v různých kontextech spuštění. Integrace hostování Azure poskytují API k určení, jak mají být tyto prostředky „publikovány“ a „spuštěny“.

Když se hostitel aplikace spustí, použije se kontext spuštění k určení, jestli je hostitel aplikace v Run nebo Publish režimu. Zásady vytváření názvů pro tato rozhraní API označují zamýšlenou akci pro prostředek.

Následující tabulka shrnuje zásady vytváření názvů používané k vyjádření Azure prostředků:

Další informace o způsobech provádění naleznete v tématu kontext provádění.

Obecné případy použití rozhraní API režimu spuštění

Použijte RunAsExisting, když potřebujete dynamicky pracovat s existujícím prostředkem během běhu, aniž byste museli nasazovat nebo aktualizovat. Při deklarování existujících prostředků v rámci konfigurace nasazení použijte PublishAsExisting, aby se zajistilo, že se použijí správné obory a oprávnění. Nakonec při deklarování existujících prostředků v obou konfiguracích použijte AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) s požadavkem na parametrizaci odkazů.

Dotaz na to, zda je prostředek označen jako již existující, můžete provést voláním metody rozšíření IsExisting(IResource) na IResource. Další informace najdete v tématu Použití existujících prostředků Azure.

Použití existujících prostředků Azure

.NET Aspire poskytuje podporu pro odkazování na existující prostředky Azure. Existující prostředek označíte prostřednictvím rozhraní API PublishAsExisting, RunAsExistinga AsExisting. Tato rozhraní API umožňují vývojářům odkazovat na již nasazené Azure prostředky, konfigurovat je a generovat vhodné manifesty nasazení pomocí šablon Bicep.

Stávající prostředky odkazované na tato rozhraní API je možné vylepšit přiřazením rolí a dalšími přizpůsobeními, které jsou k dispozici s infrastrukturou .NET.NET Aspirejako funkcemi kódu. Rozhraní API jsou omezena na prostředky Azure, které lze nasadit pomocí šablon Bicep.

Nastavte stávající prostředky Azure pro režim spuštění

Metoda RunAsExisting se používá, když se distribuovaná aplikace spouští v režimu spuštění. V tomto režimu předpokládá, že odkazovaný zdroj Azure již existuje a integruje se s ním během jeho spuštění bez jeho zřizování. Pokud chcete Azure prostředek označit jako existující, zavolejte metodu RunAsExisting na generátoru prostředků. Podívejte se na následující příklad:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Předchozí kód:

• Vytvoří novou instanci builder.
• Přidá do tvůrce parametr s názvem existingServiceBusName.
• Přidá do sestavovatele prostředek Azure Service Bus s názvem messaging.
• Volá metodu RunAsExisting v tvůrci prostředků serviceBus a předá parametr existingServiceBusName – alternativně můžete použít přetížení parametru string.
• Přidá do prostředku serviceBus frontu s názvem queue.

Ve výchozím nastavení se předpokládá, že odkaz na parametry služby Service Bus je ve stejné skupině prostředků Azure. Pokud je ale v jiné skupině prostředků, můžete skupinu prostředků předat explicitně jako parametr, abyste správně určili příslušné seskupení prostředků.

Konfigurace existujících prostředků Azure pro režim publikování

Metoda PublishAsExisting se používá v režimu publikování, pokud je záměr deklarovat a odkazovat na již existující Azure prostředek během režimu publikování. Toto rozhraní API usnadňuje vytváření manifestů a šablon, které obsahují definice prostředků mapující na existující prostředky v Bicep.

Pokud chcete Azure prostředek označit jako existující v režimu publikování, zavolejte metodu PublishAsExisting v Tvůrci prostředků. Podívejte se na následující příklad:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Předchozí kód:

• Vytvoří novou instanci builder.
• Přidá do tvůrce parametr s názvem existingServiceBusName.
• Přidá prostředek Azure Service Bus s názvem messaging do tvůrce.
• Volá metodu PublishAsExisting v tvůrci prostředků serviceBus a předá parametr existingServiceBusName – alternativně můžete použít přetížení parametru string.
• Přidá do prostředku serviceBus frontu s názvem queue.

Po spuštění hostitele aplikace v režimu publikování bude vygenerovaný soubor manifestu obsahovat existingResourceName parametr, který lze použít k odkazování na existující Azure prostředek. Zvažte následující vygenerovaný částečný fragment kódu souboru manifestu:

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Další informace o souboru manifestu naleznete ve formátu manifestu pro tvůrce nástrojů nasazení .NET.NET Aspire.

Vygenerovaná šablona Bicep navíc obsahuje parametr existingResourceName, který lze použít k odkazování na existující Azure prostředek. Zvažte následující vygenerovanou šablonu Bicep:

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

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Další informace o generovaných šablonách Bicep najdete v tématu Infrastruktura jako kód a zvažte další rozhraní API pro publikování.

Konfigurujte existující Azure zdroje ve všech režimech

Metoda AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) se používá, když distribuovaná aplikace běží v režimu spustit nebo publikovat. Vzhledem k tomu, že metoda AsExisting funguje v obou scénářích, podporuje pouze parametrizovaný odkaz na název prostředku nebo název skupiny prostředků. Tento přístup pomáhá zabránit použití stejného prostředku v testovacím i produkčním prostředí.

Pokud chcete Azure prostředek označit jako existující, zavolejte metodu AsExisting v tvůrci prostředků. Podívejte se na následující příklad:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Předchozí kód:

• Vytvoří novou instanci builder.
• Přidá do tvůrce parametr s názvem existingServiceBusName.
• Přidá do konstruktéra Azure Service Bus prostředek s názvem messaging.
• Zavolá metodu AsExisting v tvůrci prostředků serviceBus a předá parametr existingServiceBusName.
• Do prostředku serviceBus přidá frontu s názvem queue.

Přidejte existující prostředky Azure s připojovacími řetězci

.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á v kontextu spouštění hostitele aplikace pro podmíněné přidání připojovacího řetězce do modelu aplikace.

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á zdroj úložiště Azure 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í . V režimu spuštění připojovací řetězec odpovídá konfigurační hodnotě viditelné pro hostitele aplikace. Předpokládá se, že jsou nakonfigurovaná všechna přiřazení rolí pro cílový prostředek. 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.

Na rozdíl od existujících prostředků modelovaných pomocí prvotřídního rozhraní API AsExisting , stávající prostředky modelované jako připojovací řetězce nelze rozšířit o další přiřazení rolí nebo přizpůsobení infrastruktury.

Publikovat jako aplikaci kontejneru Azure

.NET .NET Aspire vám umožňuje publikovat primitivní prostředky jako Azure Container Apps, což je bezserverová platforma snižující správu infrastruktury. Podporované typy prostředků zahrnují:

• ContainerResource: Představuje zadaný kontejner.
• ExecutableResource: Představuje zadaný spustitelný proces.
• ProjectResource: Představuje zadaný projekt .NET.

K publikování těchto prostředků použijte následující rozhraní API:

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

Tato rozhraní API konfigurují prostředek, který se má publikovat jako Azure Container App, a implicitně volají AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder), aby do hostitele vaší aplikace přidaly potřebnou infrastrukturu a soubory Bicep. Jako příklad vezměte v úvahu následující kód:

var builder = DistributedApplication.CreateBuilder();

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

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

Předchozí kód:

• Vytvoří novou instanci builder.
• Přidá do tvůrce parametr s názvem env.
• Přidá do sestavovacího nástroje projekt s názvem api.
• Volá metodu PublishAsAzureContainerApp v tvůrci prostředků api a předává výraz lambda, který konfiguruje infrastrukturu Azure Container App – kde infra je AzureResourceInfrastructure a app je ContainerApp.
  • Přidá proměnnou prostředí s názvem Hello do aplikace kontejneru pomocí parametru env.
  • Metoda AsProvisioningParameter se používá ke zpracování env buď jako nový prvek ProvisioningParameter v infrastruktuře, nebo znovu použije existující parametr bicep, pokud již existuje se stejným názvem.

Další informace najdete v tématech ContainerApp a AsProvisioningParameter.

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 přímo volat žádné API pro provisioning.

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:

• Azure. Přizpůsobení nasazení:
  • Nakonfigurujte infrastrukturu: Přizpůsobte infrastrukturu zdrojů Azure.
  • Přidat infrastrukturu Azure: Ručně přidejte infrastrukturu do hostitelské aplikace Azure.
• Použití vlastních šablon Bicep:
  • Referenční soubory Bicep: Přidat odkaz na soubor Bicep na disku.
  • Odkaz na Bicep v řádku: Přidejte vloženou šablonu Bicep.

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 rozhraní API pro integraci hostování pro přidání zdrojů 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 lokální nastavení. Další informace naleznete v lokálním Azure poskytová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 používají tyto knihovny na pozadí 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 hostingové integrace .NET AspireAzure zpřístupňují různé prostředky Azure; 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, je třeba provést zřetězení 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 pro přizpůsobení úložné infrastruktury Azure.
  • Získá provizovatelné prostředky.
  • Filtruje do jediného StorageAccount.
  • Přiřadí parametr storage-sku vlastnosti StorageAccount.Sku:
    • Nová instance StorageSku má přiřazenou vlastnost Name z výsledku rozhraní API AsProvisioningParameter.

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 se 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á projekt s názvem worker do kompilátoru.
• 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 přenést výstup z 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.

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 odkazování na soubory Bicep a přizpůsobení prostředků Azure.

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

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

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 naleznete v části 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 projektu hostitele aplikace . 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 Bicep inline

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. Chcete-li 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 poté přidána do kolekce prostředků aplikace pod názvem "ai". Tento příklad zajišťuje AI prostředek Azure.

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 obsahující pole ř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:

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ískat výstupy z referencí 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, která definuje output nazvané 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, který je tajný, se pak předá jako proměnná prostředí (ConnectionStrings__cosmos) projektu api. Tato proměnná prostředí slouží k připojení k instanci Cosmos DB.

Při nasazení tohoto prostředku základní mechanismus nasazení automaticky odkazuje na tajemství 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.

Publikování

Při publikování aplikace se Bicep vygenerované pro zřizování 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).