Sätt upp .NET Aspire-projektet till Azure Container Apps med hjälp av en djupgående guide för Azure Developer CLI.

Azure Developer CLI (azd) har utökats för att stödja implementering av .NET- och.NET Aspire-projekt. Använd den här guiden för att gå igenom processen med att skapa och distribuera ett .NET Aspire-projekt till Azure Container Apps med hjälp av Azure Developer CLI. I den här självstudien får du lära dig följande begrepp:

• Utforska hur azd integrering fungerar med .NET.NET Aspire projekt
• Etablera och distribuera resurser på Azure för ett .NET Aspire projekt med hjälp av azd
• Generera Bicep-infrastruktur och andra mallfiler med hjälp av azd

Förutsättningar

Om du vill arbeta med .NET.NET Aspirebehöver du följande installerat lokalt:

• .NET 8,0 eller .NET 9,0
• En OCI-kompatibel containerruntime, till exempel:
  • Docker Desktop eller Podman. Mer information finns i Container Runtime.
• En IDE (Integrated Developer Environment) eller kodredigerare, till exempel:
  • Visual Studio 2022 version 17.9 eller senare (valfritt)
  • Visual Studio Code (valfritt)
    • C# Dev Kit: Tillägg (valfritt)
  • JetBrains Rider med .NET.NET Aspire tillägg (valfritt)

Mer information finns i .NET.NET Aspire installation och verktygoch .NET.NET Aspire SDK.

Du måste också ha Azure Developer CLIinstallerat lokalt. Vanliga installationsalternativ är följande:

Windows

winget install microsoft.azd

macOS

brew tap azure/azd && brew install azd

Linux

curl -fsSL https://aka.ms/install-azd.sh | bash

Så här fungerar Azure Developer CLI integrering

Arbetsflödet azd init ger anpassat stöd för .NET.NET Aspire projekt. Följande diagram visar hur det här flödet fungerar konceptuellt och hur azd och .NET.NET Aspire är integrerade:

1. När azd riktar in sig på ett .NET.NET Aspire projekt startar det AppHost med ett särskilt kommando (dotnet run --project AppHost.csproj --output-path manifest.json --publisher manifest), som genererar Aspire-manifestfilen.
2. Manifestfilen utvärderas av azd provision underkommandslogik för att generera Bicep-filer endast i minnet (som standard).
3. När du har genererat Bicep-filerna triggas en distribution med hjälp av ARM-API:erna hos Azuresom riktar sig mot den tidigare angivna prenumerationen och resursgruppen.
4. När de underliggande Azure resurserna har konfigurerats körs azd deploy underkommandologik som använder samma Aspire manifestfil.
5. Som en del av distributionen anropar azddotnet publish med hjälp av .NETinbyggda stöd för containerpublicering för att generera containeravbildningar.
6. När azd har skapat containeravbildningarna skickas de till ACR-registret som skapades under etableringsfasen.
7. När containeravbildningen är i ACR uppdaterar azd slutligen resursen med ARM för att börja använda den nya versionen av containeravbildningen.

Anteckning

azd kan också mata ut den genererade Bicep till en infra mapp i ditt projekt, vilket du kan läsa mer om i avsnittet Generera Bicep från .NET.NET Aspire appmodell.

Etablera och distribuera en .NET.NET Aspire startapp

Stegen i det här avsnittet visar hur du skapar en .NET Aspire startapp och hanterar tillhandahållandet och distributionen av appresurser till Azure med hjälp av azd.

Skapa .NET.NET Aspire-startappen

Skapa ett nytt .NET.NET Aspire projekt med hjälp av kommandot dotnet new. Du kan också skapa projektet med hjälp av Visual Studio.

dotnet new aspire-starter --use-redis-cache -o AspireSample
cd AspireSample
dotnet run --project AspireSample.AppHost\AspireSample.AppHost.csproj

Föregående kommandon skapar ett nytt .NET.NET Aspire projekt baserat på mallen aspire-starter som innehåller ett beroende av Redis cacheminne. Den kör .NET.NET Aspire projekt som verifierar att allt fungerar korrekt.

Initiera mallen

1. Öppna ett nytt terminalfönster och cd i projektkatalogen AppHost för din .NET.NET Aspire lösning.

2. Kör kommandot azd init för att initiera projektet med azd, som kommer att granska den lokala katalogstrukturen och fastställa typen av app.

   azd init
   

   Mer information om kommandot azd init finns i azd init.

3. Välj Använd kod i den aktuella katalogen när azd uppmanar dig med två alternativ för appinitiering.

   ? How do you want to initialize your app?  [Use arrows to move, type to filter]
   > Use code in the current directory
     Select a template
   

4. När du har genomsökt katalogen uppmanar azd dig att bekräfta att den hittade rätt .NET.NET AspireAppHost- projekt. Välj alternativet Bekräfta och fortsätt initiera min app.

   Detected services:
   
     .NET (Aspire)
     Detected in: D:\source\repos\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj
   
   azd will generate the files necessary to host your app on Azure using Azure Container Apps.
   
   ? Select an option  [Use arrows to move, type to filter]
   > Confirm and continue initializing my app
     Cancel and exit
   

5. Ange ett miljönamn som används för att namnge etablerade resurser i Azure och hantera olika miljöer, till exempel dev och prod.

   Generating files to run your app on Azure:
   
     (✓) Done: Generating ./azure.yaml
     (✓) Done: Generating ./next-steps.md
   
   SUCCESS: Your app is ready for the cloud!
   You can provision and deploy your app to Azure by running the azd up command in this directory. For more information on configuring your app, see ./next-steps.md
   

azd genererar ett antal filer och placerar dem i arbetskatalogen. Dessa filer är:

• azure.yaml: Beskriver tjänsterna i appen, till exempel .NET Aspire AppHost-projekt, och mappar dem till Azure resurser.
• .azure/config.json: Konfigurationsfil som informerar azd vad den aktuella aktiva miljön är.
• .azure/aspireazddev/.env: Innehåller miljöspecifika åsidosättningar.

Filen azure.yaml innehåller följande innehåll:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

name: AspireSample
services:
  app:
    language: dotnet
    project: .\AspireSample.AppHost\AspireSample.AppHost.csproj
    host: containerapp

Namngivning av resurser

När du skapar nya Azure resurser är det viktigt att du följer namngivningskraven. För Azure Container Appsmåste namnet vara 2–32 tecken långt och bestå av gemener, siffror och bindestreck. Namnet måste börja med en bokstav och sluta med ett alfanumeriskt tecken.

Mer information finns i Namngivningsregler och begränsningar för Azure resurser.

Inledande distribution

1. För att distribuera .NET Aspire projektet autentiserar du till Azure AD för att anropa Azure resurshanterings-API:er.

   azd auth login
   

   Föregående kommando startar en webbläsare för att autentisera kommandoradssessionen.

2. När du har autentiserats kör du följande kommando från projektkatalogen AppHost för att etablera och distribuera programmet.

   azd up
   

   Viktig

   Om du vill skicka containeravbildningar till Azure Container Registry (ACR) måste du ha Microsoft.Authorization/roleAssignments/write åtkomst. Detta kan uppnås genom att aktivera en administratörsanvändare i registret. Öppna Azure-portalen, gå till ACR-resursen/Inställningar/Åtkomstnycklar och markera sedan kryssrutan Administratörsanvändare. Mer information finns i Aktivera administratörsanvändare.

3. När du uppmanas till det väljer du den prenumeration och plats som resurserna ska distribueras till. När de här alternativen har valts distribueras .NET.NET Aspire projektet.

   By default, a service can only be reached from inside the Azure Container Apps environment it is running in. Selecting a service here will also allow it to be reached from the Internet.
   ? Select which services to expose to the Internet webfrontend
   ? Select an Azure Subscription to use:  1. <YOUR SUBSCRIPTION>
   ? Select an Azure location to use: 1. <YOUR LOCATION>
   
   Packaging services (azd package)
   
   
   Provisioning Azure resources (azd provision)
   Provisioning Azure resources can take some time.
   
   Subscription: <YOUR SUBSCRIPTION>
   Location: <YOUR LOCATION>
   
     You can view detailed progress in the Azure Portal:
     <LINK TO DEPLOYMENT>
   
     (✓) Done: Resource group: <YOUR RESOURCE GROUP>
     (✓) Done: Container Registry: <ID>
     (✓) Done: Log Analytics workspace: <ID>
     (✓) Done: Container Apps Environment: <ID>
   
   SUCCESS: Your application was provisioned in Azure in 1 minute 13 seconds.
   You can view the resources created under the resource group <YOUR RESOURCE GROUP> in Azure Portal:
   <LINK TO RESOURCE GROUP OVERVIEW>
   
   Deploying services (azd deploy)
   
     (✓) Done: Deploying service apiservice
     - Endpoint: <YOUR UNIQUE apiservice APP>.azurecontainerapps.io/
   
     (✓) Done: Deploying service webfrontend
     - Endpoint: <YOUR UNIQUE webfrontend APP>.azurecontainerapps.io/
   
   Aspire Dashboard: <LINK TO DEPLOYED .NET ASPIRE DASHBOARD>
   
   SUCCESS: Your up workflow to provision and deploy to Azure completed in 3 minutes 50 seconds.
   

   Den sista raden med utdata från kommandot azd är en länk till Azure-portalen som visar alla Azure resurser som har distribuerats:

   

Tre containrar distribueras i det här programmet:

• webfrontend: Innehåller kod från webbprojektet i startmallen.
• apiservice: Innehåller kod från API-tjänstprojektet i startmallen.
• cache: En Redis containeravbildning för att tillhandahålla en cache till klientdelen.

Precis som i lokal utveckling har konfigurationen av anslutningssträngar hanterats automatiskt. I det här fallet var azd ansvarig för att tolka programmodellen och översätta den till lämpliga distributionssteg. Tänk till exempel på de anslutningssträngs- och tjänstidentifieringsvariabler som matas in i webfrontend-containern så att den vet hur man ansluter till Redis cache och apiservice.

Mer information om hur .NET.NET Aspire projekt hanterar anslutningssträngar och tjänstidentifiering finns i .NET.NET Aspire orchestration overview.

Distribuera programuppdateringar

När kommandot azd up körs provisioneras de underliggande Azure-resurserna och en containeravbildning byggs och distribueras till containerapparna som är värdar för .NET.NET Aspire-projektet. När utvecklingen är igång och Azure resurser distribueras är det vanligtvis inte nödvändigt att etablera Azure resurser varje gång koden uppdateras. Detta gäller särskilt för utvecklarens inre loop.

För att påskynda distributionen av kodändringar stöder azd distribution av koduppdateringar i containeravbildningen. Detta görs med hjälp av kommandot azd deploy:

azd deploy

Deploying services (azd deploy)

  (✓) Done: Deploying service apiservice
  - Endpoint: <YOUR UNIQUE apiservice APP>.azurecontainerapps.io/

  (✓) Done: Deploying service webfrontend
  - Endpoint: <YOUR UNIQUE webfrontend APP>.azurecontainerapps.io/

Aspire Dashboard: <LINK TO DEPLOYED .NET ASPIRE DASHBOARD>

Det är inte nödvändigt att distribuera alla tjänster varje gång. azd förstår .NET.NET Aspire projektmodell och det är möjligt att distribuera endast en av de tjänster som anges med hjälp av följande kommando:

azd deploy webfrontend

Mer information finns i Azure Developer CLI referens: azd deploy.

Distribuera infrastrukturuppdateringar

När beroendestrukturen i ett .NET.NET Aspire projekt ändras måste azd återetablera de underliggande Azure resurserna. Kommandot azd provision används för att tillämpa dessa ändringar på infrastrukturen.

Om du vill se detta i praktiken uppdaterar du filen Program.cs i AppHost-projektet till följande:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

// Add the locations database.
var locationsdb = builder.AddPostgres("db").AddDatabase("locations");

// Add the locations database reference to the API service.
var apiservice = builder.AddProject<Projects.AspireSample_ApiService>("apiservice")
    .WithReference(locationsdb);

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
    .WithReference(cache)
    .WithReference(apiservice);

builder.Build().Run();

Spara filen och utfärda följande kommando:

azd provision

Kommandot azd provision uppdaterar infrastrukturen genom att skapa en containerapp som är värd för Postgres-databasen. Kommandot azd provision uppdaterade inte anslutningssträngarna för apiservice-containern. För att anslutningssträngarna ska kunna uppdateras så att de pekar på den nyligen etablerade Postgres databasen måste kommandot azd deploy anropas igen. När du är osäker, använd azd up för både att förbereda och distribuera.

Rensa resurser

Kom ihåg att rensa de Azure resurser som du har skapat under den här genomgången. Eftersom azd känner till resursgruppen där den skapade resurserna kan den användas för att stänga ner miljön med hjälp av följande kommando:

azd down

Det tidigare kommandot kan ta lite tid att köra, men när resursgruppen och alla dess resurser har slutförts bör de tas bort.

Deleting all resources and deployed code on Azure (azd down)
Local application code is not deleted when running 'azd down'.

  Resource group(s) to be deleted:

    • <YOUR RESOURCE GROUP>: <LINK TO RESOURCE GROUP OVERVIEW>

? Total resources to delete: 7, are you sure you want to continue? Yes
Deleting your resources can take some time.

  (✓) Done: Deleting resource group: <YOUR RESOURCE GROUP>

SUCCESS: Your application was removed from Azure in 9 minutes 59 seconds.

Generera Bicep från .NET.NET Aspire projektmodell

Även om utvecklingsteamen kan använda kommandon för azd up (eller azd provision och azd deploy) för sina distributioner både i utvecklings- och produktionssyfte, kan vissa team välja att generera Bicep-filer som de kan granska och hantera som en del av versionskontroll (detta gör också att dessa Bicep-filer kan refereras som en del av en större mer komplex Azure distribution).

azd innehåller möjligheten att mata ut Bicep-konfigurationen som används för tillhandahållande via följande kommando:

azd config set alpha.infraSynth on
azd infra synth

När det här kommandot har körts i exemplet med startmallen som används i den här guiden skapas följande filer i projektkatalogen AppHost:

• infra/main.bicep: Representerar huvudstartpunkten för distributionen.
• infra/main.parameters.json: Används som parametrar för huvud-Bicep (mappar till miljövariabler som definierats i mappen .azure).
• infra/resources.bicep: Definierar de Azure resurser som krävs för att stödja .NET Aspire projektmodellen.
• AspireSample.Web/manifests/containerApp.tmpl.yaml: Containerappdefinitionen för webfrontend.
• AspireSample.ApiService/manifests/containerApp.tmpl.yaml: Containerappdefinitionen för apiservice.

Filen infra\resources.bicep innehåller ingen definition av själva containerapparna (med undantag för containerappar som är beroenden som Redis och Postgres):

@description('The location used for all deployed resources')
param location string = resourceGroup().location

@description('Tags that will be applied to all resources')
param tags object = {}

var resourceToken = uniqueString(resourceGroup().id)

resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'mi-${resourceToken}'
  location: location
  tags: tags
}

resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: replace('acr-${resourceToken}', '-', '')
  location: location
  sku: {
    name: 'Basic'
  }
  tags: tags
}

resource caeMiRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(containerRegistry.id, managedIdentity.id, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d'))
  scope: containerRegistry
  properties: {
    principalId: managedIdentity.properties.principalId
    principalType: 'ServicePrincipal'
    roleDefinitionId:  subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d')
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
  name: 'law-${resourceToken}'
  location: location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
  }
  tags: tags
}

resource containerAppEnvironment 'Microsoft.App/managedEnvironments@2023-05-01' = {
  name: 'cae-${resourceToken}'
  location: location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: logAnalyticsWorkspace.properties.customerId
        sharedKey: logAnalyticsWorkspace.listKeys().primarySharedKey
      }
    }
  }
  tags: tags
}

resource cache 'Microsoft.App/containerApps@2023-05-02-preview' = {
  name: 'cache'
  location: location
  properties: {
    environmentId: containerAppEnvironment.id
    configuration: {
      service: {
        type: 'redis'
      }
    }
    template: {
      containers: [
        {
          image: 'redis'
          name: 'redis'
        }
      ]
    }
  }
  tags: union(tags, {'aspire-resource-name': 'cache'})
}

resource locations 'Microsoft.App/containerApps@2023-05-02-preview' = {
  name: 'locations'
  location: location
  properties: {
    environmentId: containerAppEnvironment.id
    configuration: {
      service: {
        type: 'postgres'
      }
    }
    template: {
      containers: [
        {
          image: 'postgres'
          name: 'postgres'
        }
      ]
    }
  }
  tags: union(tags, {'aspire-resource-name': 'locations'})
}
output MANAGED_IDENTITY_CLIENT_ID string = managedIdentity.properties.clientId
output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerRegistry.properties.loginServer
output AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID string = managedIdentity.id
output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string = containerAppEnvironment.id
output AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN string = containerAppEnvironment.properties.defaultDomain

Mer information om hur du använder Bicep för att automatisera distributioner till Azure finns i Vad är Bicep?

Definitionen av containerapparna från .NET-tjänstprojekten finns i containerApp/tmpl.yaml filer i katalogen manifests i respektive projekt. Här är ett exempel från webfrontend projektet:

location: {{ .Env.AZURE_LOCATION }}
identity:
  type: UserAssigned
  userAssignedIdentities:
    ? "{{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}"
    : {}
properties:
  environmentId: {{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_ID }}
  configuration:
    activeRevisionsMode: single
    ingress:
      external: true
      targetPort: 8080
      transport: http
      allowInsecure: false
    registries:
    - server: {{ .Env.AZURE_CONTAINER_REGISTRY_ENDPOINT }}
      identity: {{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}
  template:
    containers:
    - image: {{ .Env.SERVICE_WEBFRONTEND_IMAGE_NAME }}
      name: webfrontend
      env:
      - name: AZURE_CLIENT_ID
        value: {{ .Env.MANAGED_IDENTITY_CLIENT_ID }}
      - name: ConnectionStrings__cache
        value: {{ connectionString "cache" }}
      - name: OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES
        value: "true"
      - name: OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES
        value: "true"
      - name: services__apiservice__0
        value: http://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
      - name: services__apiservice__1
        value: https://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
tags:
  azd-service-name: webfrontend
  aspire-resource-name: webfrontend

När kommandot azd infra synth har körts, används Bicep och de stödjande genererade filerna när azd provision och azd deploy anropas.

Viktig

Om azd infra synth anropas igen ersätts alla ändrade filer med nyligen genererade filer och du uppmanas att bekräfta detta innan du gör det.

Isolerade miljöer för felsökning

Eftersom azd gör det enkelt att etablera nya miljöer är det möjligt för varje teammedlem att ha en isolerad molnbaserad miljö för felsökning av kod i en inställning som nära matchar produktionen. När du gör detta bör varje gruppmedlem skapa en egen miljö med hjälp av följande kommando:

azd env new

Då uppmanas användaren att ange prenumerations- och resursgruppsinformation igen och efterföljande azd up, azd provisionoch azd deploy anrop använder den här nya miljön som standard. Växeln --environment kan användas för dessa kommandon för att växla mellan miljöer.

Rensa resurser

Kör följande Azure CLI-kommando för att ta bort resursgruppen när du inte längre behöver de Azure resurser som du skapade. Om du tar bort resursgruppen tas även de resurser som ingår i den bort.

az group delete --name <your-resource-group-name>

Mer information finns i Rensa resurser i Azure.