通过

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

挂钩是在 azd 命令和服务生命周期事件前后 azd 自动执行自定义脚本的扩展点。 挂钩遵循命名约定，在匹配的命令或服务事件名称上使用前缀和azd前缀。

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

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

可用挂钩

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

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

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

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

挂钩配置

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

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

挂钩示例

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

根命令注册

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

项目目录（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 文件中定义的特定服务运行。

服务目录（与 project 文件中服务配置 azure.yaml 属性中定义的路径相同）是服务挂钩的默认 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 hooks run 命令允许独立于其正常触发器事件执行挂钩。 这对于测试和调试挂钩非常有用，无需完成整个工作流。

azd hooks run <hook-name>

替换为 <hook-name> 要运行的挂钩的名称（例如 preprovision， postdeploy）。

高级选项

# 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

配置交互式模式

挂钩默认以交互模式运行。 交互式挂钩模式允许你通过直接控制台交互运行挂钩脚本，从而更轻松地实时调试、监视和与挂钩进行交互。 如果要禁用特定挂钩的交互模式，可以在挂钩配置中显式设置 interactive 属性：

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

对于特定于服务的挂钩：

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

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

挂钩可以使用 .env 和 azd env get-values 命令在 azd set <key> <value> 文件中获取和设置环境变量。 挂钩还可以使用 ${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 提出新功能的信息，请访问 故障排除和支持 页。