Configuratie bouwen voor Azure Static Web Apps

De buildconfiguratie van Azure Static Web Apps maakt gebruik van GitHub Actions of Azure Pipelines. Elke site heeft een YAML-configuratiebestand dat bepaalt hoe een site wordt gebouwd en geïmplementeerd. In dit artikel worden de structuur en opties van het bestand uitgelegd.

De volgende tabel bevat de beschikbare configuratie-instellingen.

Eigenschappen	Beschrijving	Vereist
app_location	Deze map bevat de broncode voor uw front-endtoepassing. De waarde is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub en de huidige werkmap in Azure DevOps. Wanneer deze waarde wordt gebruikt skip_app_build: true, is deze waarde de uitvoerlocatie van de build van de app.	Ja
api_location	Deze map met de broncode voor uw API-toepassing. De waarde is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub en de huidige werkmap in Azure DevOps. Wanneer deze waarde wordt gebruikt skip_api_build: true, is deze waarde de build-uitvoerlocatie van de API.	Nee
output_location	Als uw web-app een buildstap uitvoert, is de uitvoerlocatie de map waarin de openbare bestanden worden gegenereerd. Voor de meeste projecten is het output_location relatief ten opzichte van de app_location. Voor .NET-projecten is de locatie echter relatief ten opzichte van de uitvoermap.	Nee
app_build_command	Voor Node.js toepassingen kunt u een aangepaste opdracht definiëren om de statische inhoudstoepassing te bouwen. Als u bijvoorbeeld een productie-build wilt configureren voor een Angular-toepassing, maakt u een NPM-script dat build-prod moet worden uitgevoerd ng build --prod en voert u deze npm run build-prod in als de aangepaste opdracht. Als u niets opgeeft, probeert de werkstroom de npm run build of npm run build:azure opdrachten uit te voeren.	Nee
api_build_command	Voor Node.js toepassingen kunt u een aangepaste opdracht definiëren om de Azure Functions API-toepassing te bouwen.	Nee
skip_app_build	Stel de waarde in om true het bouwen van de front-end-app over te slaan.	Nee
skip_api_build	Stel de waarde in om true het bouwen van de API-functies over te slaan.	Nee
cwd (Alleen Azure Pipelines)	Absoluut pad naar de werkmap. Standaard ingesteld op $(System.DefaultWorkingDirectory).	Nee
build_timeout_in_minutes	Stel deze waarde in om de time-out van de build aan te passen. Standaard ingesteld op 15.	Nee

Met deze instellingen kunt u GitHub Actions of Azure Pipelines instellen voor het uitvoeren van continue integratie/continue levering (CI/CD) voor uw statische web-app.

Bestandsnaam en locatie

GitHub Actions

De GitHub-actie genereert het configuratiebestand en wordt opgeslagen in de map .github/workflows, met de naam met de volgende indeling: azure-static-web-apps-<RANDOM_NAME>.yml

Azure Pipelines

Standaard wordt het configuratiebestand opgeslagen in de hoofdmap van uw opslagplaats met de naam azure-pipelines.yml.

Configuratie compileren

In de volgende voorbeeldconfiguratie wordt de opslagplaats gecontroleerd op wijzigingen. Wanneer doorvoeringen naar de main vertakking worden gepusht, wordt de toepassing gebouwd vanuit de app_location map en worden bestanden in het output_location openbare web aangeboden. Daarnaast is de toepassing in de API-map beschikbaar onder het pad van api de site.

GitHub Actions

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations ######
          app_location: "src" # App source code path relative to repository root
          api_location: "api" # Api source code path relative to repository root - optional
          output_location: "public" # Built app content directory, relative to app_location - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

In deze configuratie:

• De main vertakking wordt gecontroleerd op doorvoeringen.
• Een GitHub Actions-werkstroom wordt geactiveerd wanneer een pull-aanvraag in de main vertakking wordt geopend, gesynchroniseerd, opnieuw geopend of gesloten.
• De build_and_deploy_job opdracht wordt uitgevoerd wanneer u doorvoeringen pusht of een pull-aanvraag opent voor de vertakking die in de on eigenschap wordt vermeld.
• De app_location verwijst naar de src map die de bronbestanden voor de web-app bevat. Als u deze waarde wilt instellen op de hoofdmap van de opslagplaats, gebruikt u /.
• De api_location verwijst naar de api map die de Azure Functions-toepassing voor de API-eindpunten van de site bevat. Als u deze waarde wilt instellen op de hoofdmap van de opslagplaats, gebruikt u /.
• De output_location map verwijst naar de public map die de definitieve versie van de bronbestanden van de app bevat. Het is relatief ten opzichte van app_location. Voor .NET-projecten is de locatie relatief ten opzichte van de publicatie-uitvoermap.

Wijzig de waarden voor repo_token, actionen azure_static_web_apps_api_token zoals ze voor u zijn ingesteld door Azure Static Web Apps niet.

Met de taak Pull-aanvraag sluiten wordt automatisch de pull-aanvraag gesloten die de build en implementatie heeft geactiveerd. Deze optionele taak is niet vereist om het proces te laten werken.

Wanneer een pull-aanvraag wordt geopend, bouwt en implementeert de GitHub Action van Azure Static Web Apps de app in een faseringsomgeving. Daarna controleert de taak Pull-aanvraag sluiten of de pull-aanvraag nog steeds is geopend en wordt deze gesloten met een voltooiingsbericht.

Deze taak helpt uw werkstroom voor pull-aanvragen georganiseerd te houden en verouderde pull-aanvragen te voorkomen. Door de runtime de pull-aanvraag automatisch te sluiten, blijft uw opslagplaats up-to-date en wordt uw team op de hoogte gesteld van de status.

De pull-aanvraagtaak sluiten maakt deel uit van de GitHub Actions-werkstroom van Azure Static Web Apps en sluit de pull-aanvraag nadat deze is samengevoegd. Met Azure/static-web-apps-deploy de actie wordt de app geïmplementeerd in Azure Static Web Apps, waarvoor verificatie azure_static_web_apps_api_token is vereist.

Azure Pipelines

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

In deze configuratie:

• De main vertakking wordt gecontroleerd op doorvoeringen.
• De app_location verwijst naar de src map die de bronbestanden voor de web-app bevat. Deze waarde is relatief ten opzichte van de werkmap (cwd). Als u deze wilt instellen op de werkmap, gebruikt u /.
• De api_location verwijst naar de api map die de Azure Functions-toepassing voor de API-eindpunten van de site bevat. Deze waarde is relatief ten opzichte van de werkmap (cwd). Als u deze wilt instellen op de werkmap, gebruikt u /.
• De output_location map verwijst naar de public map die de definitieve versie van de bronbestanden van de app bevat. Deze waarde is relatief ten app_locationopzichte van . Voor .NET-projecten is de locatie relatief ten opzichte van de uitvoermap.
• Het cwd is een absoluut pad dat verwijst naar de werkmap. Deze wordt standaard ingesteld op $(System.DefaultWorkingDirectory).
• De $(deployment_token) variabele verwijst naar het gegenereerde Azure DevOps-implementatietoken.

Notitie

app_location en api_location moet relatief zijn ten opzichte van de werkmap (cwd) en moeten submappen zijn onder cwd.

Aangepaste buildopdrachten

Voor Node.js toepassingen kunt u gedetailleerde controle over welke opdrachten worden uitgevoerd tijdens het app- of API-buildproces. In het volgende voorbeeld ziet u hoe u build definieert met waarden voor app_build_command en api_build_command.

Notitie

Op dit moment kunt u alleen builds definiëren app_build_command en api_build_command voor Node.js. Als u de Node.js versie wilt opgeven, gebruikt u het engines veld in het package.json bestand.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: '/'
  api_location: 'api'
  output_location: 'dist'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

Front-end-app overslaan

Als u volledige controle over de build voor uw front-end-app nodig hebt, kunt u de automatische build omzeilen en de app implementeren die in een vorige stap is gebouwd.

Ga als volgende te werk om het bouwen van de front-end-app over te slaan:

• Stel app_location in op de locatie waar de bestanden die u wilt implementeren.
• Stel skip_app_build in op true.
• Ingesteld output_location op een lege tekenreeks ('').

Notitie

Zorg ervoor dat het bestand ook in de uitvoermap is staticwebapp.config.json gekopieerd.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

Azure Pipelines

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Het bouwen van de API overslaan

Als u het bouwen van de API wilt overslaan, kunt u de automatische build omzeilen en de API implementeren die in een vorige stap is gebouwd.

Stappen voor het overslaan van het bouwen van de API:

• Stel apiRuntime in het staticwebapp.config.json bestand de juiste runtime en versie in. Raadpleeg Azure Static Web Apps configureren voor de lijst met ondersteunde runtimes en versies.

  {
    "platform": {
      "apiRuntime": "node:16"
    }
  }
  

• Stel skip_api_build in op true.
• Stel api_location in op de map met de ingebouwde API-app die moet worden geïmplementeerd. Dit pad is relatief ten opzichte van de hoofdmap van de opslagplaats in GitHub Actions en cwd in Azure Pipelines.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: "src" # App source code path relative to repository root
  api_location: "api" # Api source code path relative to repository root - optional
  output_location: "public" # Built app content directory, relative to app_location - optional
  skip_api_build: true

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Time-out van build uitbreiden

De app- en API-builds zijn standaard beperkt tot 15 minuten. U kunt de time-out van de build uitbreiden door de build_timeout_in_minutes eigenschap in te stellen.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

Werkstroom uitvoeren zonder implementatiegeheimen

Soms hebt u uw werkstroom nodig om te blijven verwerken, zelfs wanneer sommige geheimen ontbreken. Stel de SKIP_DEPLOY_ON_MISSING_SECRETS omgevingsvariabele in om uw werkstroom te true configureren om door te gaan zonder gedefinieerde geheimen.

Wanneer deze functie is ingeschakeld, kan de werkstroom doorgaan zonder de inhoud van de site te implementeren.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

Omgevingsvariabelen

U kunt omgevingsvariabelen voor uw build instellen via de sectie van de env configuratie van een taak.

Zie Oryx-configuratie voor meer informatie over de omgevingsvariabelen die worden gebruikt door Oryx.

GitHub Actions

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Ondersteuning voor Monorepo

Een monorepo is een opslagplaats die code voor meer dan één toepassing bevat. De werkstroom houdt standaard alle bestanden in een opslagplaats bij, maar u kunt de configuratie aanpassen aan één app.

Als u een werkstroombestand wilt richten op één app, geeft u paden in de push en pull_request secties op.

GitHub Actions

Wanneer u een monorepo instelt, wordt elke configuratie van een statische app beperkt tot alleen bestanden voor één app. De verschillende werkstroombestanden bevinden zich naast elkaar in de map .github/werkstromen van de opslagplaats.

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

In het volgende voorbeeld ziet u hoe u een paths knooppunt toevoegt aan de secties pull_request van een bestand met de push naam azure-static-web-apps-purple-pond.yml.

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

In dit voorbeeld worden alleen wijzigingen aangebracht in de volgende bestanden, waardoor een nieuwe build wordt geactiveerd:

• Bestanden in de app1-map
• Bestanden in de API1-map
• Wijzigingen in het azure-static-web-apps-purple-pond.yml werkstroombestand van de app

Azure Pipelines

Als u meer dan één toepassing in één opslagplaats wilt ondersteunen, maakt u een afzonderlijk werkstroombestand en koppelt u dit aan verschillende Azure Pipelines.

Volgende stappen

Pull-aanvragen controleren in preproductieomgevingen