Azure 開發者 CLI （azd） 範本是一個標準儲存庫，包含組態與基礎架構資產，能用於azd專案的配置與部署。 無論你是建立新範本還是從現有範本開始，你都必須負責隨著專案演進審查與維護其檔案。
本文說明如何檢查與編輯主要範本檔案。 完整結構的概念說明，請參見 Azure Developer 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從目錄中的src建立Dockerfile容器映像。 -
remoteBuild指示azd使用 Azure Container Registry（ACR）來建置容器映像。
新增服務定義
在 azd 下，針對 services 應部署的每個其他應用程式新增一個項目。 服務定義會指定其來源目錄、語言及 Azure 主機目標。 例如，描述一個新的 API 專案：
services:
api:
project: ./src/api
language: csharp
host: appservice
當你移動應用程式碼時，更新對應 project 的路徑。 當你更改主機架構時，請同時更新服務定義和提供主機的基礎設施。
關於所有可用的屬性與支援值，請參閱結構。azure.yaml
原始程式碼
應用程式來源為可選。 帶有可部署應用程式的範本通常會在目錄下 src 組織原始碼，但你不需要使用特定的資料夾名稱或排版。 在 azure.yaml 中，每個服務的 project 屬性會告訴 azd 其原始程式碼位於何處。
在 hello-azd中，aca服務設定 project: ./src，因此azd將 C# 應用程式打包在目錄中src，並部署到 Azure 容器應用程式。 因為服務也會設定docker設定，會在azd部署前從Dockerfilesrc目錄中建立容器映像。
azd 在受支援的 Azure 主機上支援 Node.js、Python、.NET、Java 和 Go。 範本也可以部署容器。 關於目前的語言、框架與主機組合，請參見 支援語言與環境。
編輯原始碼就像在任何應用程式倉庫裡一樣。 如果你新增服務或移動其來源目錄，請更新其 azure.yaml 服務定義。 如果應用程式需要新的 Azure 資源，更新基礎架構，並透過設定將所需的端點或資源名稱傳給應用程式。
變更服務來源目錄
例如，如果你將應用程式src從 移動hello-azd到 src/app，則更新project服務的aca值：
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，以用於簡單或單次使用的資源。 當你重複使用資源、需要多個相關資源，或想保持main.bicep可讀性時，將資源分拆到獨立的 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 的範本，請參見 Use Terraform with Azure Developer 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 })
配置非標準基礎設施路徑
infra該azure.yaml區塊識別基礎設施提供者及入口點。 這些數值在使用預設 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
如果你打算分享範本，請先在乾淨的目錄中初始化，然後用新環境部署。 此測試有助於辨識範本中不包含的本地檔案、快取值或環境特定的假設。
相關內容
請求幫助
如需了解如何提出錯誤、請求協助或建議Azure開發者 CLI 新功能，請造訪 troubleshooting and support 頁面。