Proposal: VSCode Extension – Improve Bicep menu

[SetTrend]

Current Situation

I noticed that the Bicep menu and deployment workflow are technically oriented rather than user focussed. From my observation, the menu's wording leads to misunderstanding, and the order of the menu items are confusing and misleading.

So, I suggest to improve the Bicep menu and workflow by the following usability enhancements, making Bicep easier to grasp and use:

Three usability issues with the current Bicep menu

1. Wording is misleading
2. Menu item sequence doesn't reflect workflow
3. Any available json file is suggested as parameters file

1. Wording is misleading

Build Bicep File

By convention, it has become a common wording habit that sources are compiled/transpiled while targets are built. For instance, we "compile" a "C++" file, and we "build" a "WPF application". We don't "build" a "C++ file".

Given that, the generally accepted rule is that we "compile {source type}" and "build {target type}".

This common rule is violated with the menu item's wording "Build Bicep File" because, in fact, this menu item builds an ARM Template file. So, the correct wording for that menu item would be "Build ARM Template".

Deploy Bicep File...

This menu item text is misleading, because it is not deploying a text file. Instead, it is potentially deploying resources to Azure. Resources that are going to be charged for. The focus of this menu item should be on the result, not on the first step in the technical process. So, a better wording for that menu item would be "Deploy Resources To Azure...".

Restore Bicep File (Force)

This menu item is not restoring a single Bicep file. Instead, it's restoring all referenced Bicep modules. So, the correct wording for that menu item would be "Restore Bicep Modules (Force)".

2. Menu item sequence doesn't reflect workflow

The following menu items take part in composing a Bicep file:

• Restore Bicep Modules (Force)
• Insert Resource...
• Generate Parameters File
• Build ARM Template

(Preferrably in this sequence.)

Deploy Resources To Azure... is not part of this composing process. So, this menu item should not be put amidst these other menu items.

3. Any available json file is suggested as parameters file

When deploying resources to Azure using the Deploy Bicep File... menu item, the process suggest any available json files, even those not being valid parameters files:

This is confusing and misleading.

The process should only list valid parameters files that adhere to the Bicep Parameters file JSON schema.

Desired Situation

(1) Re-arrange Bicep Menu Items

To make working with Bicep more streamlined and easier to grasp, I propose to re-arrange and rename the Bicep menu items to look like this:

(Please note the additional separators and the additional mnemonic.)

(2) Filter Parameters Files In Deployment Process

In the process of deploying the current Bicep file's resources, only suggest json files that …

• are valid
• are not empty
• adhere to the JSON schema for Bicep Parameters files

[alex-frankel]

@ucheNkadiCode -- can you take a look at this one and see if we want to make any changes?

[ucheNkadiCode]

Awesome feedback @SetTrend! Thanks a bunch!

My opinions are:

• I think "Build ARM Template" is definitely more clear and true to purpose
• I'm not super familiar with all the use cases of "Restore Bicep Modules" so I don't have an opinion on this.
• Personally, although I see your point of "Deploy Bicep file" could be "Deploy resources to Azure", users often "run deployment scripts" which is similar to us deploying a Bicep file in this fashion. I think Deploy Bicep file is clear enough for users and leaves wiggle room if we ever expand to other clouds in the future.
• Correct me if I'm wrong, but aren't there some limitations on how we can separate certain menu items on file explorer menu vs in file menu vs file tab menu @bhsubra or @StephenWeatherford? I think we ran into limitation of VS Code on this one. For consistency it may not be possible to truly seperate "Deploy Bicep file" from the

[SetTrend]

Thanks, @ucheNkadiCode, for taking the time to deal with my proposal and share your valuable thoughts!

• I think Deploy Bicep file is clear enough for users and leaves wiggle room if we ever expand to other clouds in the future.

Yes, I was pondering myself about the question "what if MS extends Bicep for addressing other cloud providers" in regard to the "to Azure" bit. Then I came to the conclusion: "Well, leave it in there. Later on, they can still change it to deploy resources to the cloud... or deploy resources to servers... or just omit the target and keep deploy resources.... I still favor resources over Bicep file, though.

[ucheNkadiCode]

I appreciate your feedback! @anthony-c-martin do you have an opinion on Restore Bicep Modules (force)? I think it could be a great idea for naming clarity, but I'm not familiar with the use case.

As for Build ARM Template, I will submit that to the backlog

[StephenWeatherford]

We need to also consider the ARM extension menus during this (in particular, there are currently some points of confusing if you have both extensions installed, there's a bug on this). Let's discuss a full proposal when we meet.

I'm not super familiar with all the use cases of "Restore Bicep Modules" so I don't have an opinion on this. Sounds good to me.

Personally, although I see your point of "Deploy Bicep file" could be "Deploy resources to Azure", users often "run deployment scripts" which is similar to us deploying a Bicep file in this fashion. I think Deploy Bicep file is clear enough for users and leaves wiggle room if we ever expand to other clouds in the future. Personally I agree with this.

Correct me if I'm wrong, but aren't there some limitations on how we can separate certain menu items on file explorer menu vs in file menu vs file tab menu @bhsubra or @StephenWeatherford? I think we ran into limitation of VS Code on this one. For consistency it may not be possible to truly seperate "Deploy Bicep file" from the

Don't think this will be an issue.

[StephenWeatherford]

Filtering issue broken off to here: https://github.com/Azure/bicep/issues/7752

[SetTrend]

Thanks, @StephenWeatherford.

I was hoping for a complete menu redo to improve user experience, not just renaming a single menu item.

[StephenWeatherford]

Discussed withi @ucheNkadiCode, this is the decision (accepting two of the text changes and the change in menu ordering):

Restore Bicep Modules (Force) <<< change in text
Insert Resource... 
Generate Parameters File
Build ARM Template  << change in text
---
Deploy Bicep File (no changes)
---
Open Bicep Visualizer
Open Bicep Visualizer to the Side

This change would carry to the 3 context menu options (file explorer, file tab, right click on file). Closing https://github.com/Azure/bicep/issues/7747 in favor of using this bug to track that change.

[StephenWeatherford]

• [x] Does it affect the walkthrough?

[ucheNkadiCode]

• [x] Does it affect the walkthrough?

Nope! We don't use "Bicep build" nor "Restore"