Bicep CLI 命令

此文章描述您可以在 Bicep CLI 中使用的命令。 您可以使用 Azure CLI 或直接叫用 Bicep CLI 命令來執行這些命令。 兩種方式各需要不同的安裝程序。 如需安裝的詳細資訊，請參閱 Azure CLI 和 Azure PowerShell。

本指南說明如何在 Azure CLI 中執行命令。 在 Azure CLI 中執行命令時，請使用 az加以啟動。 如果您未使用 Azure CLI，請在每個命令開始時執行 命令，而不 az 用。 例如 az bicep build 會成為 bicep build，而 az bicep version 會成為 bicep --version。

build

命令 build 會將 Bicep 檔案轉換成 JSON Azure Resource Manager 範本 （ARM 範本）。 一般來說，您不需要執行此命令，因為其會在您部署 Bicep 檔案時自動執行。 當您想要查看從 Bicep 檔案建立的 JSON ARM 範本時，請手動執行它。

使用下列任何 Bicep 功能會自動啟用語言 2.0 版程式代碼產生：

• 用戶定義型別
• 用戶定義函式
• 編譯時間匯入
• 實驗性功能

下列範例會將名為 main.bicep 的 Bicep 檔案轉換成名為 main.json 的 ARM 範本。 新檔案會建立在與 Bicep 檔案相同的目錄中：

az bicep build --file main.bicep

下一個範例會將main.json儲存至不同的目錄：

az bicep build --file main.bicep --outdir c:\jsontemplates

下一個範例會指定要建立之檔案的名稱和位置：

az bicep build --file main.bicep --outfile c:\jsontemplates\azuredeploy.json

若要將檔案列印到 stdout，請使用：

az bicep build --file main.bicep --stdout

如果您的 Bicep 檔案包含參考外部登入的模組， build 命令會自動呼叫 restore。 命令 restore 會從登錄取得檔案，並將它儲存在本機快取中。

注意

命令 restore 不會重新整理快取。 如需詳細資訊，請參閱還原。

如果不要自動呼叫 restore，請使用 --no-restore 參數：

az bicep build --no-restore <bicep-file>

如果其中一個外部模組尚未快取，則具有 --no-restore 參數的建置程序會失敗：

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

當您收到此錯誤時，請執行命令而不--no-restore使用 build 參數，或先執行bicep restore。

若要使用 --no-restore 參數，您必須擁有 Bicep CLI 0.4.X 版或更新版本。

build-params

命令 build-params 會將 .bicepparam 檔案建置至 JSON 參數檔案：

az bicep build-params --file params.bicepparam

此命令會將 params.bicepparam 參數轉換為 params.json JSON 參數檔案。

decompile

命令 decompile 會將 JSON ARM 樣本轉換成 Bicep 檔案：

az bicep decompile --file main.json

此命令會在與 main.json 相同的目錄中建立名為 main.bicep 的檔案。 如果相同的目錄中已存在 main.bicep，請使用 --force 參數覆寫現有的 Bicep 檔案。

如需使用此命令的詳細資訊，請參閱 將 JSON ARM 範本分解為 Bicep。

decompile-params

命令會將 decompile-params JSON 參數檔案分解成 .bicepparam 參數檔案。

az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/main.bicep

此命令會將 azuredeploy.parameters.json 參數檔案分解成 azuredeploy.parameters.bicepparam 檔案。 --bicep-file會指定宣告中所using參考之 Bicep 檔案的路徑（相對於.bicepparam檔案）。

format

命令會 format 格式化 Bicep 檔案。 與 Visual Studio Code 中的 SHIFT+ALT+F 捷徑具有相同功能。

az bicep format --file main.bicep

generate-params

generate-params 命令會從指定的 bicep 檔案建置參數檔案，如果有現有的參數檔案，則會進行更新。

az bicep generate-params --file main.bicep --output-format bicepparam --include-params all

此命令會建立名為 main.bicepparam 的 Bicep 參數檔案。 參數檔案包含 Bicep 檔案中的所有參數，不論是否使用預設值進行設定。

az bicep generate-params --file main.bicep --outfile main.parameters.json

此命令會建立名為 main.parameters.json 的參數檔案。 parameters 檔案只會包含參數，而不需在 Bicep 檔案中設定預設值。

安裝

命令 install 會將 Bicep CLI 新增至本機環境，而且只能透過 Azure CLI 使用。 如需詳細資訊，請參閱安裝 Bicep 工具。

若要安裝最新版本，請使用：

az bicep install

若要安裝特定版本：

az bicep install --version v0.3.255

jsonrpc

jsonrpc此命令可讓您使用 JSON-RPC 介面執行 Bicep CLI，以程式設計方式與結構化輸出互動，並避免編譯多個檔案時發生冷啟動延遲。 此設定也支援建置連結庫，以程序設計方式以 non-.NET 語言與 Bicep 檔案互動。

傳送和接收輸入/輸出的電線格式是以標頭分隔，使用下列結構，其中 \r 和 \n 代表歸位字元和換行字元：

Content-Length: <length>\r\n\r\n<message>\r\n\r\n

• <length> 是字串的 <message> 長度，包括尾端 \r\n\r\n。
• <message> 是原始 JSON 訊息。

例如：

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

下列訊息顯示 Bicep 版本的範例。

• 輸入：

  {
    "jsonrpc": "2.0",
    "id": 0,
    "method": "bicep/version",
    "params": {}
  }
  

• 輸出如下：

  {
    "jsonrpc": "2.0",
    "id": 0,
    "result": {
      "version": "0.24.211"
    }
  }
  

如需可用的方法和要求/響應主體，請參閱 ICliJsonRpcProtocol.cs。 如需建立 JSONRPC 連線並使用 Node 以程式設計方式與 Bicep 檔案互動的範例，請參閱 jsonrpc.test.ts。

命名管道的使用方式

使用下列語法，以 JSONRPC 用戶端身分連線到現有的命名管道：

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> 是用來連接 JSONRPC 用戶端的現有命名管道。

若要連線到 OSX/Linux 上的命名管道：

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

若要連線到 Windows 上的命名管道：

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

如需更多範例，請參閱 C# 和 node.js。

TCP 套接字的使用方式

使用下列語法，以 JSONRPC 用戶端身分連線到現有的 TCP 套接字：

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> 是 JSONRPC 用戶端所連線的套接字編號。

若要連線到 TCP 套接字：

bicep jsonrpc --socket 12345

stdin 和 stdout 的使用方式

使用下列語法和 和 stdin stdout 來執行 JSONRPC 介面的訊息：

bicep jsonrpc --stdio

lint

此命令 lint 會傳回 Bicep 檔案的錯誤和 linter 規則 違規。

az bicep lint --file main.bicep

如果您的 Bicep 檔案包含參考外部登入的模組， lint 命令會自動呼叫 restore。 命令 restore 會從登錄取得檔案，並將它儲存在本機快取中。

注意

命令 restore 不會重新整理快取。 如需詳細資訊，請參閱還原。

如果不要自動呼叫 restore，請使用 --no-restore 參數：

az bicep lint --no-restore <bicep-file>

如果其中一個外部模組尚未快取，則具有 --no-restore 參數的 lint 程序會失敗：

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

當您收到此錯誤時，請在沒有 --no-restore 參數的情況下執行 lint 命令，或先執行 bicep restore。

list-versions

list-versions 命令會傳回所有可用的 Bicep CLI 版本。 使用此命令，來查看您是否要升級 (部分機器翻譯) 或安裝 (部分機器翻譯) 新版本。 此命令只能透過 Azure CLI 使用。

az bicep list-versions

此指令會傳回可用版本的陣列：

[
  "v0.28.1",
  "v0.27.1",
  "v0.26.170",
  "v0.26.54",
  "v0.25.53",
  "v0.25.3",
  "v0.24.24",
  "v0.23.1",
  "v0.22.6",
  "v0.21.1",
  "v0.20.4",
  "v0.19.5",
  "v0.18.4",
  "v0.17.1",
  "v0.16.2",
  "v0.16.1",
  "v0.15.31",
  "v0.14.85",
  "v0.14.46",
  "v0.14.6",
  "v0.13.1",
  "v0.12.40",
  "v0.12.1",
  "v0.11.1",
  "v0.10.61",
  "v0.10.13",
  "v0.9.1",
  "v0.8.9",
  "v0.8.2",
  "v0.7.4"
]

publish

publish 命令會將模組新增至登錄。 Azure 容器登錄必須存在，而且發佈至登錄的帳戶必須有正確的權限。 如需設定模組登錄的詳細資訊，請參閱使用 Bicep 模組的私人登錄 (部分機器翻譯)。 若要發佈模組，帳戶必須有正確的設定檔與權限，才能存取登錄。 您可以在 Bicep 設定檔案中，設定向登錄進行驗證的設定檔與認證優先順序。

將檔案發佈至登錄之後，您可以在模組中參考該檔案 (部分機器翻譯)。

您必須有 Bicep CLI 0.14.X 版或更新版本，才能使用 publish 命令和 --documentationUri/-d 參數。

若要將模組發佈至登錄，請使用：

az bicep publish --file <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

例如：

az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

命令publish無法辨識bicepconfig.json檔案中指定的別名。 提供完整的模組路徑。

警告

發佈至相同目標會覆寫舊模組。 建議您在更新時遞增版本。

還原

當 Bicep 檔案使用已發佈至登錄的模組時，restore 命令會從登錄取得所有必要模組的複本。 其會將那些複本儲存在本機快取中。 只有當本機快取中有可用的外部檔案時，才能建置 Bicep 檔案。 因為建置程序會自動觸發還原，因此通常不需要另外執行。

若要將外部模組還原至本機快取，帳戶必須有正確的設定檔與權限，才能存取登錄。 您可以在 Bicep 設定檔案中，設定向登錄進行驗證的設定檔與認證優先順序。

若要使用 restore 命令，您必須擁有 Bicep CLI 0.14.X 版或更新版本。 此時，只有直接呼叫 Bicep CLI 時，才能使用此命令。 目前無法透過 Azure CLI 取得。

若要手動還原檔案的外部模組，請使用：

az bicep restore --file <bicep-file> [--force]

您提供的 Bicep 檔案是您希望部署的檔案。 其必須包含連結至登錄的模組。 例如，您可以還原下列檔案：

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

您可以在下列位置中找到本機快取：

• 在 Windows 上

  %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>
  

• 在 Linux 上

  /home/<username>/.bicep
  

• 在 Mac 上

  ~/.bicep
  

如果模組已經快取，restore 命令不會重新整理快取。 若要重新整理快取，您可以從快取中刪除模組路徑，或使用 --force 參數搭配 restore 命令。

升級

upgrade 命令會以最新版本更新您安裝的版本。 此命令只能透過 Azure CLI 使用。

az bicep upgrade

version

命令 version 會傳回已安裝的版本：

az bicep version

這個指令會顯示版本號碼：

Bicep CLI version 0.22.6 (d62b94db31)

若要直接透過 Bicep CLI 呼叫此命令，請使用：

bicep --version

如果尚未安裝 Bicep CLI，您會看到錯誤訊息，指出找不到 Bicep CLI。

下一步

若要深入瞭解如何部署 Bicep 檔案，請參閱：

• 部署 - Azure CLI
• 部署 - Azure PowerShell
• 部署 - Cloud Shell