.NET Aspire Azure integrációk áttekintése

Azure a legnépszerűbb felhőplatform .NET alkalmazásoklétrehozásához és üzembe helyezéséhez. A SDK lehetővé teszi a szolgáltatások egyszerű kezelését és használatát. .NET Aspire integrációkat biztosít Azure szolgáltatásokkal, ahol szabadon adhat hozzá új erőforrásokat, vagy csatlakozhat a meglévőkhöz. Ez a cikk részletezi a Azure integrációk néhány gyakori aspektusát .NET Aspire-ban, és azt a célt szolgálja, hogy segítsen megérteni a használatukat.

Azure-erőforrások hozzáadása

Minden .NET AspireAzure üzemeltetési integráció Azure erőforrásokat tesz elérhetővé, és konvenció szerint AddAzure* API-k használatával kerülnek hozzáadásra. Amikor hozzáadja ezeket az erőforrásokat az .NET Aspire alkalmazás gazdagépéhez, azok egy Azure szolgáltatást megjelölnek. A AddAzure* API egy IResourceBuilder<T> ad vissza, ahol TAzure erőforrás típusa. Ezek a IResourceBuilder<T> (szerkesztő) felületek egy folyékony API-t biztosítanak, amely lehetővé teszi az alapul szolgáló Azure erőforrás konfigurálását az alkalmazásmodell. Vannak API-k az új Azure erőforrások hozzáadásához, az erőforrások meglévőként való megjelöléséhez és az erőforrások különböző végrehajtási környezetekben való viselkedésének konfigurálásához.

Tipikus fejlesztői élmény

Ha az .NET Aspire alkalmazásgazda tartalmaz Azure erőforrásokat, és helyben futtatja őket (ami tipikus a fejlesztőknél, amikor F5-öt nyomnak, vagy dotnet run tapasztalatról van szó), a Azure erőforrások kiépítésre kerülnek az Azure előfizetésedben. Ez lehetővé teszi, hogy fejlesztőként helyileg hibakeresést hajtson el rajtuk az alkalmazásgazda környezetében.

.NET .NET Aspire a költségek minimalizálását a alapszintű vagy standardkészletmegőrzési egység (SKU) használatával éri el a Azure integrációi során. Bár ezek az ésszerű alapértelmezett beállítások biztosítottak, igényeinek megfelelően testre szabhatja a Azure erőforrásokat. Emellett egyes integrációk támogatják emulátorokat vagy tárolókat, amelyek hasznosak a helyi fejlesztéshez, teszteléshez és hibakereséshez. Alapértelmezés szerint az alkalmazás helyi futtatásakor a Azure erőforrások a tényleges Azure szolgáltatást használják. Konfigurálhatja azonban őket helyi emulátorok vagy tárolók használatára, elkerülve a tényleges Azure szolgáltatással kapcsolatos költségeket a helyi fejlesztés során.

Helyi emulátorok

Néhány Azure szolgáltatás emulálható helyi futtatáshoz. Jelenleg .NET Aspire az alábbi Azure emulátorokat támogatja:

Ha azt szeretné, hogy a Azure erőforrásai a helyi emulátorokat használják, láncba kell kapcsolnia a RunAsEmulator metódust az Azure erőforrás-szerkesztőben. Ez a metódus úgy konfigurálja a Azure erőforrást, hogy a helyi emulátort használja a tényleges Azure szolgáltatás helyett.

Helyi tárolók

Egyes Azure erőforrások helyileg helyettesíthetők nyílt forráskódú vagy helyszíni tárolók használatával. Ha helyileg szeretne Azure erőforrást cserélni egy tárolóban, láncba kell kapcsolnia egy hívást a RunAsContainer metódushoz az Azure erőforrás-szerkesztőben. Ez a módszer úgy konfigurálja a Azure erőforrást, hogy a szolgáltatás tárolóalapú verzióját használja a helyi fejlesztéshez és teszteléshez a tényleges Azure szolgáltatás helyett.

Jelenleg a .NET Aspire a következő Azure szolgáltatásokat támogatja tárolóként:

Azure integrációs API-k ismertetése

.NET .NET Aspire erőssége abban rejlik, hogy képes egy csodálatos fejlesztői belső ciklust biztosítani. A Azure integrációi nem különböznek. Az összes Azure erőforrásban megosztott közös API-kat és mintákat biztosítanak. Ezek az API-k és minták úgy lettek kialakítva, hogy Azure erőforrások egységesen kezelhetők legyenek.

Az előző tárolók szakaszban láthatta, hogyan futtathat helyileg Azure szolgáltatásokat a tárolókban. Ha ismeri a .NET.NET Aspire, felmerülhet a kérdés, hogy a helyi AddAzureRedis("redis").RunAsContainer() tároló lekéréséhez docker.io/library/redis hívása miben különbözik a AddRedis("redis")- mivel mindkettő ugyanazt a helyi tárolót eredményezi.

A válasz az, hogy nincs különbség helyi futtatás esetén. A közzétételükkor azonban különböző erőforrásokat kap:

Ugyanez igaz az SQL- és PostgreSQL-szolgáltatásokra is:

A futtatási és közzétételi módok közötti különbségről további információt .NET.NET Aspire alkalmazásgazda: Végrehajtási környezetcímű témakörben talál.

API-k Azure erőforrások különböző módokon való kifejezéséhez

Az elosztott alkalmazások szerkesztője, amely a alkalmazásgazda részét képezi, a szerkesztő mintáját használja, hogy AddAzure* erőforrásokat a alkalmazásmodell számára. A fejlesztők konfigurálhatják ezeket az erőforrásokat, és különböző végrehajtási környezetekben határozhatják meg működésüket. Azure üzemeltetési integrációk API-kat biztosítanak, amelyek meghatározzák, hogyan kell ezeket az erőforrásokat "közzétenni" és "futtatni".

Amikor az alkalmazásgazda végrehajtódik, a végrehajtási környezet határozza meg, hogy az alkalmazásgazda Run vagy Publish módban van-e. Ezeknek az API-knak az elnevezési konvenciók az erőforrás tervezett műveletét jelzik.

Az alábbi táblázat a Azure erőforrások kifejezésére használt elnevezési konvenciók összegzését foglalja össze:

További információ a végrehajtási módokról: Végrehajtási környezet.

Általános futtatási módú API-használati esetek

A RunAsExisting akkor használja, ha a futtatókörnyezetben dinamikusan kell kezelnie egy meglévő erőforrást anélkül, hogy üzembe kellene helyeznie vagy frissítenie kellene. Használja a PublishAsExisting a meglévő erőforrások üzembehelyezési konfiguráció részeként történő deklarálásakor, biztosítva a megfelelő hatókörök és engedélyek alkalmazását. Végül használja a AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>), amikor mindkét konfigurációban deklarálja a meglévő erőforrásokat, és a hivatkozások paraméterezésére van szükség.

Az IsExisting(IResource)IResource bővítménymetódus meghívásával lekérdezheti, hogy egy erőforrás meglévő erőforrásként van-e megjelölve. További információ: Meglévő Azure erőforrások használata.

Meglévő Azure erőforrások használata

.NET Aspire támogatja a meglévő Azure erőforrások hivatkozását. Egy meglévő erőforrást a PublishAsExisting, RunAsExistingés AsExisting API-kkal jelölhet meg. Ezek az API-k lehetővé teszik a fejlesztők számára, hogy már üzembe helyezett Azure erőforrásokra hivatkozhassanak, konfigurálják őket, és bicep-sablonok használatával létrehozhassanak megfelelő üzembehelyezési jegyzékeket.

Az ezekkel az API-kkal hivatkozott meglévő erőforrások bővíthetők szerepkör-hozzárendelésekkel és egyéb testreszabásokkal, amelyek .NET.NET Aspire-infrastruktúrával, mint kódképességekkelérhetők el. Ezek az API-k a Bicep-sablonokkal üzembe helyezhető Azure erőforrásokra korlátozódnak.

Meglévő Azure-erőforrások konfigurálása futtatási módhoz

A RunAsExisting metódust akkor használja a rendszer, ha egy elosztott alkalmazás futtatás módban fut. Ebben a módban feltételezi, hogy a hivatkozott Azure erőforrás már létezik, és az erőforrás kiépítése nélkül integrálható vele a végrehajtás során. Ha meglévőként szeretne megjelölni egy Azure erőforrást, hívja meg a RunAsExisting metódust az erőforrás-szerkesztőben. Vegye figyelembe a következő példát:

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

Az előző kód:

• Létrehoz egy új builder-példányt.
• Hozzáad egy existingServiceBusName nevű paramétert az építőhöz.
• Hozzáad egy Azure Service Bus erőforrást messaging névvel az építőhöz.
• Meghívja a RunAsExisting metódust az serviceBus erőforrás-készítőn, átadva a existingServiceBusName paramétert – másik lehetőségként használhatja a string paraméter túlterhelését.
• Hozzáad egy queue nevű sort a serviceBus erőforráshoz.

A Service Bus paraméterhivatkozás alapértelmezés szerint ugyanabban a Azure erőforráscsoportban van. Ha azonban egy másik erőforráscsoportban van, az erőforráscsoportot explicit módon paraméterként is átadhatja, hogy helyesen adja meg a megfelelő erőforráscsoport-csoportosítást.

Meglévő Azure erőforrások konfigurálása közzétételi módhoz

A PublishAsExisting metódus akkor használatos "közzétételi" módban, ha a szándék egy már meglévő Azure erőforrás deklarálása és hivatkozása közzétételi módban. Ez az API lehetővé teszi olyan jegyzékek és sablonok létrehozását, amelyek olyan erőforrásdefiníciókat tartalmaznak, amelyek a Bicep meglévő erőforrásaihoz lesznek megfeleltetve.

Ha egy Azure erőforrást a "közzététel" módban meglévőként szeretne megjelölni, hívja meg a PublishAsExisting metódust az erőforrás-szerkesztőben. Vegye figyelembe a következő példát:

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

Az előző kód:

• Létrehoz egy új builder-példányt.
• Hozzáad egy existingServiceBusName nevű paramétert az építőhöz.
• Hozzáad egy Azure Service Bus erőforrást, amelynek neve messaging, az építőhöz.
• Meghívja a PublishAsExisting metódust az serviceBus erőforrás-készítőn, átadva a existingServiceBusName paramétert – másik lehetőségként használhatja a string paraméter túlterhelését.
• Hozzáad egy queue nevű üzenetsort a serviceBus erőforráshoz.

Az alkalmazás gazdaprogramjának közzétételi módban történő végrehajtását követően a létrehozott manifesztfájl tartalmazni fogja a existingResourceName paramétert, amely a meglévő Azure erőforrásra való hivatkozásra használható. Vegye figyelembe a következő részleges, generált részletet a jegyzékfájlban:

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

További információ a jegyzékfájl formátumáról a telepítőeszköz-készítők számára: .NET.NET Aspire.

Emellett a létrehozott Bicep-sablon tartalmazza a existingResourceName paramétert, amely a meglévő Azure erőforrásra való hivatkozásra használható. Fontolja meg a következő automatikusan generált Bicep sablont:

@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

A létrehozott Bicep-sablonokról további információért lásd: Infrastruktúra kódként, és tekintse meg a többi közzétételi API-t.

Meglévő Azure erőforrások konfigurálása minden módban

A AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) metódus akkor használatos, ha az elosztott alkalmazás "futtatás" vagy "közzététel" módban fut. Mivel a AsExisting metódus mindkét forgatókönyvben működik, csak az erőforrás vagy erőforráscsoport nevére mutató paraméteres hivatkozást támogat. Ez a megközelítés segít megakadályozni, hogy ugyanazt az erőforrást mind a tesztelési, mind az éles környezetben használják.

Ha meglévőként szeretne megjelölni egy Azure erőforrást, hívja meg a AsExisting metódust az erőforrás-szerkesztőben. Vegye figyelembe a következő példát:

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

Az előző kód:

• Létrehoz egy új builder-példányt.
• Hozzáad egy existingServiceBusName nevű paramétert az építőhöz.
• Hozzáad egy Azure Service Bus erőforrást, amelynek neve messaging, az építőhöz.
• Meghívja a AsExisting metódust az serviceBus erőforrás-készítőn, és átadja a existingServiceBusName paramétert.
• Hozzáad egy queue nevű üzenetsort a serviceBus erőforráshoz.

Meglévő Azure-erőforrások hozzáadása kapcsolati karakterláncokkal

.NET .NET Aspire lehetővé teszi, hogy kapcsolódjon a meglévő erőforrásokhoz, beleértve Azure erőforrásokat is. A kapcsolati sztringek kifejezése akkor hasznos, ha meglévő Azure erőforrásokat szeretne használni a .NET Aspire alkalmazásban. A AddConnectionString API-t az alkalmazásgazda végrehajtási környezetével használjuk, hogy feltételesen hozzáadjon egy kapcsolati sztringet az alkalmazásmodellhez.

Vegye figyelembe a következő példát, amelyben közzétételi módban hozzáad egy Azure Storage-erőforrást, miközben futtatási módban egy kapcsolati sztringet ad hozzá egy meglévő Azure Storagehoz.

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

Az előző kód:

• Létrehoz egy új builder-példányt.
• Hozzáad egy Azure nevű storage Storage-erőforrást "közzétételi" módban.
• Kapcsolati láncot ad hozzá egy meglévő Azure tárolóhoz, amely a storage nevet viseli, "futtatás" módban.
• Hozzáad egy api nevű projektet az építőhöz.
• A api projekt a módtól függetlenül hivatkozik a storage erőforrásra.

A fogyasztó API-projekt a kapcsolati sztring adatait használja anélkül, hogy tudná, az alkalmazásgazda hogyan konfigurálta azt. "Közzétételi módban a kód egy új Azure tárolási erőforrást ad hozzá – ami ennek megfelelően megjelenik a üzembehelyezési jegyzékben." Futtatás módban a kapcsolati sztring egy konfigurációs értéknek felel meg, amely látható az alkalmazás hosztja számára. Feltételezzük, hogy a célerőforrás összes szerepkör-hozzárendelése konfigurálva van. Ez azt jelenti, hogy valószínűleg konfigurál egy környezeti változót vagy egy felhasználói titkos kulcsot a kapcsolati sztring tárolásához. A konfiguráció feloldása a ConnectionStrings__storage (vagy ConnectionStrings:storage) konfigurációs kulccsal történik. Ezek a konfigurációs értékek az alkalmazás futtatásakor tekinthetők meg. További információ: Erőforrás részletei.

Az első osztályú AsExisting API-val modellezett meglévő erőforrásoktól eltérően a kapcsolati karakterláncokként modellezett meglévő erőforrások nem bővíthetők további szerepkör-hozzárendelésekkel vagy infrastruktúra-testreszabásokkal.

Közzététel Azure konténeralkalmazásként

.NET .NET Aspire lehetővé teszi a primitív erőforrások közzétételét Azure Container Apps, egy kiszolgáló nélküli platformként, amely csökkenti az infrastruktúra kezelését. Támogatott erőforrástípusok többek között az alábbiak:

• ContainerResource: Egy megadott tárolót jelöl.
• ExecutableResource: Egy megadott végrehajtható folyamatot jelöl.
• ProjectResource: Egy megadott .NET projektet jelöl.

Az erőforrások közzétételéhez használja a következő API-kat:

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

Ezek az API-k úgy konfigurálják az erőforrást, hogy [Azure] tárolóalkalmazásként legyen közzétéve, és implicit módon meghívja a [AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder)], hogy hozzáadja a szükséges infrastruktúrát és Bicep-fájlokat az alkalmazás kiszolgálójához. Példaként tekintse meg a következő kódot:

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

Az előző kód:

• Létrehoz egy új builder-példányt.
• Hozzáad egy env nevű paramétert a készítőhöz.
• Hozzáad egy api nevű projektet az építőhöz.
• Meghívja a PublishAsAzureContainerApp metódust az api erőforrás-készítőn, és átad egy lambda kifejezést, amely konfigurálja a Azure Container App infrastruktúráját – ahol infra a AzureResourceInfrastructure, a app pedig a ContainerApp.
  • Hozzáad egy Hello nevű környezeti változót a tárolóalkalmazáshoz a env paraméter használatával.
  • A AsProvisioningParameter módszer arra szolgál, hogy a env-et az infrastruktúrában új ProvisioningParameter-ként kezelje, vagy újrafelhasználjon egy meglévő bicep paramétert, ha ilyen nevű már létezik.

További információ: ContainerApp és AsProvisioningParameter.

Infrastruktúra kódként

A Azure.NET SDK biztosítja a 📦Azureszolgáltatás-specifikus NuGet-csomagot és egy sor Azure kiépítési csomagot. Ezek a Azure telepítési könyvtárak megkönnyítik a Azure infrastruktúra deklaratív módon történő, natív megadását .NET-ben. Az API-k lehetővé teszik, hogy objektumorientált infrastruktúrát írjon C#-ban, ami a Bicep-et eredményezi. Bicep egy tartományspecifikus nyelv (DSL)Azure erőforrások deklaratív üzembe helyezéséhez.

Bár manuálisan is ki lehet építeni Azure erőforrásokat, .NET Aspire leegyszerűsíti a folyamatot azáltal, hogy api-kat biztosít a Azure erőforrások kifejezéséhez. Ezek az API-k kiterjesztési módszerekként érhetők el a .NET AspireAzure hosztoló könyvtárakban, és kibővítik a IDistributedApplicationBuilder interfészt. Amikor Azure erőforrásokat ad hozzá az alkalmazás hostjához, azok implicit módon hozzáadják a megfelelő erőforrás-kezelési funkciót. Más szóval nem kell közvetlenül meghívnia a kiépítési API-kat.

Mivel a .NET Aspire modellek a Azure erőforrásokat modellezik a Azure üzemeltetési integrációkban, a Azure SDK-t használják ezeknek az erőforrásoknak a létrehozásához. Bicep-fájlok jönnek létre, amelyek meghatározzák a szükséges Azure erőforrásokat. A létrehozott Bicep-fájlok a jegyzékfájl mellett jelennek meg az alkalmazás közzétételekor.

A létrehozott Bicep-fájlok többféleképpen is befolyásolhatók:

• Azure.Ellátási testreszabás:
  • Infrastruktúra-konfigurálása: Azure erőforrás-infrastruktúra testreszabása.
  • Azure infrastruktúra hozzáadása: A Azure infrastruktúra manuális hozzáadása az alkalmazáshostjához.
• Egyéni Bicep-sablonok alkalmazása:
  • Bicep fájl referenciák: Hivatkozás hozzáadása a lemezen lévő Bicep-fájlhoz.
  • Hivatkozás a Bicep beágyazott: Beágyazott Bicep-sablon hozzáadása.

Helyi kiépítés és Azure.Provisioning

A terminológiai összemosás elkerülése és a "kiépítés" egyértelműsítése érdekében fontos tisztában lenni a helyi kiépítés és a Azure kiépítésközötti különbségtétellel.

• Helyi kiépítés:

  Ha a Azure integrációs API-k bármelyikét meghívja Azure erőforrások hozzáadásához, a AddAzureProvisioning(IDistributedApplicationBuilder) API implicit módon lesz meghívva. Ez az API azokat a szolgáltatásokat regisztrálja a függőséginjektálási (DI) tárolóban, amelyeket a Azure erőforrások kiépítése során használnak, amikor az alkalmazásgazda elindul. Ezt a fogalmat helyi biztosításnéven nevezzük. További információkért lásd: Helyi Azure provízió.

• Azure.Provisioning:

  Azure.Provisioning a NuGet-csomagra hivatkozik, és olyan kódtárak készlete, amelyek lehetővé teszi a C# használatát a Bicep létrehozásához. A Azure tárhely-integrációk a .NET Aspire-ben ezeket a könyvtárakat használják a háttérben, hogy olyan Bicep-fájlokat hozzanak létre, amelyek meghatározzák a szükséges Azure erőforrásokat. További információért tekintse meg a Azure.Provisioning testreszabási-t.

Azure.Provisioning testreszabás

Minden .NET AspireAzure üzemeltetési integráció különböző Azure erőforrásokat tesz elérhetővé, és ezek mind a AzureProvisioningResource típusú alosztályok, amelyek maguk öröklik a AzureBicepResource. Ez lehetővé teszi az ilyen típusú, általánosan korlátozott bővítmények használatát, így a fluent API-k tetszés szerint testre szabhatják az infrastruktúrát. Bár .NET.NET Aspire alapértelmezett beállításokat biztosít, szabadon befolyásolhatja a létrehozott Bicep-et ezekkel az API-kkal.

Infrastruktúra konfigurálása

Függetlenül attól, hogy milyen Azure erőforrással dolgozik, a mögöttes infrastruktúra konfigurálásához a ConfigureInfrastructure bővítménymetódushoz kell láncolnia a hívást. Ezzel a módszerrel testre szabhatja az Azure erőforrás infrastruktúráját egy configureAction<AzureResourceInfrastructure>típusú delegált átadásával. A AzureResourceInfrastructure típus a Azure.Provisioning.Infrastructurealosztálya. Ez a típus egy hatalmas API-felületet tesz elérhetővé a Azure erőforrás mögöttes infrastruktúrájának konfigurálásához.

Vegye figyelembe a következő példát:

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

Az előző kód:

• Hozzáad egy storage-skunevű paramétert.
• Hozzáadja a Azure Storage-t a AddAzureStorage API-hoz, amely storagenévre hallgat.
• A ConfigureInfrastructure-hez láncolt hívásokkal testreszabhatja a Azure tárhely-infrastruktúrát.
  • Lekérdezi a rendelkezésre bocsátható erőforrásokat.
  • Egyetlen StorageAccount-ra szűr.
  • Hozzárendeli a storage-sku paramétert a StorageAccount.Sku tulajdonsághoz:
    • A StorageSku új példányának Name tulajdonságát a AsProvisioningParameter API eredményéből rendelik hozzá.

Ez a példa egy külső paraméter a Azure Storage-infrastruktúrába való áramlását szemlélteti, így a létrehozott Bicep-fájl tükrözi a kívánt konfigurációt.

Azure infrastruktúra hozzáadása

Nem minden Azure szolgáltatás érhető el .NET Aspire integrációként. Bár lehetséges, hogy később válnak elérhetővé, továbbra is biztosíthatja a Azure.Provisioning.* könyvtárakban elérhető szolgáltatásokat. Képzeljen el egy olyan forgatókönyvet, amelyben egy munkafolyamat szolgáltatás felelős egy Azure Konténer-regiszter kezeléséért. Képzelje el, hogy egy alkalmazásgazda projekt függőséget vesz fel a 📦Azure.Provisioning.ContainerRegistry NuGet-csomagra.

A AddAzureInfrastructure API-val hozzáadhatja a Azure Container Registry-infrastruktúrát az alkalmazásgazda számára:

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

Az előző kód:

• AddAzureInfrastructure hívása egy acr névvel.
• Egy configureInfrastructure delegáltat biztosít a Azure Container Registry-infrastruktúra testreszabásához:
  • Létrehoz egy ContainerRegistryService objektumot a(z) acr névvel és egy standard SKU-val.
  • Hozzáadja a Azure Container Registry szolgáltatást a infra változóhoz.
  • Létrehoz egy ProvisioningOutput a névvel registryName, a típusával string, és egy értékkel, amely megfelel a Azure tárolóregisztrációs nevének.
  • Hozzáadja a kimenetet a infra változóhoz.
• Hozzáad egy worker nevű projektet az építőhöz.
• Összekapcsol egy hívást a WithEnvironment-val, hogy a projekt ACR_REGISTRY_NAME környezeti változóját a registryName kimenetének értékére állítsa.

A funkció bemutatja, hogyan adhat hozzá Azure infrastruktúrát az alkalmazásgazdaprojekthez, még akkor is, ha a Azure szolgáltatás nem érhető el közvetlenül .NET Aspire integrációként. Azt is bemutatja, hogyan áramolhat a Azure Tárolóregisztrációs adatbázis kimenete egy függő projekt környezetébe.

Fontolja meg az eredményként kapott Bicep-fájlt:

@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

A Bicep-fájl az Azure API által meghatározott AddAzureInfrastructure Container Registry kívánt konfigurációját tükrözi.

Egyéni Bicep-sablonok használata

Amikor célba veszi a Azure-t mint a kívánt felhőszolgáltatót, a Bicep használatával kódként definiálhatja az infrastruktúrát. Célja, hogy drasztikusan leegyszerűsítse a szerzői élményt egy tisztább szintaxissal, és jobban támogassa a modularitást és a kód újrafelhasználását.

Bár .NET.NET Aspire előre összeállított Bicep-sablonokat biztosít, előfordulhat, hogy testre szeretné szabni a sablonokat, vagy sajátot szeretne létrehozni. Ez a szakasz ismerteti a Bicep-sablonok testreszabásához használható fogalmakat és a hozzájuk tartozó API-kat.

A üzembe helyezési történetének részeként a () a projekt megértését és a üzembe helyezésének lehetőségét biztosítja. A azd parancssori felület a Bicep-sablonok segítségével telepíti az alkalmazást Azure-re.

Aspire.Hosting.Azure csomag telepítése

Ha Bicep-fájlokra szeretne hivatkozni, lehetséges, hogy nem használja a Azure hosting-integrációkat. Ebben az esetben továbbra is hivatkozhat Bicep-fájlokra a Aspire.Hosting.Azure csomag telepítésével. Ez a csomag biztosítja a Bicep-fájlok hivatkozásához és a Azure erőforrások testreszabásához szükséges API-kat.

Ezen funkciók bármelyikének használatához a 📦Aspire.Hosting.Azure NuGet-csomagot telepíteni kell:

dotnet add package Aspire.Hosting.Azure

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

További információ: dotnet add package vagy csomagfüggőségek kezelése a .NET alkalmazásokban.

Mit várhatunk a példáktól?

Az ebben a szakaszban szereplő összes példa feltételezi, hogy a Aspire.Hosting.Azure névteret használja. Ezenkívül a példák feltételezik, hogy van egy IDistributedApplicationBuilder példányod.

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Alapértelmezés szerint, amikor bármely Bicep-hez kapcsolódó API-t hív meg, a rendszer egy hívást is kezdeményez a AddAzureProvisioning felé, amely támogatja a Azure erőforrások dinamikus létrehozását az alkalmazás indításakor. További információkért lásd: Helyi előkészítés és Azure.Provisioning.

Hivatkozás Bicep-fájlokra

Tegyük fel, hogy egy storage.bicep nevű fájlban van egy Bicep-sablon, amely egy Azure Storage-fiókot helyez üzembe:

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

Ha a lemezen lévő Bicep-fájlra szeretne hivatkozni, hívja meg a AddBicepTemplate metódust. Vegye figyelembe a következő példát:

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

Az előző kód egy ../infra/storage.bicephelyen található Bicep-fájlra mutató hivatkozást ad hozzá. A fájl elérési útjainak relatívnak kell lenniük a alkalmazáshoz kapcsolódó projekthez viszonyítva. Ez a hivatkozás hozzáad egy AzureBicepResource-t az alkalmazás erőforrásgyűjteményéhez a "storage" névvel, és az API visszaad egy IResourceBuilder<AzureBicepResource> példányt, amely az erőforrás további testreszabására használható.

Bicep referencia soron belül

Bár a leggyakoribb forgatókönyv a Bicep-fájl lemezen való használata, a Bicep-sablonokat beágyazottan is hozzáadhatja. A beágyazott sablonok akkor lehetnek hasznosak, ha egy sablont kódban szeretne definiálni, vagy ha dinamikusan szeretné létrehozni a sablont. Beágyazott Bicep-sablon hozzáadásához hívja meg a AddBicepTemplateString metódust a Bicep-sablont megadva string-ként. Vegye figyelembe a következő példát:

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

Ebben a példában a Bicep-sablon string beágyazottként van definiálva, és hozzáadásra kerül az alkalmazás erőforrásgyűjteményéhez "ai" néven. Ez a példa létrehoz egy Azure AI-erőforrást.

Paraméterek átadása Bicep-sablonoknak

Bicep támogatja aparaméterek elfogadását, amelyek a sablon viselkedésének testreszabására használhatók. Ha paramétereket szeretne átadni egy Bicep-sablonnak a .NET.NET Aspire-ből, láncolja a hívásokat a WithParameter metódussal az alábbi példában látható módon:

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

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

Az előző kód:

• Hozzáad egy "region" nevű paramétert a builder-példányhoz.
• A ../infra/storage.bicephelyen található Bicep-fájlra mutató hivatkozást ad hozzá.
• Átadja a "region" paramétert a Bicep-sablonnak, amely a standard paraméterértékeléssel kerül meghatározásra.
• Átadja a "storageName" paramétert a Bicep-sablonnak egy rögzített értékkel.
• A "tags" paramétert sztringtömbbel továbbítja a Bicep-sablonnak.

További információ: Külső paraméterek.

Jól ismert paraméterek

.NET .NET Aspire számos jól ismert paramétert biztosít, amelyek átadhatók a Bicep-sablonoknak. Ezek a paraméterek az alkalmazással és a környezettel kapcsolatos információk megadására szolgálnak a Bicep-sablonok számára. A következő jól ismert paraméterek érhetők el:

Egy jól ismert paraméter használatához adja meg a paraméter nevét a WithParameter metódusnak, például WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Nem adja át a jól ismert paraméterek értékeit, mivel .NET.NET Aspire az Ön nevében oldja fel őket.

Vegyünk egy példát, ahol egy Azure Event Grid-webhookot szeretne beállítani. A Bicep-sablont a következőképpen határozhatja meg:

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

Ez a Bicep-sablon számos paramétert határoz meg, beleértve a topicName, webHookEndpoint, principalId, principalTypeés az opcionális location. Ha ezeket a paramétereket a Bicep-sablonnak szeretné átadni, használja a következő kódrészletet:

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

• A webHookApi projekt a builderhivatkozásaként lesz hozzáadva.
• A topicName paraméter egy rögzített névértéket ad át.
• A webHookEndpoint paraméter olyan kifejezésként adódik át, amely meghatározza az URL-címet a api projekthivatkozások "https" végpontjáról a /hook útvonallal.
• A principalId és principalType paraméterek jól ismert paraméterekként lesznek átadva.

A jól ismert paraméterek konvencióalapúak, és az WithParameter API-val való átadáskor nem szabad megfelelő értékkel kiegészíteni. A jól ismert paraméterek leegyszerűsítenek néhány gyakori funkciót, például szerepkör-hozzárendeléseket, amikor hozzáadják a Bicep-sablonokhoz, ahogy az előző példában is látható. Szerepkör-hozzárendelésekre van szükség ahhoz, hogy az Event Grid webhook eseményeket küldjön a megadott végpontra. További információért lásd: Event Grid-adatküldő szerepkör-hozzárendelés.

Eredmények lekérése a Bicep-hivatkozásokból

A paraméterek Bicep-sablonoknak való átadása mellett kimeneteket is lekérhet a Bicep-sablonokból. Vegye figyelembe a következő Bicep-sablont, amely egy outputnevű endpoint-t definiál:

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

A Bicep egy endpointnevű kimenetet határoz meg. A Bicep-sablon kimenetének lekéréséhez hívja meg a GetOutput metódust egy IResourceBuilder<AzureBicepResource>-példányon a következő C#-kódrészletben látható módon:

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

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

Ebben a példában a Bicep-sablon kimenete egy endpoint változóban lesz lekérve és tárolva. Ezt a kimenetet általában környezeti változóként adná át egy másik, rá támaszkodó erőforrásnak. Ha például egy ASP.NET Core Minimális API-projektje volt, amely a végponttól függött, a kimenetet környezeti változóként továbbíthatja a projektnek a következő kódrészlet használatával:

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

További információért lásd: Bicep-kimenetek.

Titkos kódkimenetek lekérése Bicep-hivatkozásokból

A Bicep használatakor fontos, hogy kerülje a titkos kódok kimenetét. Ha egy kimenetet titkosnak tartunk, ami azt jelenti, hogy nem szabad naplókban vagy más helyeken elérhetővé tenni, akkor ennek megfelelően kell kezelni. Ez úgy érhető el, hogy a titkos kulcsot a Azure Key Vault tárolja, és a Bicep-sablonban hivatkozik rá. .NET Aspire Azure integrációja mintát biztosít a Bicep sablonból származó kimenetek biztonságos tárolásához azáltal, hogy lehetővé teszi az erőforrások számára, hogy a keyVaultName paraméterrel titkokat tároljanak Azure Key Vault-on.

Tekintsük példaként a következő Bicep-sablont, amely a titkos kódok kimenetének biztonságossá tételének fogalmát mutatja be:

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

Az előző Bicep-sablon számos más paraméter mellett egy keyVaultName paramétert vár. Ezután definiál egy Azure Cosmos DB erőforrást, és egy titkot helyez el a Azure Key Vault-be, connectionString néven, amely a Cosmos DB példányhoz tartozó teljes kapcsolati sztringet jelöli. A titkos kapcsolati sztring értékének eléréséhez használja a következő kódrészletet:

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

Az előző kódrészletben a cosmos Bicep-sablon a builderhivatkozásaként lesz hozzáadva. A connectionString titkos kimenet a Bicep-sablonból van visszaállítva, és egy változóban tárolódik. A titkos kimenet ezután környezeti változóként (ConnectionStrings__cosmos) továbbítja a api projektnek. Ez a környezeti változó a Cosmos DB-példányhoz való csatlakozásra szolgál.

Amikor az erőforrás üzembe van helyezve, az alapjául szolgáló telepítési mechanizmus automatikusan hivatkozik a titkos kulcsokra Azure Key Vault. A titkos kódok elkülönítésének garantálása érdekében .NET.NET Aspire forrásonként létrehoz egy Key Vaultot.

Könyvkiadás

Amikor közzéteszed az alkalmazást, a Azure által generált Bicep kiépítést használja a Azure Developer CLI a Azure erőforrások létrehozásához a Azure előfizetésedben. .NET .NET Aspire egy közzétételi jegyzékfájlt ad ki, amely a közzétételi folyamat fontos része is. A Azure Developer CLI egy parancssori eszköz, amely parancsokat biztosít Azure erőforrások kezeléséhez.

További információért a közzétételről és az üzembe helyezésről lásd a útmutatót, amely részletezi, hogyan lehet egy .NET Aspire projektet Azure Container Apps üzembe helyezni a Azure Developer CLI (részletes útmutató)használatával.