Tutorial: Bereitstellen eines .NET Aspire-Projekts mit den Azure Developer CLI- und GitHub-Aktionen

Artikel
12/13/2024

Mit dem Azure Developer CLI (azd) können Sie .NET Aspire Projekte mithilfe von GitHub Aktionen bereitstellen, indem Sie die erforderlichen Authentifizierungs- und Umgebungseinstellungen automatisch konfigurieren. Dieser Artikel führt Sie durch den Prozess des Erstellens und Bereitstellens eines .NET Aspire-Projekts auf Azure Container Apps unter Verwendung von azd und GitHub-Aktionen. Sie lernen die folgenden Konzepte kennen:

Erfahren Sie, wie azd Integration mit .NET Aspire Projekten und GitHub Aktionen funktioniert
Erstellen und Konfigurieren eines GitHub Repositorys für ein .NET Aspire Projekt mithilfe von azd
Hinzufügen einer GitHub Aktionen-Workflowdatei zu Ihrer .NET Aspire Lösung
Überwachen und Untersuchen von GitHub Aktionen-Workflow-Ausführungen und Azure Bereitstellungen

Voraussetzungen

Um mit .NET.NET Aspirezu arbeiten, benötigen Sie folgendes lokal installiert:

.NET 8.0 oder .NET 9,0
Eine OCI-kompatible Containerlaufzeit, z. B.:
- Docker Desktop oder Podman. Weitere Informationen finden Sie unter container runtime.
Eine integrierte Entwicklerumgebung (Integrated Developer Environment, IDE) oder ein Code-Editor, z. B.:
- Visual Studio 2022 Version 17.9 oder höher (optional)
- Visual Studio Code (optional)
  - C# Dev Kit: Erweiterung (Optional)
- JetBrains Rider mit .NET.NET Aspire Plugin (Optional)

Weitere Informationen finden Sie unter .NET.NET Aspire Setup und Toolingsowie .NET.NET Aspire SDK.

Erstellen einer Azure DevOps-Organisation oder Auswählen einer vorhandenen Organisation
Erstellen Sie ein Azure DevOps Personal Access Token (PAT) und speichern Sie es zur späteren Verwendung. Konfigurieren Sie das Token mit den folgenden Berechtigungen:
- Agentpools (lesen, verwalten)
- Build (Lesen und Ausführen)
- Code (vollständig)
- Projekt und Team (Lesen, Schreiben und Verwalten)
- Freigabe (Lesen, Schreiben, Ausführen und Verwalten)
- Dienstverbindungen (Lesen, Abfragen und Verwalten)

Sie müssen auch die Azure Developer CLIlokal (Version 1.5.1 oder höher) installiert haben. Zu den allgemeinen Installationsoptionen gehören die folgenden:

winget install microsoft.azd

brew tap azure/azd && brew install azd

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

Erstellen einer .NET.NET Aspire Lösung

Als Ausgangspunkt geht in diesem Artikel davon aus, dass Sie eine .NET.NET Aspire Lösung aus der Vorlage .NET.NET Aspire Starter Application erstellt haben. Weitere Informationen finden Sie unter Schnellstart: Erstellen Sie Ihre erste .NET.NET Aspire-App.

Vorlage initialisieren

Öffnen Sie ein neues Terminalfenster, und cd Sie in das AppHost- Projektverzeichnis Ihrer .NET.NET Aspire Lösung ein.
Führen Sie den befehl azd init aus, um Ihr Projekt mit azdzu initialisieren, wodurch die lokale Verzeichnisstruktur überprüft und der App-Typ bestimmt wird.
```
azd init
```
Weitere Informationen zum Befehl azd init finden Sie unter azd init.

Wählen Sie Code im aktuellen Verzeichnis nutzen aus, wenn azd Sie mit zwei App-Initialisierungsoptionen auffordert.

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

Nach dem Scannen des Verzeichnisses werden Sie von azd aufgefordert, zu bestätigen, dass es das richtige .NET.NET AspireAppHost- Projekt gefunden hat. Wählen Sie die Option "Bestätigen und fortfahren mit der Initialisierung meiner App" aus.

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

Geben Sie einen Umgebungsnamen ein, der verwendet wird, um bereitgestellte Ressourcen in Azure zu benennen und verschiedene Umgebungen wie dev und prodzu verwalten.

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 generiert eine Reihe von Dateien und platziert sie in das Arbeitsverzeichnis. Diese Dateien sind:

azure.yaml: Beschreibt die Dienste der App, z. B. .NET Aspire AppHost Projekt, und ordnet diese den Azure Ressourcen zu.
** .azure/config.json: Eine Konfigurationsdatei, die azd darüber informiert, welche die aktuell aktive Umgebung ist.
.azure/aspireazddev/.env: Enthält umgebungsspezifische Außerkraftsetzungen.

Hinzufügen der Workflowdatei GitHub Aktionen

Obwohl azd einige wichtige Vorlagendateien für Sie generiert hat, benötigt das Projekt weiterhin eine Actions-Workflow-Datei von GitHub, um Bereitstellungen mit CI/CD zu unterstützen.

Erstellen Sie einen leeren .github Ordner im Stammverzeichnis Ihres Projekts. azd verwendet dieses Verzeichnis standardmäßig, um GitHub Aktionen-Workflowdateien zu ermitteln.
Tipp

Wenn Sie macOS-Nutzer sind und Schwierigkeiten haben, einen Ordner mit einer führenden .zu erstellen, können Sie das Terminal verwenden, um den Ordner zu erstellen. Öffnen Sie das Terminal und navigieren Sie zum Stammverzeichnis Ihres Projekts. Führen Sie den folgenden Befehl aus, um den Ordner zu erstellen:
```
mkdir .github
```
Innerhalb der neuen .github Ordner erstellen Sie einen anderen Ordner namens Workflows (Sie erhalten .github/workflows).
Fügen Sie in den neuen Ordner azureeine neue -Aktionen-Workflowdatei hinzu. Die azd Startvorlage enthält eine Workflowdatei GitHub Aktionen, die Sie in Ihr Projekt kopieren können.

Aktualisieren Sie den Beispiel-GitHub-Workflow, um einen Schritt für die Installation der .NET Aspire-Arbeitslast hinzuzufügen. Dadurch wird sichergestellt, dass die .NET Aspire Werkzeuge und Befehle für den Job verfügbar sind, der Ihre GitHub Aktionen ausführt. Die abgeschlossene Workflowdatei sollte mit dem folgenden übereinstimmen:

on:
  workflow_dispatch:
  push:
    # Run when commits are pushed to mainline branch (main or master)
    # Set this to the mainline branch you are using
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install azd
        uses: Azure/setup-azd@v1.0.0

      - name: Install .NET Aspire workload
        run: dotnet workload install aspire

      - name: Log in with Azure (Federated Credentials)
        if: ${{ env.AZURE_CLIENT_ID != '' }}
        run: |
          azd auth login `
            --client-id "$Env:AZURE_CLIENT_ID" `
            --federated-credential-provider "github" `
            --tenant-id "$Env:AZURE_TENANT_ID"
        shell: pwsh

      - name: Log in with Azure (Client Credentials)
        if: ${{ env.AZURE_CREDENTIALS != '' }}
        run: |
          $info = $Env:AZURE_CREDENTIALS | ConvertFrom-Json -AsHashtable;
          Write-Host "::add-mask::$($info.clientSecret)"

          azd auth login `
            --client-id "$($info.clientId)" `
            --client-secret "$($info.clientSecret)" `
            --tenant-id "$($info.tenantId)"
        shell: pwsh

      - name: Provision Infrastructure
        run: azd provision --no-prompt
        # Required when 
        # env:
        #   AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}

      # Required when provisioning and deploying are defined in separate jobs.
      # - name: Refresh azd env (pulls latest infrastructure provision)
      #  run: azd env refresh
      #  env:
      #    AZURE_LOCATION: ${{ env.AZURE_LOCATION }}

      - name: Deploy Application
        run: azd deploy --no-prompt

Darüber hinaus stellen Sie möglicherweise fest, dass die Bereitstellungs- und Bereitstellungsschritte in einem einzigen Auftrag kombiniert werden. Wenn Sie diese Schritte lieber in verschiedene Aufträge unterteilen möchten, können Sie dazu zwei separate Aufträge in der Workflowdatei erstellen. Der Bereitstellungsauftrag sollte zuerst ausgeführt werden, gefolgt vom Bereitstellungsauftrag. Der Bereitstellungsauftrag sollte den AZD_INITIAL_ENVIRONMENT_CONFIG geheimen Schlüssel enthalten, um sicherzustellen, dass der Bereitstellungsauftrag Zugriff auf die Umgebungskonfiguration hat. Sie müssen den Kommentar zum Schritt azd env refresh im Deploy-Auftrag aufheben, um sicherzustellen, dass er Zugriff auf die neueste Infrastructure-Provision hat.

Erstellen des GitHub Repositorys und der Pipeline

Mit dem Azure Developer CLI können Sie CI/CD-Pipelines mit den richtigen Konfigurationen und Berechtigungen automatisch erstellen, um Ressourcen auf Azurebereitzustellen und zu veröffentlichen. azd kann auch ein GitHub-Repository für Ihre App erstellen, falls es noch nicht existiert.

Führen Sie den Befehl azd pipeline config aus, um Die Bereitstellungspipeline zu konfigurieren und sicher mit Azurezu verbinden:
```
azd pipeline config
```
Wählen Sie das Abonnement aus, in dem die App-Ressourcen bereitgestellt und eingesetzt werden sollen.
Wählen Sie den Azure Speicherort aus, der für die Ressourcen verwendet werden soll.
Wenn Sie aufgefordert werden, ein neues Git Repository im Verzeichnis zu erstellen, geben Sie und ein, und drücken Sie EINGABETASTE.

Anmerkung

Zum Erstellen eines GitHub Repositorys mussten Sie bei GitHubangemeldet sein. Es gibt einige Auswahlmöglichkeiten, die je nach Ihren Vorlieben variieren. Nach der Anmeldung werden Sie aufgefordert, ein neues Repository im aktuellen Verzeichnis zu erstellen.
Wählen Sie , um ein neues privates GitHub Repository zu erstellen und die git Remote zu konfigurieren.
Geben Sie einen Namen Ihrer Wahl für das neue GitHub Repository ein, oder drücken Sie die EINGABETASTE, um den Standardnamen zu verwenden. azd erstellt ein neues Repository in GitHub und konfiguriert es mit den erforderlichen Geheimschlüsseln, die für die Authentifizierung bei Azureerforderlich sind.
Geben Sie und ein, um fortzufahren, wenn azd Sie auffordert, einen Commit auszuführen und Ihre lokalen Änderungen zu übertragen, um die konfigurierte Pipeline zu starten.

Erkunden Sie den GitHub-Workflow und die Bereitstellung von Aktionen.

Navigieren Sie mittels des Links, den GitHubausgibt, zu Ihrem neuen azd-Repository.
Wählen Sie die Registerkarte Aktionen aus, um die Repository-Workflows anzuzeigen. Der neue Workflow sollte entweder ausgeführt oder bereits abgeschlossen sein. Wählen Sie den Workflow aus, um die Auftragsschritte und Details in den Protokollen der Ausführung anzuzeigen. Sie können z. B. Schritte wie installieren .NET.NET Aspire Workload oder Anwendung bereitstellen erweitern, um die Details der abgeschlossenen Aktion anzuzeigen.
Wählen Sie Anwendungsbereitstellung aus, um die Protokolle für diesen Schritt zu erweitern. Es sollten zwei Endpunkt-URLs für apiservice und webfrontendausgegeben werden. Wählen Sie einen dieser Links aus, um sie auf einer anderen Browserregisterkarte zu öffnen und die bereitgestellte Anwendung zu erkunden.

Glückwunsch! Sie haben erfolgreich ein .NET Aspire Projekt mithilfe der Azure Developer CLI und GitHub Aktionen eingesetzt.

Konfigurieren der Workflow-Datei

Obwohl azd einige wichtige Vorlagendateien für Sie generiert hat, benötigt das Projekt weiterhin eine Azure Pipelines-Workflowdatei, um Bereitstellung und Implementierung mit CI/CD zu unterstützen.

Erstellen Sie einen leeren .azdo Ordner im Stammverzeichnis des Projekts. azd verwendet dieses Verzeichnis standardmäßig, um Azure Pipelines-Workflowdateien zu ermitteln.
Erstellen Sie im neuen .azdo Ordner einen weiteren Ordner namens Pipelines (Das Ergebnis ist .azdo/pipelines).
Fügen Sie eine neue Azure Pipelines-Workflowdatei in den neuen Ordner mit dem Namen azure-dev.ymlhinzu. Die azd Startvorlage stellt eine Beispiel-Pipeline-Workflowdatei Azure bereit, die Sie in Ihr Projekt kopieren können.
Aktualisieren Sie den Beispiel-Workflow Azure Pipelines, um einen Schritt zum Installieren der .NET Aspire Workload einzuschließen. Die abgeschlossene Workflowdatei sollte mit dem folgenden übereinstimmen:

trigger:
  - main
  - master

pool:
  vmImage: ubuntu-latest

steps:

  - task: Bash@3
    displayName: Install azd
    inputs:
      targetType: 'inline'
      script: |
        curl -fsSL https://aka.ms/install-azd.sh | bash

  # azd delegate auth to az to use service connection with AzureCLI@2
  - pwsh: |
      azd config set auth.useAzCliAuth "true"
    displayName: Configure `azd` to Use AZ CLI Authentication.

  - task: Bash@3
    displayName: Install .NET Aspire workload
    inputs:
      targetType: 'inline'
      script: |
        dotnet workload install aspire

  - task: AzureCLI@2
    displayName: Provision Infrastructure
    inputs:
      azureSubscription: azconnection
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        azd provision --no-prompt
    env:
      AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
      AZURE_ENV_NAME: $(AZURE_ENV_NAME)
      AZURE_LOCATION: $(AZURE_LOCATION)

  - task: AzureCLI@2
    displayName: Deploy Application
    inputs:
      azureSubscription: azconnection
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        azd deploy --no-prompt
    env:
      AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
      AZURE_ENV_NAME: $(AZURE_ENV_NAME)
      AZURE_LOCATION: $(AZURE_LOCATION)

Erstellen Sie das Azure DevOps-Repository und die Pipeline

Wichtig

Wie in den Voraussetzungen erwähnt, müssen Sie eine Azure DevOps-Organisation erstellen bzw. eine vorhandene Organisation auswählen, um die nachfolgenden Schritte auszuführen. Sie müssen auch einen persönlichen Zugriffstoken (PAT) mit den in den Voraussetzungen aufgeführten Berechtigungen erstellen.

Mit dem Azure Developer CLI können Sie Pipelines automatisch mit den richtigen Konfigurationen und Berechtigungen erstellen, um Ressourcen für Azurebereitzustellen und zu implementieren. azd kann auch ein Azure Pipelines-Repository für Ihre App erstellen, sofern es noch nicht vorhanden ist.

Führen Sie den Befehl azd pipeline config aus, um die Bereitstellungspipeline zu konfigurieren und sie sicher mit Azurezu verbinden. Fügen Sie die Option --provider azdo hinzu, um Azure Pipelines anstelle der Standardkonfiguration GitHub Aktionen zu verwenden.
```
azd pipeline config --provider azdo
```
Wählen Sie das Abonnement aus, in dem die App-Ressourcen bereitgestellt und eingesetzt werden sollen.
Wählen Sie den Azure Speicherort aus, der für die Ressourcen verwendet werden soll.
Fügen Sie das zuvor erstellte persönliche Zugriffstoken ein.
Geben Sie den namen der Azure DevOps-Organisation ein, den Sie erstellt oder ausgewählt haben.
Wenn Sie aufgefordert werden, ein neues Repository im aktuellen Verzeichnis zu erstellen, geben Sie y ein und drücken Sie die Eingabetaste.
Wenn Sie aufgefordert werden, die git Remote zu konfigurieren, wählen Sie Neues Azure DevOps-Projekt erstellenaus.
Geben Sie einen eindeutigen Namen Ihrer Wahl für das neue Repository ein, z. B. aspireazd. azd erstellt ein neues Repository in Azure Repos und konfiguriert es mit den erforderlichen geheimen Schlüsseln, die für die Authentifizierung bei Azureerforderlich sind.
Geben Sie und ein, um fortzufahren, wenn azd Sie auffordert, einen Commit auszuführen und Ihre lokalen Änderungen zu übertragen, um die konfigurierte Pipeline zu starten.

Erkunden Sie die Pipeline und die bereitgestellte App

Zur neuen Azure-Pipeline navigieren Sie über den Statuslink, der von azdausgegeben wird.
Wählen Sie die abgeschlossene Pipelineausführung aus, um die Zusammenfassung anzuzeigen.
Wählen Sie den Joblink am unteren Rand der Ansicht aus, um zu den Jobdetails zu gelangen.
Auf der Seite "Auftragsdetails" wird der Status aller einzelnen Phasen angezeigt. Wählen Sie Bereitstellungsinfrastruktur aus, um die Protokolle für diese Phase anzuzeigen, die alle Bereitstellungsschritte enthalten, die von azdabgeschlossen wurden. Notieren Sie sich am Ende der Protokolle die endgültige Statusmeldung und den Link zur bereitgestellten Azure-Ressourcengruppe.
Wählen Sie den Link unten in den Bereitstellungsausgabeprotokollen aus, um zur neuen Azure Ressourcengruppe zu navigieren.

Anmerkung

Sie können auch direkt zu Ihrer neuen Ressourcengruppe navigieren, indem Sie im Azure Portal danach suchen. Ihr Ressourcengruppenname ist der Umgebungsname, den Sie azd mit dem Präfix "rg-" angegeben haben.
Wählen Sie die webfrontend Container-App aus, die den öffentlich zugänglichen Teil Ihrer Website hosten soll.
Wählen Sie auf der webfrontend Detailseite den Link Anwendungs-URL aus, um Ihre Website im Browser zu öffnen.

Wichtig

Wenn beim Anzeigen Ihrer Website im Browser ein 403 Forbidden-Fehler auftritt, stellen Sie sicher, dass die Ingress-Einstellungen ordnungsgemäß konfiguriert sind. Navigieren Sie auf der webfrontend App-Seite im Azure Portal zu Ingress auf der linken Navigationsleiste. Stellen Sie sicher, dass Eingangsverkehr auf Annehmen von Datenverkehr von überall festgelegt ist und speichern Sie Ihre Änderungen.

Glückwunsch! Sie haben erfolgreich ein .NET Aspire-Projekt mithilfe der Azure Developer CLI- und Azure-Pipeline bereitgestellt.

Bereinigen von Ressourcen

Führen Sie den folgenden Azure CLI-Befehl aus, um die Ressourcengruppe zu löschen, wenn Sie die von Ihnen erstellten Azure Ressourcen nicht mehr benötigen. Durch das Löschen der Ressourcengruppe werden auch die darin enthaltenen Ressourcen gelöscht.

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

Weitere Informationen finden Sie unter Ressourcen bereinigen in Azure.

Freigeben über