Uw Azure Developer CLI-werkstromen aanpassen met behulp van opdracht- en gebeurtenishook

Hooks zijn azd uitbreidingspunten die automatisch aangepaste scripts uitvoeren vóór en na opdrachten en gebeurtenissen van azd de levenscyclus van de service. Hooks volgen een naamconventie met voor- en postvoorvoegsels op de overeenkomende azd opdracht- of servicegebeurtenisnaam.

U kunt bijvoorbeeld een aangepast script uitvoeren in de volgende scenario's:

• Gebruik de prerestore hook om afhankelijkheidsbeheer aan te passen.
• Gebruik de vooraf geïmplementeerde hook om te controleren of externe afhankelijkheden of aangepaste configuraties aanwezig zijn voordat u uw app implementeert.
• Gebruik de postup aan het einde van een werkstroom of pijplijn om aangepaste opschoning of logboekregistratie uit te voeren.

Beschikbare haken

De volgende azd opdrachthook is beschikbaar:

• prerestore en postrestore: Uitvoeren voor en na pakketafhankelijkheden worden hersteld.
• preprovision en postprovision: Uitvoeren voor en nadat Azure-resources zijn gemaakt.
• prepackage en postpackage: Uitvoeren voor en nadat de toepassing is verpakt.
• predeploy en postdeploy: Voer vóór en nadat de toepassingscode is geïmplementeerd in Azure uit.
• prepublish en postpublish: Uitvoeren voor en nadat de toepassing is gepubliceerd.
• preup en postup: voor en na de gecombineerde implementatiepijplijn uitvoeren. Up is een verkorte opdracht waarmee restore, provisionen deploy opeenvolgend worden uitgevoerd.
• predown en postdown: voor en nadat de resources zijn verwijderd.

De volgende gebeurtenishook voor de levenscyclus van de service zijn beschikbaar:

• prerestore en postrestore: voor en na de servicepakketten en afhankelijkheden worden hersteld.
• prebuild en postbuild: Voer vóór en na de broncode of container van de service uit.
• prepackage en postpackage: Uitvoeren voor en nadat de app is verpakt voor implementatie.
• predeploy en postdeploy: Voer vóór en nadat de servicecode is geïmplementeerd in Azure uit.
• prepublish en postpublish: Uitvoeren voor en nadat de service is gepubliceerd.

Hook-configuratie

Hooks worden geregistreerd in uw azure.yaml bestand in de hoofdmap of in een specifieke serviceconfiguratie. Alle typen hooks ondersteunen de volgende configuratieopties:

• shell: sh | pwsh (optioneel). Wanneer u dit weglaat, azd selecteert u een standaardinstelling op basis van het besturingssysteem: pwsh op Windows en sh in Linux en macOS. azd hiermee wordt een waarschuwing afgedrukt wanneer de standaardwaarde wordt gebruikt en wordt de instelling shell expliciet aanbevolen voor platformoverschrijdende betrouwbaarheid. PowerShell 7 is vereist voor pwsh.
• run: Definieer een inlinescript of een pad naar een bestand. Voor bestandspaden azd wordt de shell afgeleid van de bestandsextensie (bijvoorbeeld .sh of .ps1).
• continueOnError: Wanneer de set wordt uitgevoerd, zelfs nadat er een scriptfout is opgetreden tijdens een opdrachthook (standaard onwaar).
• interactive: als dit is ingesteld, wordt het actieve script gekoppeld aan de console stdin, stdout & stderr (standaard onwaar).
• windows: hiermee geeft u op dat de geneste configuraties alleen van toepassing zijn op het Windows-besturingssysteem. Als deze configuratieoptie is uitgesloten, wordt de hook uitgevoerd op alle platforms.
• posix: hiermee geeft u op dat de geneste configuraties alleen van toepassing zijn op OP POSIX gebaseerde besturingssystemen (Linux & MaxOS). Als deze configuratieoptie is uitgesloten, wordt de hook uitgevoerd op alle platforms.

Hook-voorbeelden

In de volgende voorbeelden ziet u verschillende soorten hookregistraties en configuraties.

Registratie van hoofdopdracht

Hooks kunnen worden geconfigureerd om te worden uitgevoerd voor specifieke azd opdrachten in de hoofdmap van uw azure.yaml-bestand.

De projectmap (waar het bestand azure.yaml zich bevindt) is de standaard huidige werkmap (cwd) voor opdrachthook.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: # Example of an inline script with an explicit shell
    shell: sh
    run: echo 'Hello'
  preprovision: # Example of external script (Relative path from project root)
    run: ./hooks/preprovision.sh
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Serviceregistratie

Hooks kunnen ook worden geconfigureerd om alleen te worden uitgevoerd voor specifieke services die zijn gedefinieerd in uw .yaml-bestand.

De servicemap (hetzelfde pad dat is gedefinieerd in de eigenschap project van de serviceconfiguratie in het azure.yaml-bestand) is de standaard-cwd voor servicehook.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice
    hooks:
      prerestore: # Example of an inline script with an explicit shell
        shell: sh
        run: echo 'Restoring API service...'
      prepackage: # Example of external script (Relative path from service path)
        run: ./hooks/prepackage.sh

Specifieke haken voor het besturingssysteem

Optioneel kunnen hooks ook worden geconfigureerd voor uitvoering in Windows of Posix (Linux & MaxOS). Als de Windows- of Posix-configuraties standaard worden uitgesloten, wordt de hook op alle platforms uitgevoerd.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: 
    posix: # Only runs on Posix environments
      shell: sh
      run: echo 'Hello'
   windows: # Only runs on Windows environments
     shell: pwsh
     run: Write-Host "Hello"
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Platformoverschrijdende inlinescripts zonder expliciete shell

Wanneer u een inlinehook weglaatshell, azd selecteert u een standaardshell op basis van het besturingssysteem: pwsh op Windows en in Linux en sh macOS. Deze optie is handig voor eenvoudige opdrachten die in beide shells werken, zoals het afdrukken van een statusbericht of het aanroepen van een CLI die al op het pad van de gebruiker staat.

name: example-project
hooks:
  prerestore: # No shell specified; azd uses pwsh on Windows and sh on Linux/macOS
    run: echo 'Restoring dependencies...'

azd drukt een waarschuwing af wanneer deze terugvalt op de standaardshell. Stel voor inlinescripts die afhankelijk zijn van shell-specifieke syntaxis shell expliciet in of gebruik de windows configuraties posix om beide varianten te bieden.

Meerdere hooks per gebeurtenis

U kunt meerdere hooks per gebeurtenis configureren voor verschillende bereiken, zoals het basisregistratieniveau of voor een specifieke service:

name: example-project
services:
    api:
        project: src/api
        host: containerapp
        language: ts
        hooks:
            postprovision:
                - shell: sh
                  run: scripts/postprovision1.sh
                - shell: sh
                  run: scripts/postprovision2.sh
hooks:
    postprovision:
        - shell: sh
          run: scripts/postprovision1.sh
        - shell: sh
          run: scripts/postprovision2.sh

Haakjes onafhankelijk uitvoeren

Met de azd hooks run opdracht kunt u hooks onafhankelijk van hun normale trigger-gebeurtenissen uitvoeren. Dit is handig voor het testen en foutopsporing van hooks zonder de hele werkstroom te doorlopen.

azd hooks run <hook-name>

Vervang door <hook-name> de naam van de haak die u wilt uitvoeren (bijvoorbeeld preprovision, postdeploy).

Geavanceerde opties

# Run a specific service hook
azd hooks run postdeploy --service api

# Force hooks to run for a specific platform
azd hooks run preprovision --platform windows

# Run hooks in a specific environment
azd hooks run postup -e staging

# Run hooks with all options combined
azd hooks run predeploy --service frontend --platform posix -e production --interactive

Interactieve modus configureren

Hooks worden standaard uitgevoerd in de interactieve modus. Met de interactieve hooks-modus kunt u hookscripts uitvoeren met directe consoleinteractie, zodat u in realtime eenvoudiger fouten kunt opsporen, bewaken en ermee kunt werken. U kunt de eigenschap expliciet instellen in uw interactive hookconfiguratie als u de interactieve modus voor een specifieke hook wilt uitschakelen:

hooks:
  postprovision:
    shell: sh
    run: ./scripts/setup-database.sh
    interactive: false # Default is true

Voor servicespecifieke hooks:

services:
  api:
    project: ./src/api
    language: js
    host: appservice
    hooks:
      postdeploy:
        shell: sh
        run: ./scripts/post-deploy-verification.sh
        interactive: false  # Override the default interactive mode

Omgevingsvariabelen gebruiken met hooks

Hooks kunnen omgevingsvariabelen ophalen en instellen in het .env-bestand met behulp van de opdrachten azd env get-values en azd set <key> <value>. Hooks kunnen ook omgevingsvariabelen ophalen uit uw lokale omgeving met behulp van de ${YOUR_ENVIRONMENT VARIABLE} syntaxis. azd stelt automatisch bepaalde omgevingsvariabelen in het .env-bestand in wanneer opdrachten worden uitgevoerd, zoals AZURE_ENV_NAME en AZURE_LOCATION. Uitvoerparameters uit het main.bicep-bestand worden ook ingesteld in het .env-bestand. De pagina omgevingsvariabelen beheren bevat meer informatie over werkstromen voor omgevingsvariabelen.

Hooks kunnen omgevingsvariabelen inline of via scripts waarnaar wordt verwezen, ophalen en instellen, zoals wordt weergegeven in het volgende voorbeeld:

name: azure-search-openai-demo
metadata:
  template: azure-search-openai-demo@0.0.2-beta
services:
  backend:
    project: ./app/backend
    language: py
    host: appservice
hooks:
  postprovision:
    windows: # Run referenced script that uses environment variables (script shown below)
      shell: pwsh
      run: ./scripts/prepdocs.ps1
      interactive: true
      continueOnError: false
    posix:
      shell: sh
      run: ./scripts/prepdocs.sh
      interactive: true
      continueOnError: false
  postdeploy: # Pull environment variable inline from local device and set in .env file
      shell: sh
      run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}

Het script waarnaar wordt verwezen: prepdocs.sh:

echo "Loading azd .env file from current environment"

# Use the `get-values` azd command to retrieve environment variables from the `.env` file
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values) 
EOF

echo 'Creating python virtual environment "scripts/.venv"'
python3 -m venv scripts/.venv

echo 'Installing dependencies from "requirements.txt" into virtual environment'
./scripts/.venv/bin/python -m pip install -r scripts/requirements.txt

echo 'Running "prepdocs.py"'
./scripts/.venv/bin/python ./scripts/prepdocs.py './data/*' 
    --storageaccount "$AZURE_STORAGE_ACCOUNT"
    --container "$AZURE_STORAGE_CONTAINER"
    --searchservice "$AZURE_SEARCH_SERVICE"
    --openaiservice "$AZURE_OPENAI_SERVICE"
    --openaideployment "$AZURE_OPENAI_EMB_DEPLOYMENT"
    --index "$AZURE_SEARCH_INDEX"
    --formrecognizerservice "$AZURE_FORMRECOGNIZER_SERVICE"
    --tenantid "$AZURE_TENANT_ID" -v

Hulp vragen

Ga naar de pagina voor probleemoplossing en ondersteuning voor informatie over het indienen van een bug, hulp vragen of een nieuwe functie voorstellen voor de Azure Developer CLI.