使用命令和事件挂钩自定义 Azure 开发人员 CLI 工作流

项目
01/30/2025

Azure 开发人员 CLI 支持各种扩展点来自定义工作流和部署。挂钩中间件允许你在 azd 命令和服务生命周期事件前后执行自定义脚本。挂钩遵循命名约定，预先，并在匹配的 azd 命令或服务事件名称上发布前缀。

例如，你可能希望在以下方案中运行自定义脚本：

使用 预存储 挂钩自定义依赖项管理。
使用 预部署 挂钩在部署应用之前验证外部依赖项或自定义配置是否已到位。
使用工作流或管道末尾的后挂钩来执行自定义清理或日志记录。

可用挂钩

可以使用以下 azd 命令挂钩：

prerestore 和 postrestore：还原包依赖项之前和之后运行。
preprovision 和 postprovision：在创建 Azure 资源之前和之后运行。
predeploy 和 postdeploy：在应用程序代码部署到 Azure 之前和之后运行。
preup 和 postup：在组合部署管道前后运行。 Up 是运行 restore、provision和按顺序 deploy 的速记命令。
predown 和 postdown：删除资源之前和之后运行。

以下服务生命周期事件挂钩可用：

prerestore 和 postrestore：在还原服务包和依赖项之前和之后运行。
prebuild 和 postbuild：在生成服务源代码或容器之前和之后运行。
prepackage 和 postpackage：在打包应用进行部署之前和之后运行。
predeploy 和 postdeploy：在服务代码部署到 Azure 之前和之后运行。

挂钩配置

可以在根目录或特定服务配置中的 azure.yaml 文件中注册挂钩。所有类型的挂钩都支持以下配置选项：

shell：sh | pwsh
- 注释：pwsh需要 PowerShell 7。
run：定义内联脚本或文件的路径。
continueOnError：即使命令挂钩期间发生脚本错误（默认值 false），设置也会继续执行。
interactive：设置时会将正在运行的脚本绑定到控制台 stdin，stdout & stderr（默认值 false）。
windows：指定嵌套配置仅适用于 Windows OS。如果排除此配置选项，则挂钩在所有平台上执行。
posix：指定嵌套配置仅适用于基于 POSIX 的 OS（Linux & MaxOS）。如果排除此配置选项，则挂钩在所有平台上执行。

挂钩示例

以下示例演示不同类型的挂钩注册和配置。

根命令注册

可以将挂钩配置为在 azure.yaml 文件的根目录中针对特定 azd 命令运行。

项目目录（azure.yaml 文件所在的位置）是命令挂钩的默认当前工作目录（cwd）。

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: # Example of an inline script. (shell is required for inline scripts)
    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

服务注册

还可以将挂钩配置为仅针对 .yaml 文件中定义的特定服务运行。

服务目录（与 azure.yaml 文件中服务配置 project 属性中定义的路径相同）是服务挂钩的默认 cwd。

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. (shell is required for inline scripts)
        shell: sh
        run: echo 'Restoring API service...'
      prepackage: # Example of external script (Relative path from service path)
        run: ./hooks/prepackage.sh

特定于 OS 的挂钩

（可选）还可以将挂钩配置为在 Windows 或 Posix 上运行（Linux & MaxOS）。默认情况下，如果排除 Windows 或 Posix 配置，则挂钩在所有平台上执行。

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

每个事件有多个挂钩

可以跨不同的范围（例如根注册级别或特定服务）为每个事件配置多个挂钩：

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

将环境变量与挂钩配合使用

挂钩可以使用 azd env get-values 和 azd set <key> <value> 命令在 .env 文件中获取和设置环境变量。挂钩还可以使用 ${YOUR_ENVIRONMENT VARIABLE} 语法从本地环境中检索环境变量。 azd 在运行命令时自动在 .env 文件中设置某些环境变量，例如 AZURE_ENV_NAME 和 AZURE_LOCATION。 main.bicep 文件中的输出参数也在 .env 文件中设置。管理环境变量页包含有关环境变量工作流的详细信息。

挂钩可以内联或通过引用的脚本来获取和设置环境变量，如以下示例所示：

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}

引用的：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

请求帮助

有关如何提交 bug、请求帮助或为 Azure 开发人员 CLI 提出新功能的信息，请访问故障排除和支持页。

通过