Tutorial: Implantar um projeto de .NET Aspire usando as ações de Azure Developer CLI e GitHub

Artigo
12/14/2024

O Azure Developer CLI (azd) permite implantar projetos .NET Aspire usando ações de GitHub definindo automaticamente as configurações de autenticação e ambiente necessárias. Este artigo orienta você pelo processo de criação e implantação de um projeto de .NET Aspire em Azure Container Apps usando ações de azd e GitHub. Você aprenderá os seguintes conceitos:

Explore como a integração azd funciona com .NET Aspire projetos e Ações GitHub
Criar e configurar um repositório GitHub para um projeto de .NET Aspire usando azd
Adicionar um arquivo de fluxo de trabalho do GitHub Actions à solução .NET Aspire
Monitorar e explorar as execuções de fluxos de trabalho do GitHub Actions e as implantações do Azure

Pré-requisitos

Para trabalhar com .NET.NET Aspire, você precisa do seguinte instalado localmente:

.NET 8.0 ou .NET 9.0
Um runtime de contêiner compatível com OCI, como:
- Docker Desktop ou Podman. Para obter mais informações, consulte runtime do contêiner.
Um IDE (Ambiente de Desenvolvedor Integrado) ou um editor de código, como:
- Visual Studio 2022 versão 17.9 ou superior (opcional)
- Visual Studio Code (opcional)
  - C# Dev Kit: de extensão (opcional)
- JetBrains Rider com .NET.NET Aspire plug-in (opcional)

Para obter mais informações, consulte .NET.NET Aspirede instalação e ferramentas e .NET.NET Aspiredo SDK.

Criar uma organização Azure DevOps ou escolher uma organização existente
Criar um PAT (Token de Acesso Pessoal) Azure DevOps e salvá-lo para uso posterior. Configure o token com as seguintes permissões:
- Conjuntos de agentes (ler, gerenciar)
- Compilar (ler e executar)
- Código (completo)
- Projeto e equipe (ler, escrever e gerenciar)
- Liberação (ler, gravar, executar e gerenciar)
- Conexões de Serviço (ler, consultar e gerenciar)

Você também precisa ter o Azure Developer CLIinstalado localmente (versão 1.5.1 ou superior). As opções comuns de instalação incluem o seguinte:

Windows
macOS
Linux

winget install microsoft.azd

brew tap azure/azd && brew install azd

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

Criar uma solução de .NET.NET Aspire

Como ponto de partida, este artigo pressupõe que você criou uma solução .NET.NET Aspire a partir do modelo .NET.NET Aspire de Aplicativo Inicial. Para obter mais informações, consulte Início Rápido: Criar seu primeiro aplicativo .NET.NET Aspire.

Inicializar o modelo

Abra uma nova janela de terminal e cd no diretório de projeto do AppHost de sua solução de .NET.NET Aspire.
Execute o comando azd init para inicializar seu projeto com azd, que inspecionará a estrutura do diretório local e determinará o tipo de aplicativo.
```
azd init
```
Para obter mais informações sobre o comando azd init, consulte azd init.

Selecione Usar código no diretório atual quando azd solicitar duas opções de inicialização de aplicativo.

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

Depois de verificar o diretório, solicitará que você confirme que ele encontrou o projeto de AppHost correto. Selecione a opção Confirmar e continue inicializando meu aplicativo.

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

Insira um nome de ambiente, que é usado para nomear recursos provisionados em Azure e gerenciar ambientes diferentes, como dev e 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 gera vários arquivos e os coloca no diretório de trabalho. Estes arquivos são:

azure .yaml: descreve os serviços do aplicativo, como .NET Aspire projeto AppHost, e os mapeia para Azure recursos.
.azure/config.json: arquivo de configuração que informa azd qual é o ambiente ativo atual.
.azure/aspireazddev/.env: Contém substituições específicas do ambiente.

Adicionar o arquivo de fluxo de trabalho do GitHub Actions

Embora o azd tenha gerado alguns arquivos de modelo essenciais para você, o projeto ainda precisa de um arquivo de fluxo de trabalho do Actions GitHub para suportar o provisionamento e as implantações usando CI/CD.

Crie uma pasta .github vazia na raiz do seu projeto. azd usa esse diretório por padrão para descobrir arquivos de fluxo de trabalho do GitHub Actions.
Dica

Se você estiver usando macOS e estiver tendo dificuldade para criar uma pasta começando com ., poderá usar o terminal para criar a pasta. Abra o terminal e navegue até a raiz do projeto. Execute o seguinte comando para criar a pasta:
```
mkdir .github
```
Dentro do novo .github pasta, crie outra pasta chamada fluxos de trabalho (você acabará com .github/fluxos de trabalho).
Adicione um novo arquivo de fluxo de trabalho do GitHub Actions à nova pasta chamada azure-dev.yml. O modelo inicial do azd fornece um arquivo de exemplo de fluxo de trabalho de ações GitHub que você pode copiar para o seu projeto.

Atualize o fluxo de trabalho GitHub Actions de exemplo para incluir uma etapa para instalar a carga de trabalho .NET Aspire. Isso garante que as ferramentas e comandos .NET Aspire estejam disponíveis para a tarefa que executa as suas Ações GitHub. O arquivo de fluxo de trabalho concluído deve corresponder ao seguinte:

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

Além disso, você pode observar que as etapas de provisionamento e implantação são combinadas em um único trabalho. Se você preferir separar essas etapas em trabalhos diferentes, poderá fazer isso criando dois trabalhos separados no arquivo de fluxo de trabalho. O trabalho de provisionamento deve ser executado primeiro, seguido pelo trabalho de implantação. O trabalho de implantação deve incluir o segredo AZD_INITIAL_ENVIRONMENT_CONFIG para garantir que o trabalho de implantação tenha acesso à configuração do ambiente. Você também precisaria descompactar a etapa azd env refresh no trabalho de implantação para garantir que o trabalho de implantação tenha acesso ao provisionamento de infraestrutura mais recente.

Criar o repositório GitHub e o pipeline

O Azure Developer CLI permite que você crie automaticamente pipelines de CI/CD com as configurações e permissões corretas para provisionar e implantar recursos no Azure. azd também poderá criar um repositório GitHub para seu aplicativo se ele ainda não existir.

Execute o comando azd pipeline config para configurar o pipeline de implantação e conectá-lo com segurança ao Azure:
```
azd pipeline config
```
Selecione a assinatura para a qual provisionar e implantar os recursos do aplicativo.
Selecione o local Azure para usar os recursos.
Quando solicitado a criar um novo repositório Git no diretório, insira e e pressione Enter.

Nota

A criação de um repositório GitHub exigia que você fosse conectado ao GitHub. Há algumas seleções que variam de acordo com suas preferências. Depois de fazer logon, você será solicitado a criar um novo repositório no diretório atual.
Selecione Criar um novo repositório de GitHub privado para configurar o git remoto.
Insira um nome de sua escolha para o novo repositório GitHub ou pressione Enter para usar o nome padrão. azd cria um novo repositório no GitHub e o configura com os segredos necessários para autenticar no Azure.
Insira y continuar quando azd solicitar que você confirme e envie por push suas alterações locais para iniciar o pipeline configurado.

Explorar o fluxo de trabalho e a implantação do GitHub Actions

Navegue até o novo repositório GitHub usando o link fornecido por azd.
Selecione a guia Ações para exibir os fluxos de trabalho do repositório. Você deve ver o novo fluxo de trabalho em execução ou já concluído. Selecione o fluxo de trabalho para exibir as etapas de trabalho e os detalhes nos logs da execução. Por exemplo, você pode expandir etapas como instalar .NET.NET Aspire Carga de Trabalho ou implantar aplicativo para ver os detalhes da ação concluída.
Selecione Implantar Aplicativo para expandir os logs daquela etapa. Você deverá ver duas URLs de ponto de extremidade impressas para o apiservice e webfrontend. Selecione qualquer um desses links para abri-los em outra guia do navegador e explorar o aplicativo implantado.

Parabéns! Você implantou com êxito um projeto de .NET Aspire usando as ações de Azure Developer CLI e GitHub.

Configurar o arquivo de fluxo de trabalho

Embora azd tenha gerado alguns arquivos de modelo essenciais para você, o projeto ainda precisa de um arquivo de fluxo de trabalho do Pipelines Azure para dar suporte ao provisionamento e às implantações usando CI/CD.

Crie uma pasta de .azdo vazia na raiz do projeto. azd usa esse diretório por padrão para descobrir arquivos de fluxo de trabalho do Azure Pipelines.
Dentro da nova pasta de .azdo, crie outra pasta chamada pipelines (você acabará com .azdo/pipelines).
Adicione um novo arquivo de fluxo de trabalho do Azure Pipelines à nova pasta chamada azure-dev.yml. O modelo inicial azd fornece um arquivo de fluxo de trabalho de pipelines de exemplo Azure que você pode copiar para o seu projeto.
Atualize o fluxo de trabalho de exemplo Azure pipelines para incluir uma etapa de instalação da carga de trabalho .NET Aspire. O arquivo de fluxo de trabalho concluído deve corresponder ao seguinte:

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)

Criar o repositório e o pipeline Azure DevOps

Importante

Conforme mencionado nos pré-requisitos, você precisará criar uma organização Azure DevOps ou selecionar uma organização existente para concluir os passos a seguir. Você também precisará criar um Token de Acesso Pessoal (PAT) com as permissões listadas nos pré-requisitos.

O Azure Developer CLI permite que você crie automaticamente pipelines com as configurações e permissões corretas para provisionar e implantar recursos no Azure. azd também poderá criar um repositório Azure Pipelines para seu aplicativo se ele ainda não existir.

Execute o comando azd pipeline config para configurar o pipeline de implantação e conectá-lo com segurança ao Azure. Inclua a opção --provider azdo para usar Azure Pipelines em vez da configuração padrão do GitHub Actions.
```
azd pipeline config --provider azdo
```
Selecione a assinatura para a qual provisionar e implantar os recursos do aplicativo.
Selecione o local Azure para usar os recursos.
Cole o Token de Acesso Pessoal criado anteriormente.
Insira o nome da Organização Azure DevOps que você criou ou selecionou.
Quando solicitado a criar um novo repositório no diretório atual, insira y e pressione Enter.
Quando solicitado a configurar o git remoto, selecione Criar um novo Projeto de DevOps Azure.
Insira um nome exclusivo de sua escolha para o novo repositório, como aspireazd. azd cria um novo repositório no Azure Repos e o configura com os segredos necessários para autenticar-se no Azure.
Insira y continuar quando azd solicitar que você confirme e envie por push suas alterações locais para iniciar o pipeline configurado.

Explorar o pipeline e o aplicativo implantado

Navegue até o seu novo pipeline de Azure usando o link de status gerado por azd.
Selecione a execução do pipeline concluída para exibir o resumo.
Selecione o link de trabalho na parte inferior da exibição para navegar até os detalhes do trabalho.
A página de detalhes do trabalho mostra o status de todos os estágios individuais. Selecione Provisionamento de Infraestrutura para exibir os logs dessa etapa, que detalham todas as etapas de provisionamento concluídas por azd. Na parte inferior dos logs, anote a mensagem de status final e vincule-se ao grupo de recursos Azure provisionado.
Selecione o link na parte inferior dos registros de provisionamento para navegar até o novo grupo de recursos Azure.

Nota

Você também pode navegar diretamente para o novo grupo de recursos pesquisando-o no Portal do Azure. O nome do grupo de recursos será o nome do ambiente que você forneceu para azd prefixado com rg-.
Selecione o aplicativo de contêiner webfrontend , que hospeda a parte voltada para o público do seu site.
Na página de detalhes do webfrontend, selecione o link URL do Aplicativo para abrir seu site no navegador.

Importante

Se você encontrar um erro 403 Forbidden ao exibir seu site no navegador, verifique se as configurações de entrada estão configuradas corretamente. Na página do aplicativo do webfrontend no Portal , navegue até Ingress na navegação à esquerda. Verifique se Tráfego de entrada está definido como Aceitando tráfego de qualquer lugar e salve suas alterações.

Parabéns! Você implantou com êxito um projeto de .NET Aspire usando os pipelines Azure Developer CLI e Azure.

Limpar recursos

Execute o seguinte comando Azure CLI para excluir o grupo de recursos quando você não precisar mais dos recursos de Azure que você criou. Excluir o grupo de recursos também exclui os recursos contidos nele.

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

Para obter mais informações, consulte Limpar recursos no Azure.

Compartilhar via