Document bicep deployment flow to get arounding confusing experience

[SetTrend]

Bicep version

Bicep CLI version 0.8.9 (33a85174de)

Describe the bug / Steps To Reproduce

(1) – I installed all necessary Azure/Bicep tools/VS Code extensions according to documentation. Then, in Visual Studio Code, I created the most simple Bicep file:

var Test = 'Testing'

output Testing string = Test

---

(2) – The Build Bicep File menu item then created a corresponding Test.json file:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.8.9.13224",
      "templateHash": "2240475784943602056"
    }
  },
  "variables": {
    "Test": "Testing"
  },
  "resources": [],
  "outputs": {
    "Testing": {
      "type": "string",
      "value": "[variables('Test')]"
    }
  }
}

(3) – Running the Deploy Bicep File... menu item then failed:

11:44:04: Build succeeded. Created file Test.json
11:44:38: Restore (force) skipped. No modules references in input file.
11:44:49: Starting deployment of c:\Temp\Test.bicep
11:44:49: Scope specified in Test.bicep -> resourceGroup
11:44:59: Deployment canceled for c:\Temp\Test.bicep.
11:45:03: Starting deployment of c:\Temp\Test.bicep
11:45:03: Scope specified in Test.bicep -> resourceGroup
11:45:09: Parameter file used in deployment -> c:\Temp\Test.json
11:45:09: Deployment failed for c:\Temp\Test.bicep. The request content was invalid and could not be deserialized: 'Error converting value "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#" to type 'Azure.Deployments.Core.Definitions.DeploymentParameterDefinition'. Path 'properties.parameters.$schema', line 1, position 496.'.
Status: 400 (Bad Request)
ErrorCode: InvalidRequestContent

Content:
{"error":{"code":"InvalidRequestContent","message":"The request content was invalid and could not be deserialized: 'Error converting value \"https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#\" to type 'Azure.Deployments.Core.Definitions.DeploymentParameterDefinition'. Path 'properties.parameters.$schema', line 1, position 496.'."}}

Headers:
Cache-Control: no-cache
Pragma: no-cache
x-ms-failure-cause: REDACTED
x-ms-ratelimit-remaining-subscription-writes: REDACTED
x-ms-request-id: 7f9abb3d-****-4424-a6e1-fd1a9f3b7ea2
x-ms-correlation-request-id: 7f9abb3d-****-4424-a6e1-fd1a9f3b7ea2
x-ms-routing-request-id: GERMANYWESTCENTRAL:20220724T094513Z:7f9abb3d-****-4424-a6e1-fd1a9f3b7ea2
Strict-Transport-Security: REDACTED
X-Content-Type-Options: REDACTED
Date: Sun, 24 Jul 2022 09:45:12 GMT
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 363

(4) – This is my Azure CLI config file content:

[cloud]
name = AzureGermanCloud

[core]
first_run = yes
collect_telemetry = no

[logging]
enable_log_file = no

[BartDecker]

"parameters": {},

is missing from the json so the parameter file is invalid. Example would have worked with your value in a parameter instead of a variable. In this case the bicep build generates an unusable parameter file.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.7.4.23292",
      "templateHash": "9603412203452827862"
    }
  },
    "variables": {
    "Test": "Testing"
  },
  "parameters": {},
  "resources": [],
  "outputs": {
    "Testing": {
      "type": "string",
      "value": "[variables('Test')]"
    }
  }
}

[SetTrend]

I see … Yet isn't that an issue to be fixed in Bicep?

As far as I can see, the test file I provided is 100 % valid. If parameters is a necessity in the generated ARM template, then Bicep should synthesize that empty property, shouldn't it?

[anthony-c-martin]

@SetTrend you just need to select "None" for the parameters file. It sounds like you are instead selecting the generated ARM template - this is not the same thing as a parameters file.

Regardless, we should have better diagnostics for the scenario where the user selects an invalid parameters file. We should leave this open to track that.

[SetTrend]

@anthony-c-martin: There is no parameters file. Just a .bicep file. (See above.)

[alex-frankel]

When you select "Deploy a bicep file" from the context menu (by right clicking in the editor window or on the bicep file itself), we will automatically select that bicep file for deployment. It looks like you are also selecting the bicep file in a later step, which is picking your parameters file, but in this case you don't want to select a parameters file, so you should pick "None":

cc @bhsubra / @ucheNkadiCode as FYI -- there may be an opportunity to make this clearer.

[ucheNkadiCode]

So it seems like in @SetTrend's output, they were trying to select test.json as a parameters file. Was this happening automatically? Or did you select test.json (which was the build output of test.bicep) on purpose?

[SetTrend]

Ah, now I get it. I believed the json file was called an ARM Template file that's being built by running the Build Bicep File menu item. That's why I didn't understand the term "parameter" file.

Yes, I selected the json file manually. Here's a short screencast depicting what I did:

I'm not sure the documentation is quite clear about the purpose of the json file.

I read it all, yet I couldn't find an explanation on what the Build Bicep File and Deploy Bicep File... menu items actually do and what the Build Bicep File artifacts' purpose is.

[SetTrend]

Could you please elaborate on these three subjects in the documentation?

I suppose a clear, concise explanation of what the above menu items' intent and impact is is crucial to successfully using Bicep.

[alex-frankel]

@ucheNkadiCode -- do have a task for documenting the bicep deploy feature? If so, we can track that issue to make this a bit clearer and probably close this one.

@settrend just FWIW, there is no requirement to run "bicep build" at any point. Under the covers when you deploy a bicep file, we will automatically run the build command on your behalf in memory so you don't need to deal with the JSON ARM template if you don't want to.

[ucheNkadiCode]

Making sure to include @mumian

[SetTrend]

@alex-frankel:

Thank you for your valuable help!

With the help of your comments I now realized that the current Bicep menu is bewildering to new users: To me, the wording is misleading, menu item sequence is confusing, and the deployment process suggests invalid parameters files.

I took the liberty to issue an improvement request to enhance usability of the Bicep VSCode extension by re-arranging the menu and have the deployment process filter on valid parameters files:

/ref: Proposal: VSCode Extension – Improve Bicep menu

[StephenWeatherford]

Filtering on valid param files was definitely planned but not yet implemented. Don't think there's an issue yet, though, so that's good to have it added. And thanks for the other usability suggestions, too!

[StephenWeatherford]

Given that #7723 handles changes for the user experience, I believe the other actionable item left in this bug is documentation. Thus I've changed the title and re-routed to triage. I think we just assign to Jonathan?

[mumian]

The steps are documented in https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-vscode. I will add some screenshots and cross-reference the articles.

[StephenWeatherford]

Please be sure it's clear that they don't need to build the bicep file first, thanks!

[SetTrend]

I just saw that #7723 has the needs upvote tag added.

Given that, I guess, no-one except those involved in this thread will ever read that issue.

Would you mind kindly upvoting that issue if you feel it's a valid suggestion?

[StephenWeatherford]

At least two of the issues from that bug are being tracked in new bugs and have milestones assigned: #7747 #7752

[mumian]

The article has been updated.

[SetTrend]

Excellent work, @mumian!

Do you want me to close this issue here then? Or would you want to keep it open for later reference? I'll leave it up to you and your team workflow decisions.