Nasazení projektu .NET Aspire do Azure Container Apps pomocí Azure Developer CLI (podrobný průvodce)

Článek
12/14/2024

Azure Developer CLI (azd) byl rozšířen, aby podporoval nasazování projektů .NET.NET Aspire. Tento průvodce vás provede procesem vytvoření a nasazení projektu .NET Aspire pro Azure Container Apps pomocí Azure Developer CLI. V tomto kurzu se seznámíte s následujícími koncepty:

Prozkoumání fungování integrace azd s projekty .NET.NET Aspire
Nasazení a zřízení prostředků na Azure pro projekt .NET Aspire pomocí azd
Generujte infrastrukturu Bicep a další soubory šablon pomocí azd

Požadavky

Pokud chcete pracovat s .NET.NET Aspire, potřebujete místně nainstalovat následující:

.NET 8.0 nebo .NET 9.0
Modul runtime kontejneru kompatibilní s OCI, například:
- Docker desktopové nebo Podman. Další informace najdete v modulu runtime kontejneru .
Integrované vývojové prostředí (IDE) nebo editor kódu, například:
- Visual Studio 2022 verze 17.9 nebo novější (volitelné)
- Visual Studio Code (volitelné)
  - C# Dev Kit: Rozšíření (volitelné)
- JetBrains Rider s .NET.NET Aspire zásuvným modulem (volitelné)

Další informace najdete v tématu .NET.NET Aspire nastavení a nástrojea .NET.NET Aspire SDK.

Budete také muset mít Azure Developer CLInainstalované lokálně. Mezi běžné možnosti instalace patří:

Windows
macOS
Linux

winget install microsoft.azd

brew tap azure/azd && brew install azd

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

Jak funguje integrace Azure Developer CLI

Pracovní postup azd init poskytuje přizpůsobenou podporu pro projekty .NET.NET Aspire. Následující diagram znázorňuje, jak tento tok funguje koncepčně a jak jsou integrované azd a .NET.NET Aspire:

ilustrace interního zpracování

Když azd cílí na projekt .NET.NET Aspire, spustí AppHost pomocí speciálního příkazu (dotnet run --project AppHost.csproj --output-path manifest.json --publisher manifest), který vytvoří soubor manifestu Aspire.
Soubor manifestu je zpracováván logikou podpříkazu azd provision pro generování souborů Bicep pouze v rámci paměti (ve výchozím nastavení).
Po vygenerování souborů Bicep se nasazení aktivuje pomocí rozhraní API ARM Azure, které cílí na předplatné a skupinu prostředků uvedené dříve.
Po nakonfigurování podkladových Azure prostředků se spustí logika azd deploy dílčího příkazu, která používá stejný soubor manifestu Aspire.
V rámci nasazení azd volá dotnet publish pomocí integrované podpory publikování kontejnerů .NETk vytvoření obrazů kontejneru.
Jakmile azd sestaví image kontejneru, odešle je do registru ACR vytvořeného během fáze zřizování.
Jakmile je image kontejneru ve službě ACR, azd aktualizuje prostředek pomocí ARM, aby se začala používat nová verze image kontejneru.

Poznámka

azd také umožňuje vygenerovat vygenerovaný Bicep do složky infra v projektu, o které si můžete přečíst další informace v generování Bicep z části .NET.NET Aspire model aplikace.

Zřízení a nasazení úvodní aplikace .NET.NET Aspire

Kroky v této části ukazují, jak vytvořit a spustit aplikaci .NET Aspire a zpracovat zajištění zřizování a nasazení prostředků aplikace pro Azure pomocí azd.

Vytvoření úvodní aplikace .NET.NET Aspire

Pomocí příkazu .NET vytvořte nový projekt .NET Aspiredotnet new. Projekt můžete také vytvořit pomocí Visual Studio.

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

Předchozí příkazy vytvoří nový projekt .NET.NET Aspire založený na šabloně aspire-starter, která zahrnuje závislost na Redis mezipaměti. Spustí projekt .NET.NET Aspire, který ověří, že všechno funguje správně.

Inicializujte šablonu

Otevřete nové okno terminálu a spusťte cd do adresáře vašeho řešení .NET.NET Aspire.
Spuštěním příkazu azd init inicializovat projekt pomocí azd, který zkontroluje místní adresářovou strukturu a určí typ aplikace.
```
azd init
```
Další informace o příkazu azd init naleznete viz azd init.

Vyberte Použít kód v aktuálním adresáři, když azd zobrazí výzvu se dvěma možnostmi inicializace aplikace.

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

Po kontrole adresáře azd zobrazí výzvu k potvrzení, že našel správný projekt .NET.NET AspireAppHost. Vyberte možnost Potvrdit a pokračovat v inicializaci mé aplikace.

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

Zadejte název prostředí, který se používá k pojmenování zřízených prostředků v Azure a správě různých prostředí, jako jsou dev a 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 vygeneruje řadu souborů a umístí je do pracovního adresáře. Tyto soubory:

azure.yaml: Popisuje služby aplikace, například projekt .NET Aspire AppHost, a mapuje je na Azure zdroje.
.azure/config.json: Konfigurační soubor, který informuje azd o tom, jaké je aktuálně aktivní prostředí.
.azure/aspireazddev/.env: Obsahuje přepsání specifická pro prostředí.

Soubor azure.yaml má následující obsah:

# 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

Pojmenování prostředků

Při vytváření nových Azure prostředků je důležité dodržovat požadavky na pojmenování. Pro Azure Container Appsmusí mít název délku 2 až 32 znaků a musí obsahovat malá písmena, číslice a pomlčky. Název musí začínat písmenem a končit alfanumerickým znakem.

Další informace naleznete v tématu Pravidla a omezení pro Azure prostředky.

Počáteční nasazení

Pokud chcete nasadit projekt .NET Aspire, ověřte se do služby Azure AD a volejte rozhraní pro správu prostředků API Azure.
```
azd auth login
```
Předchozí příkaz otevře prohlížeč pro ověření relace v příkazovém řádku.
Po ověření spusťte z adresáře projektu AppHost následující příkaz, který aplikaci zřídí a nasadí.
```
azd up
```
Důležitý

Pokud chcete odeslat image kontejneru do služby Azure Container Registry (ACR), musíte mít Microsoft.Authorization/roleAssignments/write přístup. Toho lze dosáhnout povolením uživatele správce v registru. Otevřete portál Azure, přejděte na prostředek ACR / Nastavení / Přístupové klíče a zaškrtněte políčko správce. Další informace viz Povolení administrátorského uživatele.

Po zobrazení výzvy vyberte předplatné a umístění, do které se mají prostředky nasadit. Po výběru těchto možností se nasadí projekt .NET.NET Aspire.

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.

Posledním řádkem výstupu příkazu azd je odkaz na portál Azure, který zobrazuje všechny nasazené Azure prostředky:

V této aplikaci se nasazují tři kontejnery:

webfrontend: Obsahuje kód z webového projektu v úvodní šabloně.
apiservice: Obsahuje kód z projektu služby API v úvodní šabloně.
cache: Image kontejneru Redis pro poskytnutí mezipaměti front-endu.

Stejně jako v místním vývoji se konfigurace připojovacích řetězců zpracovává automaticky. V tomto případě byl azd zodpovědný za interpretaci aplikačního modelu a jeho překladu do příslušných kroků nasazení. Představte si například proměnné připojovacího řetězce a zjišťování služeb, které se vloží do kontejneru webfrontend, aby věděla, jak se připojit k mezipaměti Redis a apiservice.

Další informace o tom, jak .NET.NET Aspire projekty nakládají s připojovacími řetězci a zjišťováním služeb, najdete v tématu .NET.NET Aspire přehled orchestrace.

Nasazení aktualizací aplikací

Po provedení příkazu azd up se základní prostředky Azurezřízené a image kontejneru se sestaví a nasadí do kontejnerových aplikací hostujících projekt .NET.NET Aspire. Jakmile probíhá vývoj a Azure prostředky jsou nasazeny, nebude obvykle nutné zřizovat Azure prostředky při každé aktualizaci kódu – to platí zejména pro vnitřní smyčku vývojáře.

Pokud chcete urychlit nasazení změn kódu, azd podporuje nasazování aktualizací kódu v imagi kontejneru. To se provádí pomocí příkazu 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>

Není nutné nasazovat všechny služby pokaždé. azd rozumí modelu projektu .NET.NET Aspire, je možné nasadit pouze jednu ze služeb zadaných pomocí následujícího příkazu:

azd deploy webfrontend

Pro více informací viz reference Azure Developer CLI: nasazení azd.

Nasazení aktualizací infrastruktury

Kdykoli se struktura závislostí v rámci projektu .NET.NET Aspire změní, azd musí znovu nastavit podkladové Azure zdroje. Příkaz azd provision slouží k použití těchto změn v infrastruktuře.

Pokud se chcete podívat na tuto akci, aktualizujte soubor Program.cs v projektu AppHost následujícím způsobem:

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

Uložte soubor a zadejte následující příkaz:

azd provision

Příkaz azd provision aktualizuje infrastrukturu vytvořením aplikace kontejneru pro hostování Postgres databáze. Příkaz azd provision neaktualizuje připojovací řetězce pro kontejner apiservice. Aby se připojovací řetězce aktualizovaly tak, aby odkazovaly na nově zřízenou Postgres databázi, je potřeba znovu vyvolat příkaz azd deploy. Pokud máte pochybnosti, použijte azd up ke zřízení i nasazení.

Vyčištění prostředků

Nezapomeňte vyčistit Azure prostředky, které jste vytvořili během tohoto návodu. Vzhledem k tomu, že azd zná skupinu prostředků, ve které vytvořil prostředky, lze ji použít k vypnutí prostředí pomocí následujícího příkazu:

azd down

Provedení předchozího příkazu může nějakou dobu trvat, ale po jeho dokončení by měla být skupina prostředků a všechny její prostředky odstraněny.

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.

Vygenerovat Bicep z modelu projektu .NET.NET Aspire

I když vývojové týmy mohou pro svá nasazení používat příkazy azd up (nebo azd provision a azd deploy), některé týmy se můžou rozhodnout generovat soubory Bicep, které můžou kontrolovat a spravovat jako součást správy verzí (to také umožňuje odkazovat na tyto soubory Bicep jako součást rozsáhlejšího složitějšího nasazení Azure).

azd umožňuje export Bicep, který používá ke zřizování, pomocí následujícího příkazu:

azd config set alpha.infraSynth on
azd infra synth

Po spuštění tohoto příkazu v příkladu úvodní šablony použité v této příručce se v adresáři projektu App Host vytvoří následující soubory:

infra/main.bicep: Představuje hlavní vstupní bod nasazení.
infra/main.parameters.json: Používá se jako parametry pro hlavní Bicep (je mapován na proměnné prostředí definované ve složce .azure).
infra/resources.bicep: Definuje Azure prostředky potřebné pro podporu modelu projektu .NET Aspire.
AspireSample.Web/manifests/containerApp.tmpl.yaml: Definice aplikace kontejneru pro webfrontend.
AspireSample.ApiService/manifests/containerApp.tmpl.yaml: Definice aplikace kontejneru pro apiservice.

Soubor infrastruktury\resources.bicep neobsahuje žádnou definici samotných aplikací kontejneru (s výjimkou aplikací kontejnerů, které jsou závislostmi, jako jsou Redis a 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

Další informace o použití Bicep k automatizaci nasazení do Azure najdete v tématu Co je Bicep?

Definice aplikací kontejnerů z projektů služby .NET jsou obsaženy v souborech containerApp/tmpl.yaml, které se nacházejí v adresářích manifests v každém projektu. Tady je příklad z projektu webfrontend:

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

Po spuštění příkazu azd infra synth jsou při volání azd provision a azd deploy použity Bicep a podporující vygenerované soubory.

Důležitý

Pokud se azd infra synth znovu zavolá, nahradí všechny změněné soubory nově vygenerovanými soubory a před tím vás vyzve k potvrzení.

Izolovaná prostředí pro ladění

Vzhledem k tomu, že azd usnadňuje zřizování nových prostředí, je možné, aby každý člen týmu měl izolované prostředí hostované v cloudu pro ladění kódu v nastavení, které úzce odpovídá produkčnímu prostředí. Když to uděláte, měl by každý člen týmu vytvořit vlastní prostředí pomocí následujícího příkazu:

azd env new

Tím se znovu zobrazí výzva k zadání informací o předplatném a skupině prostředků a následné azd up, azd provisiona azd deploy vyvolání budou ve výchozím nastavení používat toto nové prostředí. Přepínač --environment lze na tyto příkazy použít k přepínání mezi prostředími.

Vyčištění prostředků

Spuštěním následujícího příkazu rozhraní příkazového řádku Azure odstraňte skupinu prostředků, pokud už nepotřebujete Azure prostředky, které jste vytvořili. Odstraněním skupiny prostředků se odstraní také prostředky obsažené v této skupině.

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

Další informace si můžete prohlédnout v části Vyčištění prostředků v Azure.

Sdílet prostřednictvím

Nasazení projektu .NET Aspire do Azure Container Apps pomocí Azure Developer CLI (podrobný průvodce)

Požadavky

Jak funguje integrace Azure Developer CLI

Zřízení a nasazení úvodní aplikace .NET.NET Aspire

Vytvoření úvodní aplikace .NET.NET Aspire

Inicializujte šablonu

Pojmenování prostředků

Počáteční nasazení

Nasazení aktualizací aplikací

Nasazení aktualizací infrastruktury

Vyčištění prostředků

Vygenerovat Bicep z modelu projektu .NET.NET Aspire

Izolovaná prostředí pro ladění

Vyčištění prostředků

Další materiály