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ägga till anslutning till befintliga Azure resurser

.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. I "kör"-läge motsvarar anslutningssträngen ett konfigurationsvärde som är synligt för appvärden. Det förutsätts att alla rolltilldelningar för målresursen har konfigurerats. 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.

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.

Typisk utvecklarupplevelse

När din .NET Aspire appvärd innehåller Azure-resurser och du kör den lokalt (vanlig utvecklarupplevelse med F5 eller dotnet run) 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 som standard Basic eller StandardStock Keeping Unit (SKU) för sina 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 köras lokalt i emulatorer. För närvarande stöder .NET Aspire följande Azure emulatorer:

Värdintegrering 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 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 tjänster kan köras lokalt i containrar. Om du vill köra en Azure-tjänst lokalt i en container kedjar du ett anrop till RunAsContainer-metoden på Azure resursverktyget. Den här metoden konfigurerar Azure resursen så att den körs lokalt i en container 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 så att den körs lokalt i en container, baserat på docker.io/library/postgres avbildningen.
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 avbildningen.

Not

Precis som emulatorer påverkar anrop av RunAsContainer på en resursbyggare Azure inte 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 Aspirestyrka ligger i dess förmåga att ge en fantastisk utvecklare 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 .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ö.

Infrastruktur som kod

Azure SDK för .NET innehåller 📦Azure. Etablering NuGet-paket och en uppsättning tjänstspecifika Azure etableringspaket. 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 adderar Azure resurser till din appvärd, adderas lämplig etableringsfunktionalitet implicit. Med andra ord behöver du inte anropa några etablerings-API:er direkt.

Eftersom .NET Aspire modeller Azure resurser inom Azure hostintegreringar används Azure SDK för 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 sammanfla termer och för att förenkla "etablering" är det viktigt att förstå skillnaden mellan lokal etablering och Azure etablering:

  • Lokal tilldelning:

    När du anropar någon av de Azure som är värd för integrerings-API:er för att lägga till Azure resurser anropas som standard 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. Den Azure som är värd för integreringar i .NET Aspire använder dessa bibliotek i bakgrunden för att generera Bicep-filer som definierar Azure resurser du behöver. För mer information, se anpassningi .

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 appvärden:

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 appvärdsprojektet, även om Azure-tjänsten inte exponeras direkt 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 etablering 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ärd projekt. 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 hjälp av standardparametrarnas upplö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 matchar URL:en från api-projektet refererar till "https"-slutpunkten med /hook vägen.
  • 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 för 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 den underliggande distributionsmekanismen automatiskt referenshemligheter från Azure Key Vault. För att garantera hemlig isolering skapar .NET.NET Aspire ett Nyckelvalv per källa.

Not

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