Bicep VS Code extension should show/remove properties with default values

[NeilMacMullen]

Is your feature request related to a problem? Please describe.
I'm desperately trying to migrate away from a set of poorly-understood ARM templates. It's great that there are a bunch of example BICEP projects in the repo but the vast majority appear to be uncommented and suffer from the same issue as ARM templates - i.e every possible parameter has been filled out with no indication of which are defaults and which are "important".

In contrast, when I create a resource in the Azure Portal, it's (generally) quite simple to leave everything at default settings and have the UI guide you through the few mandatory changes.

Describe the solution you'd like

This is just a suggestion and perhaps there are better ways to do this but:

• The VS Code extension could provide different styling for parameters which have a required non-default value (e.g. names) or a strongly encouraged non-default value (e.g. locations).
• The VS Code extension could provide different styling for parameter values which are at their default (factory) setting
• The VS Code extension could provide tooltip descriptions for parameter names and values.

For example when I look at https://github.com/Azure/bicep/blob/main/docs/examples/101/vm-simple-windows/main.bicep (which seems fairly representative) it's entirely unclear whether

var addressPrefix = '10.0.0.0/16'

is being set for some specific reason or if it's just the standard default. And if it's the default, why can't I just write

resource nInter 'Microsoft.Network/networkInterfaces@2020-06-01' = {
  name: nicName
  location: location
}

and have the properties block defaulted?

[alex-frankel]

In general, we encourage examples that we review (in this repo and in ARM Template Quick Starts) to only include non-defaulted properties, so you should assume it is there because it needs to be. If you export a template from the portal you will get a lot of superfluous default properties, so take those templates for what they are worth. Personally, I'd only recommend using them to discover the shape of a particular resource, but not use it directly in production.

In that particular example, the addressPrefix is required. There is no way to have it set for you automatically. The confusing part here is that this particular resource type does not do a great job defining required properties in their REST API spec (which is what powers the bicep types), so bicep will tell you it's not required even though it is.

Where would you like the information you are asking for to be surfaced? When you bring up completions while authoring a resource, we will tell you which properties are required:

[NeilMacMullen]

In that particular example, the addressPrefix is required. There is no way to have it set for you automatically.

i don't doubt you but I'm pretty certain I have never had to explicitly set this value when creating a VM in the portal. "As an Azure user" why would I suddenly have to start worrying about it when using BICEP? (As a developer I'm sympathetic to the technical difficulties of getting the information via the REST spec but that seems like a problem the Azure team could reasonably resolve?)

Where would you like the information you are asking for to be surfaced?

My suggestion was slightly different - use the knowledge you have to influence the styling the VS code extension applies. At the moment I believe the styling is based on the type of value whereas it could be based on the kinds of parameters I described. Here's a clumsy powerpoint mockup where I've bolded and underlined required fields and colored "default" values gray and modified values red.

To me, this makes it far easier to ignore the boilerplate defaults and scan a template to see what has been changed.

[alex-frankel]

I'm pretty certain I have never had to explicitly set this value when creating a VM in the portal.

Nailed it. The portal client is abstracting these details away from you. I suspect this will be solved with the #2128 in which Microsoft (and others) can publish a canonical interface (via a module) for a particular resource or set of resources to abstract this away. In a sense, the portal UX (and a PS or CLI client) is analogous to a built-in module in the registry. They are both hand-authored and designed to make consumption of that resource(s) as easy as possible.

WRT the VS code ux for properties, that mockup helped clarify. I guess what I'm stuck on is that all the properties with default values shouldn't even be there - they are just noise. IOW, why not remove all the properties with gray values? There's probably something that could be added to the linter (#2341) to catch "properties with values set to the default value" and provide a quick fix to remove it. (FYI @MarcusFelling @jfleisher).

[NeilMacMullen]

guess what I'm stuck on is that all the properties with default values shouldn't even be there - they are just noise. IOW, why not remove all the properties with gray values?

No argument there, you're actually going further than I hoped for :-) Tbf, it is sometimes useful to see what could be changed and you still need a styling policy for values which are present but changed back to their default value. Another possibility would be to use folding to hide blocks of default values.

[ucheNkadiCode]

Related to #5316

[StephenWeatherford]

@NeilMacMullen I'm changing the title of this bug to reference just the default properties issue. Above, though, you also say:

The VS Code extension could provide tooltip descriptions for parameter names and values.
I think this functionality already exists, e.g.:

Or is it something else you meant? (If so, I'd prefer a separate issue to be entered and referenced here). Thanks!

[stijnherreman]

The confusing part here is that this particular resource type does not do a great job defining required properties in their REST API spec (which is what powers the bicep types), so bicep will tell you it's not required even though it is.

Are resource types responsible for defining the properties property as required? Or is this something that bicep should assume?

For example, https://learn.microsoft.com/en-us/azure/templates/microsoft.insights/actiongroups?pivots=deployment-language-bicep mentiones that some ActionGroup properties are required (enabled and groupShortName) but it does not mention that the root properties itself is required. So you could assume that some default values will be applied, but trying to deploy will return an error "The ActionGroup request is null or empty".

[alex-frankel]

I don't believe Bicep makes any assumptions about this and we rely on the swagger to capture this, but @anthony-c-martin / @jeskew would know for sure.

[jeskew]

Bicep does rely on resource provider service models to determine what properties are required. properties is not marked as optional in the ActionGroups body definition, and Bicep is just reflecting what's in the model.

There are resource types that don't require the properties property (Micrsoft.Storage/storageAccounts and Microsoft.ManagedIdentity/userAssignedIdentities come to mind), so I wouldn't want Bicep to just assume that not marking properties as required is a mistake.