Samouczek: wdrażanie projektu .NET Aspire przy użyciu akcji Azure Developer CLI i GitHub

Artykuł
12/13/2024

Azure Developer CLI (azd) umożliwia wdrażanie projektów .NET Aspire przy użyciu GitHub Actions przez automatyczne konfigurowanie wymaganych ustawień uwierzytelniania i środowiska. W tym artykule przedstawiono proces tworzenia i wdrażania projektu .NET Aspire na platformie Azure Container Apps przy użyciu azd i akcji GitHub. Poznasz następujące pojęcia:

Dowiedz się, jak integracja azd działa z projektami .NET Aspire i akcjami GitHub
Tworzenie i konfigurowanie repozytorium GitHub dla projektu .NET Aspire przy użyciu azd
Dodawanie pliku przepływu pracy akcji GitHub do rozwiązania .NET Aspire
Monitorowanie i eksplorowanie wykonań przepływów pracy GitHub Actions oraz wdrożeń Azure

Warunki wstępne

Aby pracować z .NET.NET Aspire, musisz mieć zainstalowane lokalnie następujące elementy:

.NET 8.0 lub .NET 9.0
Środowisko uruchomieniowe kontenera zgodne ze standardem OCI, takie jak:
- Docker Desktop lub Podman. Aby uzyskać więcej informacji, zobacz Container Runtime.
Zintegrowane środowisko deweloperskie (IDE) lub edytor kodu, takie jak:
- Visual Studio 2022 w wersji 17.9 lub nowszej (opcjonalnie)
- Visual Studio Code (opcjonalnie)
  - C# Dev Kit: Rozszerzenie (opcjonalnie)
- JetBrains Rider z wtyczką .NET.NET Aspire (opcjonalnie)

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire setup and toolingi .NET.NET Aspire SDK.

Azure organizację DevOps lub wybierz istniejącą organizację
Utwórz Azure osobisty token dostępu DevOps (PAT) i zapisz go do późniejszego użycia. Skonfiguruj token z następującymi uprawnieniami:
- Pule agentów (odczyt, zarządzanie)
- Kompilacja (odczyt i wykonanie)
- Kod (pełny)
- Projekt i zespół (odczyt, zapis i zarządzanie)
- Wydanie (odczyt, zapis, wykonywanie i zarządzanie)
- Połączenia usług (odczyt, wykonywanie zapytań i zarządzanie)

Musisz również zainstalować Azure Developer CLIlokalnie (wersja 1.5.1 lub nowsza). Typowe opcje instalacji obejmują następujące elementy:

Windows
systemu macOS
Linux

winget install microsoft.azd

brew tap azure/azd && brew install azd

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

Utwórz rozwiązanie .NET.NET Aspire

W tym artykule przyjęto założenie, że utworzono rozwiązanie .NET.NET Aspire na podstawie szablonu .NET.NET Aspire Starter Application. Aby uzyskać więcej informacji, zobacz Szybki start: tworzenie pierwszej aplikacji .NET.NET Aspire.

Inicjowanie szablonu

Otwórz nowe okno terminalu i cd w katalogu projektu AppHost rozwiązania .NET.NET Aspire.
Wykonaj polecenie azd init, aby zainicjować projekt przy użyciu azd, co spowoduje sprawdzenie struktury katalogów lokalnych i określenie typu aplikacji.
```
azd init
```
Aby uzyskać więcej informacji na temat polecenia azd init, zobacz azd init.

Wybierz pozycję Użyj kodu w bieżącym katalogu, gdy azd wyświetli monit o dwie opcje inicjowania aplikacji.

? 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 zeskanowaniu katalogu azd zostanie wyświetlony monit o potwierdzenie, że został znaleziony prawidłowy projekt .NET.NET AspireAppHost. Wybierz opcję Potwierdź i kontynuuj inicjowanie mojej aplikacji.

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

Wprowadź nazwę środowiska, która będzie używana do nazywania aprowizowanych zasobów w Azure oraz zarządzania różnymi środowiskami, takimi jak dev i 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 generuje wiele plików i umieszcza je w katalogu roboczym. Są to następujące pliki:

azure.yaml: opisuje usługi aplikacji, takie jak projekt .NET Aspire AppHost, i mapuje je na zasoby Azure.
.azure/config.json: plik konfiguracji, który informuje azd, jakie jest bieżące aktywne środowisko.
.azure/aspireazddev/.env: zawiera przesłonięcia specyficzne dla środowiska.

Dodawanie pliku przepływu pracy GitHub Actions

Mimo że azd wygenerował kilka podstawowych plików szablonów, projekt nadal potrzebuje pliku workflow dla GitHub Actions, aby wspierać aprowizację i wdrożenia przy użyciu CI/CD.

Utwórz pusty .github folder w katalogu głównym projektu. azd używa tego katalogu domyślnie do odnajdywania plików przepływu pracy GitHub Actions.
Napiwek

Jeśli jesteś użytkownikiem systemu macOS i masz problemy z utworzeniem folderu z wiodącym ., możesz użyć terminalu, aby utworzyć folder. Otwórz terminal i przejdź do katalogu głównego projektu. Uruchom następujące polecenie, aby utworzyć folder:
```
mkdir .github
```
Wewnątrz nowej .github folderze utwórz inny folder o nazwie przepływów pracy (.github/workflows).
Dodaj nowy plik przepływu pracy GitHub Actions do nowego folderu o nazwie azure-dev.yml. Szablon startowy azd zawiera przykładowy plik przepływu pracy GitHub Actions, który można skopiować do projektu.

Zaktualizuj przykładowy przepływ pracy GitHub Actions, aby uwzględnić krok instalacji obciążenia .NET Aspire. Gwarantuje to, że narzędzia i polecenia .NET Aspire są dostępne dla zadania uruchamiającego akcje GitHub. Ukończony plik przepływu pracy powinien być zgodny z następującymi elementami:

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

Możesz także zauważyć, że kroki aprowizacji i wdrażania są połączone w jedno zadanie. Jeśli wolisz oddzielić te kroki do różnych zadań, możesz to zrobić, tworząc dwa oddzielne zadania w pliku przepływu pracy. Zadanie provisioningu powinno zostać uruchomione jako pierwsze, a następnie zadanie wdrożenia. Zadanie wdrożenia powinno zawierać tajny klucz AZD_INITIAL_ENVIRONMENT_CONFIG, aby upewnić się, że ma dostęp do konfiguracji środowiska. Należy również usunąć komentarz z kroku azd env refresh w zadaniu wdrażania, aby zapewnić zadaniu wdrożenia dostęp do najnowszej wersji dostarczonej infrastruktury.

Utwórz repozytorium GitHub i potok

Azure Developer CLI umożliwia automatyczne tworzenie potoków CI/CD z prawidłowymi konfiguracjami i uprawnieniami, aby aprowizować i wdrażać zasoby do Azure. azd również można utworzyć repozytorium GitHub dla Twojej aplikacji, jeśli jeszcze nie istnieje.

Uruchom polecenie azd pipeline config, aby skonfigurować potok wdrażania i bezpiecznie połączyć go z Azure:
```
azd pipeline config
```
Wybierz subskrypcję, w ramach której chcesz aprowizować i wdrożyć zasoby aplikacji.
Wybierz lokalizację Azure, która ma być używana dla zasobów.
Gdy zostanie wyświetlony monit o utworzenie nowego repozytorium Git w katalogu, wprowadź y i naciśnij Enter.

Notatka

Utworzenie repozytorium GitHub wymaga zalogowania się do GitHub. Istnieje kilka opcji, które różnią się w zależności od preferencji. Po zalogowaniu zostanie wyświetlony monit o utworzenie nowego repozytorium w bieżącym katalogu.
Wybierz pozycję , aby utworzyć nowe prywatne repozytorium GitHub i skonfigurować zdalne repozytorium git.
Wprowadź wybraną nazwę nowego repozytorium GitHub lub naciśnij Enter, aby użyć nazwy domyślnej. azd tworzy nowe repozytorium w GitHub i konfiguruje je z niezbędnymi tajnymi danymi wymaganymi do uwierzytelnienia w Azure.
Wprowadź y, aby kontynuować, gdy azd monituje o zatwierdzenie i wypchnięcie lokalnych zmian w celu uruchomienia skonfigurowanego potoku.

Eksploruj przepływ pracy i wdrażanie Actions GitHub

Przejdź do nowego repozytorium GitHub, korzystając z linku, który został wyświetlony przez azd.
Wybierz kartę Akcje, aby wyświetlić przepływy pracy repozytorium. Powinieneś zobaczyć nowy przepływ pracy albo uruchomiony, albo już ukończony. Wybierz przepływ pracy, aby wyświetlić kroki zadania i szczegóły w dziennikach przebiegu. Możesz na przykład rozwinąć kroki, takie jak Instalowanie obciążenia .NET.NET Aspire lub Wdrażanie aplikacji, aby wyświetlić szczegóły ukończonej akcji.
Wybierz pozycję Wdróż aplikację, aby rozwinąć dzienniki dla tego kroku. Powinny być wydrukowane dwa adresy URL punktów końcowych dla apiservice i webfrontend. Wybierz jeden z tych linków, aby otworzyć go na innej karcie przeglądarki i zapoznać się z wdrożoną aplikacją.

Gratulacje! Projekt .NET Aspire został pomyślnie wdrożony przy użyciu działań Azure Developer CLI i GitHub.

Konfigurowanie pliku przepływu pracy

Mimo że azd wygenerował kilka podstawowych plików szablonów, projekt nadal potrzebuje pliku przepływu pracy Azure Pipelines w celu obsługi procesu aprowizacji i wdrożeń przy użyciu CI/CD.

Utwórz pusty folder .azdo w katalogu głównym projektu. azd używa tego katalogu domyślnie do odnajdywania plików przepływu pracy Azure Pipelines.
Wewnątrz nowego folderu .azdo utwórz inny folder o nazwie pipelines (skończysz z .azdo/pipelines).
Dodaj nowy plik workflow Pipelines Azure do nowego folderu o nazwie azure-dev.yml. Szablon startowy azd zawiera przykładowy plik przepływu pracy potoków Azure, który można skopiować do projektu.
Zaktualizuj przykładowy przepływ pracy potoków Azure, aby uwzględnić krok instalacji obciążenia .NET Aspire. Ukończony plik przepływu pracy powinien być zgodny z następującymi elementami:

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)

Utwórz repozytorium i potok Azure DevOps

Ważny

Jak wspomniano w wymaganiach wstępnych, musisz utworzyć organizację usługi Azure DevOps lub wybrać istniejącą organizację, aby wykonać następujące kroki. Należy również utworzyć osobisty token dostępu (PAT) z uprawnieniami wymienionymi w wymaganiach wstępnych.

Azure Developer CLI umożliwia automatyczne tworzenie potoków przy użyciu prawidłowych konfiguracji i uprawnień do aprowizowania i wdrażania zasobów w Azure. azd można również utworzyć repozytorium Azure Pipelines dla aplikacji, jeśli jeszcze nie istnieje.

Uruchom polecenie azd pipeline config, aby skonfigurować potok wdrażania i bezpiecznie połączyć go z Azure. Uwzględnij opcję --provider azdo, aby użyć Azure Pipelines zamiast domyślnej konfiguracji GitHub Actions.
```
azd pipeline config --provider azdo
```
Wybierz subskrypcję, w ramach której chcesz aprowizować i wdrożyć zasoby aplikacji.
Wybierz lokalizację Azure, która ma być używana dla zasobów.
Wklej utworzony wcześniej osobisty token dostępu.
Wprowadź nazwę organizacji Azure DevOps utworzoną lub wybraną.
Po wyświetleniu monitu o utworzenie nowego repozytorium w bieżącym katalogu wprowadź i i naciśnij Enter.
Po wyświetleniu monitu o skonfigurowanie zdalnego git wybierz pozycję Utwórz nowy projekt DevOps Azure.
Wprowadź unikatową nazwę nowego repozytorium, na przykład aspireazd. azd tworzy nowe repozytorium w usłudze Azure Repos i konfiguruje je z użyciem niezbędnych tajnych danych wymaganych do uwierzytelniania z Azure.
Wprowadź y, aby kontynuować, gdy azd monituje o zatwierdzenie i wypchnięcie lokalnych zmian w celu uruchomienia skonfigurowanego potoku.

Zbadaj potok danych i aplikację

Przejdź do nowego pipeline'u Azure, korzystając z linku statusu dostarczonego przez azd.
Wybierz ukończone uruchomienie potoku, aby wyświetlić podsumowanie.
Wybierz link zadania w dolnej części widoku, aby przejść do szczegółów zadania.
Na stronie szczegółów zadania jest wyświetlany stan wszystkich poszczególnych etapów. Wybierz pozycję Aprowizacja infrastruktury, aby wyświetlić dzienniki dla tego etapu, które szczegółowo opisują wszystkie kroki aprowizacji wykonane przez azd. W dolnej części dzienników zanotuj końcowy komunikat o stanie i połącz się z aprowizowaną grupą zasobów Azure.
Wybierz link na dole dzienników wyników aprowizacji, aby nawigować do nowej grupy zasobów Azure.

Notatka

Możesz również przejść bezpośrednio do nowej grupy zasobów, wyszukując ją w portalu Azure. Nazwa grupy zasobów będzie nazwą środowiska, którą podałeś do azd z prefiksem rg-.
Wybierz kontenerową aplikację webfrontend, która hostuje część witryny dostępną publicznie.
Na stronie szczegółów webfrontend wybierz link Application Url, aby otworzyć swoją witrynę w przeglądarce.

Ważny

Jeśli podczas wyświetlania witryny w przeglądarce wystąpi błąd 403 Forbidden, upewnij się, że ustawienia ruchu przychodzącego są poprawnie skonfigurowane. Na stronie aplikacji w portalu Azure przejdź do Ingress w lewym panelu nawigacyjnym. Upewnij się, że ruch przychodzący jest ustawiony na Akceptowanie ruchu z dowolnego miejsca i zapisz zmiany.

Gratulacje! Pomyślnie wdrożono projekt .NET Aspire przy użyciu pipeline'ów Azure Developer CLI i Azure.

Czyszczenie zasobów

Uruchom następujące polecenie interfejsu wiersza polecenia Azure, aby usunąć grupę zasobów, gdy nie potrzebujesz już utworzonych zasobów Azure. Usunięcie grupy zasobów powoduje również usunięcie zawartych w niej zasobów.

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

Aby dowiedzieć się więcej, zobacz Czyszczenie zasobów w Azure.

Udostępnij za pośrednictwem