Dela via

översikt över .NET AspireAzure-integreringar

  • Artikel

Azure är den mest populära molnplattformen för att skapa och distribuera .NET program. Med Azure SDK för .NET kan du enkelt hantera och använda Azure tjänster. .NET Aspire tillhandahåller en uppsättning integreringar med Azure tjänster, där du kan lägga till nya resurser eller ansluta till befintliga. Den här artikeln beskriver några vanliga aspekter av alla Azure integreringar i .NET Aspire och syftar till att hjälpa dig att förstå hur du använder dem.

Lägg till Azure resurser

Alla .NET AspireAzure värdintegreringar exponerar Azure resurser och enligt konventionen läggs till med hjälp av AddAzure* API:er. När du lägger till dessa resurser i din .NET Aspire appvärd representerar de en Azure tjänst. AddAzure*-API:et returnerar en IResourceBuilder<T> där T är typen av Azure resurs. Dessa IResourceBuilder<T>-gränssnitt (builder) tillhandahåller ett flytande API som gör att du kan konfigurera den underliggande Azure-resursen inom -appmodellen. Det finns API:er för att lägga till nya Azure resurser, markera resurser som befintliga och konfigurera hur resurserna beter sig i olika körningskontexter.

Typisk utvecklarupplevelse

När din .NET Aspire-appvärd innehåller Azure-resurser och du kör den lokalt (typisk utvecklarmiljö med F5 eller dotnet run), så etableras resurserna Azure i din Azure-prenumeration. Detta gör att du som utvecklare kan felsöka dem lokalt i miljön för din appvärd.

.NET .NET Aspire syftar till att minimera kostnaderna genom att använda antingen Basic eller StandardStock Keeping Unit (SKU) för sina Azure integrationer. Även om dessa lämpliga standardvärden tillhandahålls kan du anpassa Azure resurser efter dina behov. Dessutom stöder vissa integreringar emulatorer eller containrar, som är användbara för lokal utveckling, testning och felsökning. När du kör appen lokalt använder Azure resurser som standard den faktiska Azure-tjänsten. Du kan dock konfigurera dem för att använda lokala emulatorer eller containrar, vilket undviker kostnader som är kopplade till den faktiska Azure tjänsten under den lokala utvecklingen.

Lokala emulatorer

Vissa Azure tjänster kan emuleras för att köras lokalt. För närvarande stöder .NET Aspire följande Azure emulatorer:

Hosting-integration Beskrivning
Azure Cosmos DB Anropa AzureCosmosExtensions.RunAsEmulator på IResourceBuilder<AzureCosmosDBResource> för att konfigurera Cosmos DB-resursen så att den emuleras med NoSQL API.
Azure Event Hubs Anropa AzureEventHubsExtensions.RunAsEmulator på IResourceBuilder<AzureEventHubsResource> för att konfigurera Event Hubs-resursen så att den emuleras.
Azure Service Bus Anropa AzureServiceBusExtensions.RunAsEmulator på IResourceBuilder<AzureServiceBusResource> för att konfigurera Service Bus-resursen så att den emuleras med hjälp av Service Bus-emulatorn.
Azure SignalR Service Anropa AzureSignalRExtensions.RunAsEmulator på IResourceBuilder<AzureSignalRResource> för att konfigurera resursen SignalR så att den emuleras med AzureSignalR-emulatorn.
Azure Storage Anropa AzureStorageExtensions.RunAsEmulator på IResourceBuilder<AzureStorageResource> för att konfigurera lagringsresursen så att den emuleras med Azurite.

Om du vill att dina Azure-resurser ska använda de lokala emulatorerna, kedja ett anrop till metoden RunAsEmulator på Azure-resursbyggaren. Den här metoden konfigurerar den Azure resursen så att den använder den lokala emulatorn i stället för den faktiska Azure-tjänsten.

Viktig

Att anropa någon av de tillgängliga RunAsEmulator-API:erna på en Azure resursbyggare påverkar inte publiceringsmanifestet. När du publicerar din app visar genererad Bicep-fil den faktiska Azure tjänsten, inte den lokala emulatorn.

Lokala containrar

Vissa Azure resurser kan ersättas lokalt med containrar med öppen källkod eller lokala containrar. Om du vill ersätta en Azure-resurs lokalt i en container gör du en anropkedja med metoden RunAsContainer på Azure-resursbyggaren. Den här metoden konfigurerar Azure resursen för att använda en containerbaserad version av tjänsten för lokal utveckling och testning, i stället för den faktiska Azure tjänsten.

För närvarande stöder .NET Aspire följande Azure tjänster i form av containrar:

Värdintegrering Detaljer
Azure Cache for Redis Anropa AzureRedisExtensions.RunAsContainer på IResourceBuilder<AzureRedisCacheResource> för att konfigurera den så att den körs lokalt i en container, baserat på docker.io/library/redis avbildningen.
Azure PostgreSQL flexibel Server Anropa AzurePostgresExtensions.RunAsContainer på IResourceBuilder<AzurePostgresFlexibleServerResource> för att konfigurera den för att köra lokalt i en container, baserat på docker.io/library/postgres bilden.
Azure SQL Server Anropa AzureSqlExtensions.RunAsContainer på IResourceBuilder<AzureSqlServerResource> för att konfigurera den så att den körs lokalt i en container, baserat på mcr.microsoft.com/mssql/server-bilden.

Notis

Precis som emulatorer påverkar inte anrop av RunAsContainer på en Azure-resursbyggare -publiceringsmanifestet. När du publicerar din app återspeglar den genererade Bicep-filen den faktiska Azure-tjänsten, inte den lokala containern.

Förstå Azure integrations-API:er

.NET .NET Aspirestyrkan ligger i dess förmåga att ge en fantastisk intern arbetscykel för utvecklare. De Azure integreringarna skiljer sig inte. De tillhandahåller en uppsättning vanliga API:er och mönster som delas över alla Azure resurser. Dessa API:er och mönster är utformade för att göra det enkelt att arbeta med Azure resurser på ett konsekvent sätt.

I föregående avsnitt fick du lära dig hur man kör Azure-tjänster lokalt i containrar. Om du är bekant med .NET.NET Aspirekanske du undrar hur anrop av AddAzureRedis("redis").RunAsContainer() för att hämta en lokal docker.io/library/redis container skiljer sig från AddRedis("redis")– eftersom båda resulterar i samma lokala container.

Svaret är att det inte finns någon skillnad när du kör lokalt. Men när de publiceras får du olika resurser:

API Körningsläge Publiceringsläge
AddAzureRedis("redis"). RunAsContainer() Lokal Redis behållare Azure Cache for Redis
AddRedis("redis") Lokal Redis behållare Azure Container-app med Redis bild

Detsamma gäller för SQL- och PostgreSQL-tjänster:

API Körningsläge Publiceringsläge
AddAzurePostgresFlexibleServer("postgres").RunAsContainer() Lokal PostgreSQL behållare Azure PostgreSQL flexibel Server
AddPostgres("postgres") Lokal PostgreSQL behållare Azure Container-app med PostgreSQL bild
AddAzureSqlServer("sql").RunAsContainer() Lokal SQL Server behållare Azure SQL Server
AddSqlServer("sql") Lokal SQL Server behållare Azure Container-app med SQL Server bild

Mer information om skillnaden mellan kör- och publiceringslägen finns i .NET.NET Aspire apphosting: Körmiljö.

API:er för att uttrycka Azure resurser i olika lägen

Det distribuerade applikationsverktyget, som är en del av applikationsvärd, använder byggarmönstret för att AddAzure* resurser för appmodellen. Utvecklare kan konfigurera dessa resurser och definiera sitt beteende i olika körningskontexter. Azure värdintegreringar tillhandahåller API:er för att ange hur dessa resurser ska "publiceras" och "köras".

När appvärden körs används körningskontexten för att avgöra om appvärden är i Run eller Publish läge. Namngivningskonventionerna för dessa API:er anger den avsedda åtgärden för resursen.

I följande tabell sammanfattas namngivningskonventionerna som används för att uttrycka Azure resurser:

Verksamhet API Beskrivning
Publicera PublishAsConnectionString<T>(IResourceBuilder<T>) Ändrar resursen som ska publiceras som en referens för anslutningssträngen i manifestet.
Publicera PublishAsExisting Använder en befintlig Azure resurs när programmet distribueras i stället för att skapa en ny.
Springa AzureSqlExtensions.RunAsContainer(IResourceBuilder<AzureSqlServerResource>, Action<IResourceBuilder<SqlServerServerResource>>)
AzureRedisExtensions.RunAsContainer(IResourceBuilder<AzureRedisCacheResource>, Action<IResourceBuilder<RedisResource>>)
RunAsContainer(IResourceBuilder<AzurePostgresFlexibleServerResource>, Action<IResourceBuilder<PostgresServerResource>>)		 Konfigurerar en motsvarande container att köras lokalt. Mer information finns i Lokala containrar.
Springa AzureCosmosExtensions.RunAsEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)
AzureSignalRExtensions.RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>)
AzureStorageExtensions.RunAsEmulator(IResourceBuilder<AzureStorageResource>, Action<IResourceBuilder<AzureStorageEmulatorResource>>)
AzureEventHubsExtensions.RunAsEmulator(IResourceBuilder<AzureEventHubsResource>, Action<IResourceBuilder<AzureEventHubsEmulatorResource>>)
AzureServiceBusExtensions.RunAsEmulator(IResourceBuilder<AzureServiceBusResource>, Action<IResourceBuilder<AzureServiceBusEmulatorResource>>)		 Konfigurerar den Azure resursen som ska emuleras. För mer information, se Lokala emulatorer.
Springa RunAsExisting Använder en befintlig resurs när programmet körs i stället för att skapa en ny.
Publicera och kör AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) Använder en befintlig resurs oavsett åtgärd.

Anteckning

Alla API:er är inte tillgängliga för alla Azure resurser. Vissa Azure resurser kan till exempel containeriseras eller emuleras, medan andra inte kan det.

Mer information om körningslägen finns i Körningskontext.

Användningsfall för API för allmänt körningsläge

Använd RunAsExisting när du behöver interagera dynamiskt med en befintlig resurs under körningen utan att behöva distribuera eller uppdatera den. Använd PublishAsExisting när du deklarerar befintliga resurser som en del av en distributionskonfiguration, vilket säkerställer att rätt omfång och behörigheter tillämpas. Använd slutligen AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) när du deklarerar befintliga resurser i båda konfigurationerna, med ett krav på att parameterisera referenserna.

Du kan fråga om en resurs har markerats som en befintlig resurs genom att anropa IsExisting(IResource)-tilläggsmetoden på IResource. Mer information finns i Använd befintliga Azure resurser.

Använda befintliga Azure resurser

.NET Aspire ger stöd för att referera till befintliga Azure resurser. Du markerar en befintlig resurs via API:erna PublishAsExisting, RunAsExistingoch AsExisting. Med dessa API:er kan utvecklare referera till redan distribuerade Azure resurser, konfigurera dem och generera lämpliga distributionsmanifest med hjälp av Bicep-mallar.

Befintliga resurser som refereras till med dessa API:er kan utökas med rolltilldelningar och andra anpassningar som är tillgängliga med .NET.NET Aspireinfrastruktur som kodfunktioner. Dessa API:er är begränsade till Azure resurser som kan distribueras med Bicep-mallar.

Konfigurera befintliga Azure resurser för körningsläge

Metoden RunAsExisting används när ett distribuerat program körs i körningsläge. I det här läget förutsätter det att den refererade resursen Azure redan finns och integrerar med den vid körning utan att behöva etablera resursen. Om du vill markera en Azure resurs som befintlig anropar du metoden RunAsExisting på resursverktyget. Tänk på följande exempel:

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

Föregående kod:

  • Skapar en ny builder instans.
  • Lägger till en parameter med namnet existingServiceBusName till byggaren.
  • Lägger till en Azure Service Bus resurs med namnet messaging till byggaren.
  • Anropar RunAsExisting-metoden på serviceBus-resursbyggaren genom att ange parametern existingServiceBusName — alternativt kan du använda string-parameterns överbelastning.
  • Lägger till en kö med namnet queue till den serviceBus resursen.

Som standard antas Service Bus-parameterreferensen finnas i samma Azure resursgrupp. Men om den finns i en annan resursgrupp kan du uttryckligen skicka resursgruppen som en parameter för att korrekt ange lämplig resursgrupp.

Konfigurera befintliga Azure resurser för publiceringsläge

Metoden PublishAsExisting används i "publiceringsläge" när avsikten är att deklarera och referera till en redan befintlig Azure resurs under publiceringsläget. Det här API:et underlättar skapandet av manifest och mallar som innehåller resursdefinitioner som mappar till befintliga resurser i Bicep.

Om du vill markera en Azure resurs som befintlig i för publiceringsläget anropar du metoden PublishAsExisting i resursverktyget. Tänk på följande exempel:

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

Föregående kod:

  • Skapar en ny builder instans.
  • Lägger till en parameter med namnet existingServiceBusName till byggaren.
  • Lägger till en Azure Service Bus resurs med namnet messaging till byggaren.
  • Anropar PublishAsExisting-metoden på serviceBus-resursbyggaren och skickar parametern existingServiceBusName. Alternativt kan du använda string-parameteröverbelastning.
  • Lägger till en kö med namnet queue till den serviceBus resursen.

Efter det att appvärden körs i publiceringsläge, kommer den genererade manifestfilen innehålla parametern existingResourceName, som kan användas för att referera till den befintliga resursen Azure. Överväg följande genererade partiella kodfragment i manifestfilen:

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

Mer information om manifestfilen finns i .NET.NET Aspire manifestformat för distributionsverktygsbyggare.

Dessutom innehåller den genererade Bicep-mallen parametern existingResourceName, som kan användas för att referera till den befintliga Azure resursen. Överväg följande genererade Bicep-mall:

@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

Mer information om de genererade Bicep-mallarna finns i Infrastruktur som kod och titta på andra publicerings-API:er.

Varning

När du interagerar med befintliga resurser som kräver autentisering ska du se till att den autentiseringsstrategi som du konfigurerar i .NET.NET Aspire programmodell överensstämmer med den autentiseringsstrategi som tillåts av den befintliga resursen. Det går till exempel inte att använda hanterad identitet mot en befintlig AzurePostgreSQL resurs som inte är konfigurerad för att tillåta hanterad identitet. På samma sätt, om en befintlig AzureRedis resurs har inaktiverat åtkomstnycklar, är det inte möjligt att använda åtkomstnyckelautentisering.

Konfigurera befintliga Azure resurser i alla lägen

Metoden AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) används när det distribuerade programmet körs i "kör" eller "publicera"-läge. Eftersom metoden AsExisting fungerar i båda scenarierna stöder den bara en parameterbaserad referens till resursnamnet eller resursgruppens namn. Den här metoden hjälper till att förhindra användning av samma resurs i både test- och produktionsmiljöer.

Om du vill markera en Azure resurs som befintlig anropar du metoden AsExisting på resursverktyget. Tänk på följande exempel:

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

Föregående kod:

  • Skapar en ny builder instans.
  • Lägger till en parameter med namnet existingServiceBusName till byggaren.
  • Lägger till en Azure Service Bus resurs med namnet messaging till byggaren.
  • Anropar AsExisting-metoden på serviceBus-resursverktyget och skickar parametern existingServiceBusName.
  • Lägger till en kö med namnet queue till den serviceBus resursen.

Lägg till redan befintliga Azure-resurser med anslutningssträngar

.NET .NET Aspire ger möjlighet att ansluta till befintliga resurser, inklusive Azure resurser. Det är användbart att specificera anslutningssträngar när du har de befintliga Azure-resurserna som du vill använda i din .NET Aspire-app. AddConnectionString-API:et används med appvärdens körningskontext för att villkorligt lägga till en anslutningssträng i appmodellen.

Not

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Tänk på följande exempel, där du i publicera läge lägger till en Azure Storage-resurs när du i kör läge lägger till en anslutningssträng i en befintlig Azure Storage:

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

Föregående kod:

  • Skapar en ny builder instans.
  • Lägger till en Azure Storage-resurs med namnet storage i "publiceringsläge".
  • Lägger till en anslutningssträng i en befintlig Azure-lagring som heter storage i körläge.
  • Lägger till ett projekt med namnet api till byggaren.
  • Projektet api refererar till resursen storage oavsett läge.

Det förbrukande API-projektet använder information om anslutningssträngen utan kunskap om hur appvärden konfigurerade den. I "publiceringsläge" lägger koden till en ny Azure Storage-resurs – som därefter skulle återspeglas i distributionsmanifestet. När anslutningssträngen är i "körningsläge" motsvarar den ett konfigurationsvärde som är synligt för appvärden. Det förutsätts att alla rolltilldelningar för målresursen är konfigurerade. Det innebär att du förmodligen konfigurerar en miljövariabel eller en användarhemlighet för att lagra anslutningssträngen. Konfigurationen löses från konfigurationsnyckeln ConnectionStrings__storage (eller ConnectionStrings:storage). Dessa konfigurationsvärden kan visas när appen körs. Mer information finns i Resursinformation.

Till skillnad från befintliga resurser som modelleras med den förstklassiga AsExisting API-kan befintliga resurser som modelleras som anslutningssträngar inte förbättras med ytterligare rolltilldelningar eller infrastrukturanpassningar.

Publicera som Azure containerapp

.NET .NET Aspire kan du publicera primitiva resurser som Azure Container Apps, en serverlös plattform som minskar infrastrukturhanteringen. Resurstyper som stöds omfattar:

Om du vill publicera dessa resurser använder du följande API:er:

Dessa API:er konfigurerar resursen så att den publiceras som en Azure Container App och anropar implicit AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) för att lägga till nödvändig infrastruktur och Bicep-filer till din applikationsvärd. Tänk till exempel på följande kod:

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

Föregående kod:

  • Skapar en ny builder instans.
  • Lägger till en parameter med namnet env till byggaren.
  • Lägger till ett projekt med namnet api till byggaren.
  • Anropar PublishAsAzureContainerApp-metoden på api-resursverktyget och skickar ett lambda-uttryck som konfigurerar Azure Container App-infrastrukturen– där infra är AzureResourceInfrastructure och app är ContainerApp.
    • Lägger till en miljövariabel med namnet Hello till containerappen med hjälp av parametern env.
    • Metoden AsProvisioningParameter används för att behandla env som antingen en ny ProvisioningParameter i infrastrukturen eller återanvänder en befintlig bicep-parameter om en med samma namn redan finns.

Mer information finns i ContainerApp och AsProvisioningParameter.

Infrastruktur som kod

Azure SDK för .NET innehåller 📦Azure.Provisioning NuGet-paket och en uppsättning tjänstspecifika Azure provisioningpaket. Dessa Azure provisioneringsbibliotek gör det enkelt att deklarativt specificera Azure infrastruktur inbyggt i .NET. Med deras API:er kan du skriva objektorienterad infrastruktur i C#, vilket resulterar i Bicep. Bicep är ett domänspecifikt språk (DSL) för att distribuera Azure resurser deklarativt.

Det är möjligt att etablera Azure resurser manuellt, men .NET Aspire förenklar processen genom att tillhandahålla en uppsättning API:er för att uttrycka Azure resurser. Dessa API:er är tillgängliga som tilläggsmetoder i .NET AspireAzure värdbibliotek, vilket utökar IDistributedApplicationBuilder-gränssnittet. När du lägger till Azure resurser till din appvärd, läggs lämplig provisioneringsfunktionalitet till implicit. Med andra ord behöver du inte anropa några etablerings-API:er direkt.

Eftersom .NET Aspire modeller Azure resurser inom Azure värdintegrationer används Azure SDK till att tillhandahålla dessa resurser. Bicep-filer genereras för att definiera de Azure-resurser som behövs. De genererade Bicep-filerna matas ut tillsammans med manifestfilen när du publicerar din app.

Det finns flera sätt att påverka de genererade Bicep-filerna:

Lokal provisionering och Azure.Provisioning

För att undvika att sammanblanda termer och för att förenkla förståelsen av "tilldelning" är det viktigt att förstå skillnaden mellan lokal tilldelning och Azure tilldelning:

  • Lokal tilldelning:

    Som standard, när du anropar någon av värdintegrerings-API:erna för att lägga till Azure-resurser, anropas AddAzureProvisioning(IDistributedApplicationBuilder)-API:et implicit. Det här API:et registrerar tjänster i di-containern (dependency injection) som används för att etablera Azure resurser när appvärden startar. Detta begrepp kallas lokal provisionering. Mer information finns i Lokal Azure försörjning.

  • Azure.Provisioning:

    Azure.Provisioning refererar till NuGet-paketet och är en uppsättning bibliotek som gör att du kan använda C# för att generera Bicep. Hostingintegreringarna i Azure använder dessa bibliotek i bakgrunden för att generera Bicep-filer som definierar de Azure resurser du behöver. För mer information, se Azure.Provisioning anpassning.

Azure.Provisioning anpassning

Alla .NET AspireAzure hostingintegreringar exponerar olika Azure resurser, och de är alla underklasser av typen AzureProvisioningResource – som själv ärver från AzureBicepResource. Detta möjliggör tillägg som är allmänt typbegränsade till den här typen, vilket gör det möjligt för ett fluent-API att anpassa infrastrukturen efter dina behov. Även om .NET.NET Aspire tillhandahåller standardvärden kan du påverka den genererade Bicep med hjälp av dessa API:er.

Konfigurera infrastruktur

Oavsett vilken Azure-resurs du arbetar med kedjar du ett anrop till ConfigureInfrastructure-tilläggsmetoden för att konfigurera dess underliggande infrastruktur. Med den här metoden kan du anpassa infrastrukturen för den Azure resursen genom att skicka ett configure ombud av typen Action<AzureResourceInfrastructure>. Den AzureResourceInfrastructure typen är en underklass av Azure.Provisioning.Infrastructure. Den här typen exponerar en massiv API-yta för att konfigurera den underliggande infrastrukturen för den Azure resursen.

Tänk på följande exempel:

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

Föregående kod:

  • Lägger till en parameter med namnet storage-sku.
  • Lägger till Azure Storage med AddAzureStorage-API:et som heter storage.
  • Kedjar ett anrop till ConfigureInfrastructure för att anpassa Azure Storage-infrastrukturen:

Detta exemplifierar flödet av en extern parameter till Azure Storage-infrastrukturen, vilket resulterar i att den genererade Bicep-filen återspeglar den önskade konfigurationen.

Lägg till Azure infrastruktur

Alla Azure tjänster exponeras inte som .NET Aspire integreringar. Även om de kan finnas vid ett senare tillfälle kan du fortfarande etablera tjänster som är tillgängliga i Azure.Provisioning.* bibliotek. Föreställ dig ett scenario där du har en arbetarservice som ansvarar för att hantera ett Azure containerregister. Anta nu att ett programvärdprojekt är beroende av 📦Azure. Provisioning.ContainerRegistry NuGet-paket.

Du kan använda AddAzureInfrastructure API:et för att lägga till Azure Container Registry-infrastrukturen i appens värd.

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

Föregående kod:

  • Anropar AddAzureInfrastructure med namnet acr.
  • Tillhandahåller ett configureInfrastructure ombud för att anpassa Azure Container Registry-infrastrukturen:
    • Skapar en ContainerRegistryService med namnet acr och en standard-SKU.
    • Lägger till Azure Container Registry-tjänsten i variabeln infra.
    • Instansierar en ProvisioningOutput med namnet registryName, en typ av stringoch ett värde som motsvarar namnet på Azure Container Registry.
    • Lägger till utdata i variabeln infra.
  • Lägger till ett projekt med namnet worker till byggaren.
  • Kopplar ett anrop till WithEnvironment för att ställa in miljövariabeln ACR_REGISTRY_NAME i projektet till värdet av registryName:s utdata.

Funktionen visar hur du lägger till Azure infrastruktur i värdprojekt för appen, även om Azure-tjänsten inte direkt exponeras som en .NET Aspire-integration. Den visar vidare hur man leder utdata från Azure Container Registry till ett beroende projekts miljö.

Överväg den resulterande Bicep-filen:

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

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

output registryName string = acr.name

Bicep-filen återspeglar den önskade konfigurationen av Azure Container Registry, enligt definitionen i AddAzureInfrastructure-API:et.

Använd anpassade Bicep-mallar

När du riktar in dig på Azure som önskad molnleverantör kan du använda Bicep för att definiera infrastrukturen som kod. Syftet är att drastiskt förenkla redigeringsupplevelsen med en renare syntax och bättre stöd för modularitet och återanvändning av kod.

Även om .NET.NET Aspire tillhandahåller en uppsättning fördefinierade Bicep-mallar kan det finnas tillfällen då du antingen vill anpassa mallarna eller skapa egna. I det här avsnittet beskrivs de begrepp och motsvarande API:er som du kan använda för att anpassa Bicep-mallarna.

Viktig

Det här avsnittet är inte avsett att lära dig Bicep, utan snarare för att ge vägledning om hur du skapar anpassade Bicep-mallar för användning med .NET.NET Aspire.

Som en del av Azure implementeringsberättelsen för .NET Aspireger Azure Developer CLI (azd) förståelse för ditt projekt .NET Aspire och ger möjlighet att distribuera det till Azure. azd CLI använder Bicep-mallarna för att distribuera programmet till Azure.

Installera Aspire.Hosting.Azure paket

När du vill referera till Bicep-filer är det möjligt att du inte använder någon av de Azure värdintegreringar. I det här fallet kan du fortfarande referera till Bicep-filer genom att installera Aspire.Hosting.Azure-paketet. Det här paketet innehåller nödvändiga API:er för att referera till Bicep-filer och anpassa Azure resurser.

Tips

Om du använder någon av hostingintegreringarna Azure behöver du inte installera paketet Aspire.Hosting.Azure eftersom det är ett transitivt beroende.

Om du vill använda någon av de här funktionerna 📦Aspire.Hosting.Azure NuGet-paketet måste vara installerat:

dotnet add package Aspire.Hosting.Azure

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Vad du kan förvänta dig av exemplen

Alla exempel i det här avsnittet förutsätter att du använder Aspire.Hosting.Azure namnområdet. Dessutom förutsätter exemplen att du har en IDistributedApplicationBuilder instans:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

När du anropar någon av Bicep-relaterade API:er görs som standard även ett anrop till AddAzureProvisioning som lägger till stöd för att generera Azure resurser dynamiskt under programstarten. Mer information finns i Lokal tillhandahållande och Azure.Provisioning.

Referensfiler för Bicep

Anta att du har en Bicep-mall i en fil med namnet storage.bicep som etablerar ett Azure Storage-konto:

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

Om du vill lägga till en referens till Bicep-filen på disken anropar du metoden AddBicepTemplate. Tänk på följande exempel:

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

Föregående kod lägger till en referens till en Bicep-fil som finns på ../infra/storage.bicep. Filsökvägarna ska vara i förhållande till appvärdprojektet. Den här referensen resulterar i att en AzureBicepResource läggs till i programmets resurssamling med namnet "storage", och API:et returnerar en IResourceBuilder<AzureBicepResource> instans som kan användas för att anpassa resursen ytterligare.

Referens Bicep infogad

Det vanligaste scenariot är att ha en Bicep-fil på disk, men du kan också lägga till Bicep-mallar direkt i koden. Infogade mallar kan vara användbara när du vill definiera en mall i kod eller när du vill generera mallen dynamiskt. Om du vill lägga till en inbäddad Bicep-mall anropar du metoden AddBicepTemplateString med Bicep-mallen som en string. Tänk på följande exempel:

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

I det här exemplet definieras Bicep-mallen som en inbäddad string och läggs till i programmets resurssamling med namnet "ai". Det här exemplet skapar en Azure AI-resurs.

Skicka parametrar till Bicep-mallar

Bicep stöder godkännande av parametrar, som kan användas för att anpassa mallens beteende. Om du vill skicka parametrar till en Bicep-mall från .NET.NET Aspirekedjar du anrop till metoden WithParameter enligt följande exempel:

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

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

Föregående kod:

  • Lägger till en parameter med namnet "region" till builder-instansen.
  • Lägger till en referens till en Bicep-fil som finns på ../infra/storage.bicep.
  • Skickar parametern "region" till Bicep-mallen, som löses med standardmetoden för parameterupplösning.
  • Skickar "storageName"-parametern till Bicep-mallen med ett hårdkodat värde.
  • Skickar parametern "tags" till Bicep-mallen med en matris med strängar.

Mer information finns i externa parametrar.

Välkända parametrar

.NET .NET Aspire innehåller en uppsättning välkända parametrar som kan skickas till Bicep-mallar. Dessa parametrar används för att ge information om programmet och miljön till Bicep-mallarna. Följande välkända parametrar är tillgängliga:

Fält Beskrivning Värde
AzureBicepResource.KnownParameters.KeyVaultName Namnet på nyckelvalvsresursen som används för att lagra hemliga utdata. "keyVaultName"
AzureBicepResource.KnownParameters.Location Platsen för resursen. Detta krävs för alla resurser. "location"
AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId Resurs-ID för log analytics-arbetsytan. "logAnalyticsWorkspaceId"
AzureBicepResource.KnownParameters.PrincipalId Huvud-ID för den aktuella användaren eller den hanterade identiteten. "principalId"
AzureBicepResource.KnownParameters.PrincipalName Huvudnamnet för den aktuella användaren eller den hanterade identiteten. "principalName"
AzureBicepResource.KnownParameters.PrincipalType Huvudtypen för den aktuella användaren eller den hanterade identiteten. Antingen User eller ServicePrincipal. "principalType"

Om du vill använda en välkänd parameter skickar du parameternamnet till metoden WithParameter, till exempel WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Du skickar inte värden för välkända parametrar eftersom .NET.NET Aspire löser dem åt dig.

Tänk dig ett exempel där du vill konfigurera en Azure Event Grid-webhook. Du kan definiera Bicep-mallen på följande sätt:

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

Den här Bicep-mallen definierar flera parametrar, inklusive topicName, webHookEndpoint, principalId, principalTypeoch den valfria location. Om du vill skicka dessa parametrar till Bicep-mallen kan du använda följande kodfragment:

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);
  • Det webHookApi projektet läggs till som en referens till builder.
  • Parametern topicName tilldelas ett hårdkodat namnvärde.
  • Parametern webHookEndpoint skickas som ett uttryck som löses till URL:en från api-projektreferensernas "https"-slutpunkt med /hook-rutten.
  • Parametrarna principalId och principalType skickas som välkända parametrar.

De välkända parametrarna är konventionsbaserade och bör inte åtföljas av ett motsvarande värde när de skickas med hjälp av WithParameter-API:et. Välkända parametrar förenklar vissa vanliga funktioner, till exempel rolltilldelningar, när de läggs till i Bicep-mallarna, som du ser i föregående exempel. Rolltilldelningar krävs för att Event Grid-webhooken ska skicka händelser till den angivna slutpunkten. Mer information finns i rolltilldelningen Event Grid Data Sender.

Hämta utdata från Bicep-referenser

Förutom att skicka parametrar till Bicep-mallar kan du även hämta utdata från Bicep-mallarna. Överväg följande Bicep-mall eftersom den definierar en output med namnet 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 definierar ett utdata med namnet endpoint. Om du vill hämta utdata från Bicep-mallen anropar du metoden GetOutput på en IResourceBuilder<AzureBicepResource>-instans, vilket visas i följande C#-kodfragment:

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

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

I det här exemplet hämtas utdata från Bicep-mallen och lagras i en endpoint variabel. Vanligtvis skickar du dessa utdata som en miljövariabel till en annan resurs som förlitar sig på den. Om du till exempel hade ett ASP.NET Core minimalt API-projekt som var beroende av den här slutpunkten kan du skicka utdata som en miljövariabel till projektet med hjälp av följande kodfragment:

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

Mer information finns i Bicep-utdata.

Hämta hemliga utdata från Bicep-referenser

Det är viktigt att undvika utdata av hemligheter vid arbete med Bicep. Om utdata anses vara en hemlighet, vilket innebär att den inte ska exponeras i loggar eller på andra platser, kan du behandla den som sådan. Detta kan uppnås genom att lagra hemligheten i Azure Key Vault och referera till den i Bicep-mallen. .NET Aspire's Azure integrering ger ett mönster för säker lagring av utdata från Bicep-mallen genom att tillåta resurser att använda parametern keyVaultName för att lagra hemligheter i Azure Key Vault.

Tänk på följande Bicep-mall som ett exempel på hur du kan demonstrera det här konceptet med att skydda hemliga utdata:

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

Den föregående Bicep-mallen förväntar sig en parameter av typen keyVaultName, tillsammans med flera andra parametrar. Den definierar sedan en Azure Cosmos DB-resurs och lagrar en hemlighet i Azure Key Vault, med namnet connectionString, vilket representerar den fullständigt kvalificerade anslutningssträngen till Cosmos DB-instansen. Om du vill komma åt det här värdet för den hemliga anslutningssträngen kan du använda följande kodfragment:

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

I föregående kodfragment läggs cosmos Bicep-mallen till som en referens till builder. Den hemliga utdata connectionString hämtas från Bicep-mallen och lagras i en variabel. De hemliga utdata skickas sedan som en miljövariabel (ConnectionStrings__cosmos) till api projektet. Den här miljövariabeln används för att ansluta till den Cosmos DB instansen.

När den här resursen distribueras kommer den underliggande distributionsmekanismen automatiskt att referera till hemligheter från Azure Key Vault. För att garantera hemlig isolering skapar .NET.NET Aspire ett Nyckelvalv per källa.

Anteckning

I lokalt provisionsläge extraheras hemligheten från Key Vault och ställs in som en miljövariabel. Mer information finns i Lokal Azure försörjning.

Förlagsverksamhet

När du publicerar din app används den Azure etableringsgenererade Bicep av Azure Developer CLI för att skapa Azure resurser i din Azure-prenumeration. .NET .NET Aspire matar ut ett publiceringsmanifest, som också är en viktig del av publiceringsprocessen. Azure Developer CLI är ett kommandoradsverktyg som tillhandahåller en uppsättning kommandon för att hantera Azure resurser.

Mer information om publicering och distribution finns i Distribuera ett .NET Aspire-projekt till Azure Container Apps med hjälp av Azure Developer CLI (grundlig guide).