Azure开发人员 CLI （azd） 模板是一个标准存储库，其中包含配置和基础结构资产，可用于azd预配和部署项目。 无论是生成新模板还是从现有模板开始，你仍负责在项目发展过程中查看和维护其文件。
本文介绍如何检查和编辑主模板文件。 有关完整结构的概念说明，请参阅Azure开发人员 CLI 模板。
本文使用 hello-azd 模板作为标准化示例，以便查看每个文件在实际项目中执行的操作。 相同的概念适用于为自己的应用生成的模板。 若要继续操作，请初始化空目录中的模板：
azd init --template hello-azd
该hello-azd模板将容器化 C# 应用部署到Azure 容器应用，并通过Bicep预配支持Azure资源。 它采用如下所示的文件夹结构，其中每个主要资源都对应本文中的一个部分：
.
├── azure.yaml # Project configuration (Explore azure.yaml)
├── infra/ # Infrastructure as code (Infrastructure files)
│ ├── main.bicep # Deployment entry point
│ ├── main.parameters.json # Parameter values that azd supplies
│ ├── abbreviations.json # Resource name abbreviations
│ ├── app/ # Application-specific modules
│ └── core/ # Reusable resource modules
├── src/ # Application source code (Source code)
│ └── Dockerfile # Container image build for the app
├── .azure/ # Environment configuration
└── README.md
具体结构因项目而异，azure.yaml 标识 azd 使用的路径。 以下部分介绍如何编辑每个资产。
在进行重大更改之前，请提交或保存模板的已知良好版本。 查看嵌入凭据、不必要的资源、过多的权限、网络公开、服务层和环境特定值的所有更改。
探索 azure.yaml
该文件 azure.yaml 定义项目，并说明 azd 如何预配基础结构、打包应用程序代码和部署每个服务。 它可以定义服务、基础结构设置、挂钩、工作流和其他项目行为。
该 hello-azd 模板定义了一个名为 aca 的服务：
name: azd-starter
metadata:
template: hello-azd-dotnet
services:
aca:
project: ./src
language: csharp
host: containerapp
docker:
path: ./Dockerfile
remoteBuild: true
每个属性都 azd 说明如何处理服务：
-
aca是服务名称。azd使用它将服务与托管它的Azure资源匹配。 有关详细信息，请参阅 配置服务发现。 -
project: ./src指向打包和部署的应用程序源代码azd。 -
language: csharp标识应用程序语言。 -
host: containerapp告知azd将服务部署到Azure 容器应用。 -
docker从Dockerfilesrc目录中生成容器映像。 -
remoteBuild指示azd使用 Azure 容器注册表 （ACR） 生成容器映像。
添加服务定义
在azd下，为services应部署的每个其他应用程序添加一个条目。 服务定义指定其源目录、语言和Azure托管目标。 例如，若要描述新的 API 项目，请执行以下操作：
services:
api:
project: ./src/api
language: csharp
host: appservice
移动应用程序代码时，更新相应的 project 路径。 更改托管体系结构时，请更新服务定义和预配主机的基础结构。
有关所有可用属性和支持的值，请参阅 azure.yaml 架构。
源代码
应用程序源是可选的。 具有可部署应用程序的模板通常组织目录中的 src 源代码，但不需要使用特定的文件夹名称或布局。
azure.yaml 中每个服务的 project 属性会告诉 azd 其源代码所在的位置。
在 aca 中，hello-azd 服务设置了 project: ./src，因此 azd 会将 src 目录中的 C# 应用打包，并将其部署到 Azure 容器应用。 由于该服务还设置了 docker 配置，azd 会在部署前根据 src 目录中的 Dockerfile 构建容器镜像。
azd 在受支持的 Azure 主机上支持 Node.js、Python、.NET、Java 和 Go。 模板还可以部署容器。 有关当前语言、框架和主机组合，请参阅 支持的语言和环境。
像在任何应用程序存储库中一样编辑源代码。 如果添加服务或移动其源目录，请更新其 azure.yaml 服务定义。 如果应用程序需要新的Azure资源，请更新基础结构，并通过配置将所需的终结点或资源名称传递给应用程序。
更改服务源目录
例如，如果将 hello-azd 应用从 project 移动到 aca，请更新 src 服务的 src/app 值：
services:
aca:
project: ./src/app
language: csharp
host: containerapp
docker:
path: ./Dockerfile
remoteBuild: true
基础设施文件
该infra目录包含定义模板Azure资源的Bicep或 Terraform 文件。 在 hello-azd 中，infra 目录使用 Bicep，并包含以下关键资源：
-
main.bicep是azd用于预配资源的标准部署入口点。 -
main.parameters.json为main.bicep提供参数值。 -
app包含特定于应用程序的模块。 -
core包含常见资源的可重用模块，例如存储和托管。
main.bicep 在 azd up 期间如何运行
当你运行 azd up 时，预配阶段会部署 infra/main.bicep。 在 hello-azd 中，main.bicep 以订阅范围为目标，创建资源组，然后调用模块来预配应用所需的资源：
targetScope = 'subscription'
// Create a storage account
module storage './core/storage/storage-account.bicep' = {
name: 'storage'
scope: rg
params: {
name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
location: location
tags: tags
allowSharedKeyAccess: false
containers: [ { name: 'attachments' } ]
tables: [ { name: 'tickets' } ]
}
}
// Container app for the 'aca' service
module web 'app/app.bicep' = {
name: serviceName
scope: rg
params: {
// ...
serviceName: serviceName
}
}
该文件main.bicep预配用户分配的托管标识、Azure 存储帐户、Azure 容器应用环境和注册表，以及承载aca服务的容器应用。 它还分配了允许托管标识访问存储的角色。 模块将每个资源保留在其自己的文件中，因此 main.bicep 保持可读性。
向 main.bicep 添加资源
对于简单资源或一次性资源，直接将资源声明添加到 infra/main.bicep 中。 在以下情况下，请将资源拆分到单独的 Bicep 模块中：需要重用这些资源时、某个资源需要多个相关资源配合时，或者希望保持 main.bicep 的可读性时。 像 hello-azd 一样，许多模板将可复用模块归类到 infra/core 下。
对于常见的Azure资源，首选Azure已验证模块而不是从头开始创作模块。 已验证的模块Microsoft维护，遵循安全性和可靠性最佳做法，并减少在模板中维护的基础结构代码量。
有关向 hello-azd 添加新资源的完整演练，请参阅 扩展模板。
main.parameters.json 文件将由 azd 维护的值映射到 Bicep 参数中。 该 hello-azd 模板使用以下参数：
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"environmentName": { "value": "${AZURE_ENV_NAME}" },
"location": { "value": "${AZURE_LOCATION}" },
"principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
"principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
}
}
每个条目都将一个 Bicep 参数绑定到由 azd 在环境中维护的值，例如环境名称、位置以及执行部署的主体。 对于因环境或部署而异的值，请使用 main.parameters.json，例如环境名称、位置或由 azd 生成的资源名称。 将那些在不同环境之间不会变化的稳定值保留为参数默认值或 main.bicep 中的字面量。 这种方法可使同一个 Bicep 在不同环境中复用，而无需针对每次部署进行编辑。
添加或编辑基础结构时：
- 使资源配置环境保持独立。 使用参数和环境
azd值，而不是嵌入订阅 ID、资源名称、位置或凭据。 - 对敏感值使用安全输出，不要将机密以纯文本形式作为部署输出暴露出来。
- 对托管标识应用最小权限角色分配。
- 使服务定义
azure.yaml与目标资源保持一致。 - 查看服务层级、缩放限制、冗余和保留设置对成本的影响。
有关 Bicep 语言和模块相关指导，请参阅 Bicep 文档。 有关基于 Terraform 的模板，请参阅将 Terraform 与Azure开发人员 CLI 配合使用。
配置服务发现
默认情况下，azd通过查找其azd-service-name标记与服务名称azure.yaml匹配的资源来发现服务的Azure资源。 如果重命名了服务，请更新相应的资源标签，或在 azure.yaml 中显式配置资源名称。
例如，在 hello-azd 中，aca 服务名称与容器应用资源上的 azd-service-name 标记匹配。
azure.yaml 服务定义设置名称如下：
services:
aca:
project: ./src
language: csharp
host: containerapp
中的 infra/app/app.bicep 容器应用模块应用匹配标记：
tags: union(tags, { 'azd-service-name': serviceName })
配置非标准基础结构路径
azure.yaml 的 infra 部分标识出基础设施提供程序和入口点。 使用默认Bicep布局时，这些值是可选的，但声明这些值可以使非标准布局更易于理解：
infra:
provider: bicep
path: infra
module: main
环境配置
该 .azure 目录包含本地环境状态和创建值 azd ，例如所选订阅、位置、资源名称和部署输出。 将此目录视为本地状态，而不是可重用的模板资产。 不要提交包含机密或特定于环境的值的环境文件。
添加基础设施输出
运行azd provision以部署Bicep时，它会将基础结构入口点的输出捕获为azd环境值。 为应用程序服务或挂钩所需的资源终结点、资源名称和托管标识客户端 ID 添加输出。 例如，hello-azd 输出来自 main.bicep 的容器注册表和托管标识详细信息：
output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name
当可以通过托管标识或 密钥保管库 引用提供访问权限时，不要输出机密信息。 预配后，通过运行 azd env get-values检查捕获的值。
有关详细信息，请参阅 “管理环境变量”。
测试您的更改
运行 azd up 以预配基础结构并部署任何应用程序服务：
azd up
如果打算共享模板，请在干净目录中初始化模板，并使用新环境部署它。 此测试有助于识别不属于模板的本地文件、缓存值或特定于环境的假设。
相关内容
请求帮助
有关如何提交 bug、请求帮助或为 Azure 开发人员 CLI 提出新功能的信息，请访问 troubleshooting and support 页。