översikt över AspireAzure-integreringar

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. 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 Aspire och syftar till att hjälpa dig att förstå hur du använder dem.

Lägg till Azure resurser

Alla 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 Aspire AppHost 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 Aspire AppHost innehåller Azure resurser och du kör den lokalt (typisk utvecklare F5 eller dotnet run upplevelse) Azure etableras resurserna i din Azure prenumeration. På så sätt kan du som utvecklare felsöka mot dem lokalt i kontexten för din AppHost.

Aspire syftar till att minimera kostnaderna genom att som standard använda Basic eller StandardStock Keeping Unit (SKU) för dess Azure integreringar. Ä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 Aspire följande Azure emulatorer:

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.

Lokala behållare

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 Aspire följande Azure tjänster i form av containrar:

Förstå Azure integrations-API:er

Aspire's styrka ligger i dess förmåga att tillhandahålla en fantastisk utvecklarens inre loop. 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 Aspirekanske du undrar hur anrop 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:

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

Mer information om skillnaden mellan körnings- och publiceringslägen finns i Aspire AppHost: Körningskontext.

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

Den distribuerade programbyggaren, som är en del av AppHost, använder byggmönstret till AddAzure* resurser till 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 AppHost körs används körningskontexten för att avgöra om AppHost är i Run eller Publish i 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:

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

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 förbättras med rolltilldelningar och andra anpassningar som är tillgängliga med 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 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.

När AppHost körs i publiceringsläge innehåller den genererade manifestfilen parametern existingResourceName som kan användas för att referera till den befintliga Azure resursen. Ö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 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 Anpassa Azure resurser och överväg andra publicerings-API:er.

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

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 Aspire-app. AddConnectionString API:et används med AppHosts körningskontext för att villkorligt lägga till en anslutningssträng i appmodellen.

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 AppHost 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ör"-läge motsvarar den ett konfigurationsvärde som är synligt för AppHost. 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 Container-applikation

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

• ContainerResource: Representerar en angiven behållare.
• ExecutableResource: Representerar en angiven körbar process.
• ProjectResource: Representerar ett angivet .NET projekt.

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

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

Dessa API:er konfigurerar resursen så att den publiceras som en Azure containerapp och anropar AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) implicit för att lägga till nödvändig infrastruktur och Bicep-filer i din AppHost. 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.

Information om hur Azure du konfigurerar containerappmiljön finns i Konfigurera Azure Container Apps miljöer. Information om hur du publicerar resurser som Azure Container App-jobb, se Azure Container App-jobb. Mer information finns i ContainerApp och AsProvisioningParameter.

Publishing

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. Aspire producerar ett publiceringsmanifest, vilket 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 Aspire-projekt till Azure Container Apps med hjälp av Azure Developer CLI (grundlig guide).