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 檔案轉換為 Azure Resource Manager 範本 (ARM 範本)。 一般來說，您不需要執行此命令，因為其會在您部署 Bicep 檔案時自動執行。 當您想要查看從 Bicep 檔案建立的 ARM 範本 JSON 時，請手動加以執行。

使用下列任何 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，請使用 --no-restore 參數：

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

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

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not 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 命令會將 ARM 範本 JSON 轉換成 Bicep 檔案。

az bicep decompile --file main.json

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

如需使用此命令的詳細資訊，請參閱將 ARM 範本 JSON 反向組譯為 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 的參數檔案。 參數檔案只包含參數，不會在 Bicep 檔案中設定預設值。

安裝

install 命令會將 Bicep CLI 新增至您的本機環境。 如需詳細資訊，請參閱安裝 Bicep 工具。 此命令僅可透過 Azure CLI 使用。

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

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，請使用 --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 設定檔案中，設定向登錄進行驗證的設定檔與認證優先順序。

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

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

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

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.4.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
• Cloud Shell
• PowerShell