Parameters - First Release

[stephaniezyen]

Main Story: #7301

First Release - Plans

Here are the features we're proposing for the first official release (combination of the "Summer" & "MVP" section - with some MVP pieces cut out). Most of the "Summer" work has already been completed, which is why it's not included here.

Basic Language Features

Code Completion and Navigation

• Add support for parameter names refactoring #9568 Add support for parameter names refactoring
• Add descriptions to parameter symbol completions  #9574 Add descriptions to parameter symbol completions
• Add support for displaying symbol type and description when hovering  #9575 Add support for displaying symbol type and description when hovering
• I can see an outline of all the parameters I have declared in the outline view of the explorer in VS Code
• I can get errors if set values are of the wrong type or do not follow constraints set by decorators as described in the Bicep template
• I can see the allowed values for parameters that utilize the @Allowed decorator
• I can use Go To Definition to jump to the location in the Bicep file where the parameter is defined
• I can use Find Ref to pull up a VS Code window that shows all references to a parameter (right click - find all references)

Environment Variables

• Add support for environment variable values  #9576 Add support for environment variable values

Bicep Parameter File Generation

• Add VS Code action to generate a Bicep parameter file  #10164 Add VS Code action to generate a Bicep parameter file
• Create decompile functionality for params file #10165 Create decompile functionality for params file

Compatibility with Current Tooling

• Add bicep parameter file support for Az CLI #9582 Add bicep parameter file support for Az CLI
• Add bicep parameter file support for Powershell #9583 Add bicep parameter file support for Powershell
• Enable current Deploy file action to read parameters file #9584 Enable current Deploy file action to read parameters file

Other

• Ensure we have icons available for the Bicep param files
• Remove the feature flag once this is feature complete
• Update grammar libraries

If time permits

• Expression support (POC: Expressions in Bicep parameters files #10248)

[dciborow]

Was lead here from the docs on experimental features, but was a little hard to find an example of how to use the feature.

storage_account_template.bicepparam

using './storage_account_template.bicep'

param location = 'westus2'

param kind = 'StorageV2'

storage_account_template.bicep

var storageAccountName = 'store${uniqueString(resourceGroup().id)}'

param location string

param kind string

resource sa 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: kind
  properties: {}
}

[mattiasholm]

Just tried out this feature and while I obviously prefer the new syntax, I did run into a problem that I hope will be addressed.

Thing is, I have a few use cases where I pass some parameters inline with the Azure CLI instead of hard-coded in the param file.
This was working fine with JSON param files, since the parameter validation doesn't take place until the actual deployment, but with the new Bicep param files I now get an error that a required parameter is missing, which of course technically is true.

I realize I could simply add a dummy default value as a workaround, but that would also change the behavior of my template, since the parameter won't be mandatory anymore.

Is there or will there be an official way of supporting this?

[alex-frankel]

@mattiasholm - I think #10454 captures the same problem, do you agree?

[mattiasholm]

@alex-frankel
Yeah, a warning instead of an error would certainly make it less restrictive, without losing the validation entirely!

However, after testing some more I also noticed that the Azure CLI is currently blocking using --parameters repeatedly whenever a Bicep param file is used:

Can not use --parameters argument more than once when using a .bicepparam file

[stephaniezyen]

@mattiasholm, it is actually by design that we don't support inline parameters with bicepparam to allow for a simpler experience, but considering that it seems like several users have inline parameters as part of their deployment experience, we'll discuss supporting it by the first release! Thanks for letting us know

[brwilkinson]

It's probably late to be asking this, however given the depreciation of inline parameters, would it be feasible to scope in the usage of the loadtextcontent|loadjsoncontent as part of the first release, along with the environment variable capability?

That would open up or unblock so many use cases for the bicepparam. Anyone could just transition code from inline/dynamic params to loadjsoncontent.

[mattiasholm]

I can see use cases for allowing both inline params and environment variables in addition to param files.

This would also align well with Terraform, for those of us who are using both! 😊

[brwilkinson]

It's probably late to be asking this, however given the depreciation of inline parameters, would it be feasible to scope in the usage of the loadtextcontent|loadjsoncontent as part of the first release, along with the environment variable capability?

• doing more testing today and this does work already.

default.bicepparam 🟩

param Global = loadJsonContent('Global-Config.json')

Then also ...

build or just deploy already works 🟩

# works with 'loadJsonContent'
bicep build-params ".\default.bicepparam"

# no need to build (as above) since AZ 9.7.0 which includes az.resources 6.6.1, also works with `loadJsonContent` 
New-AzResourceGroupDeployment -TemplateParameterFile ".\default.bicepparam"

I am sure I was using the same version 4 days ago and it wasn't working, however I am thankful for this 🥳🙏

for me below will be useful to replace dynamic params passed to New-AzResourceGroupDeployment

param Global = {
  global: loadJsonContent('Global-Config.json')
  regional: loadJsonContent('Global-AEU1.json')
}

[brwilkinson]

I did some extra review of my dynamic param usage and I cannot move ALL of my dynamic params into the bicepparam file.

I am expressing interest to continue to allow usage of dynamic params along with the new bicepparam capabilities.

[jikuja]

I did some extra review of my dynamic param usage and I cannot move ALL of my dynamic params into the bicepparam file.

Same. We are using common parameters like project and environmentName on out templates:

• project is injected from common ADO variable group
• environment is injected from environment-specific ADO variable group

For some templates we need to query existing properties of the resources and pass them as template parameters to avoid loosing state on re-deployment.

For some templates we need to query objects ids from AAD to pass them as template parameters.

For our projects current first release is a cool tech demo but is not usable for production templates. At some point environment variable support will make things easier.

[brwilkinson]

@jikuja

At some point environment variable support will make things easier.

I believe this is still scheduled in the first release.

• It will be interesting to test once it's available, It's hard to say until then, all use cases that it might unblock.
• Perhaps can set ENV var values dynamically, instead of passing params dynamically.

[stephaniezyen]

@brwilkinson can you provide an example or a mockup of what you are looking to try to do?

I did some extra review of my dynamic param usage and I cannot move ALL of my dynamic params into the bicepparam file.

I am expressing interest to continue to allow usage of dynamic params along with the new bicepparam capabilities.

[alex-frankel]

I believe Ben's goal is to do the following:

az deployment * create -f main.bicep --parameters params.bicepparam otherParam=foo

If otherParam exists in params.bicepparam, then what is passed on the command line would override it.

[brwilkinson]

Thank you @stephaniezyen and confirming @alex-frankel example covers the scenario.

This is the current behavior in AZ cli and AZ powershell.

We are aware that this dynamic parameter pattern was not in scope for the first release of bicepparam, however a few people included myself do rely on this feature, so would welcome it back.

We will gain environment var ref in params, however I am not sure if it's a replacement for all dynamic param use cases.

[jikuja]

I think personally think that support for

az deployment * create -f main.bicep --parameters params.bicepparam otherParam=foo

should be put on hold because same should be workarounded with

bicep build-params params.bicepparam --outfile otherParams.json
az deployment * create -f main.bicep --parameters otherParams.json otherParam=foo

Reasoning:

• Allow parameters to be omitted so they can be supplied at deploy-time #10454 should be handled first. looks like it was triagad and unassigned. What was the decision?
• the workflow with BCP258: Adding placeholder values on .bicepparams and then overriding then on command-line tooling requires extra work and I personally would like to avoid using placeholder values that might be masking missing required parameters

[brwilkinson]

@jikuja

I believe the two ideas are directly related, just looking at it from a different perspective.

• since if you want to provide param values dynamically on cli you wouldn't have them in the param file.
  • so that directly relates to the error, that we are looking to work around.

Given we don't actually have loadEnvVar() yet, it's harder to test ideas.

What if we had...

otherParams.bicepparam

using 'main.bicep'

param prefix = loadEnvVar('prefix')
param global = json(loadEnvVar('global'))

Then in your deployment, you can pass in those values and they override or get bound to ENV vars on the cli?

# az cli
az deployment * create -f main.bicep --parameters otherParams.bicepparam prefix=ACU1 global='[{"abc":123}]'

# powershell
$splatParams=@{
   prefix = 'ACU1'
   global = '[{"abc":123}]'
}

New-AzResourceGroupDeployment -TemplateFile main.bicep  -TemplateParameterFile otherParams.bicepparam @splatParams

Would it be functionally equivalent to what we have now i.e. what we have both asked for in this thread?

Not saying this specific syntax, just the general idea.

[brwilkinson]

Has anyone been doing any testing with bicepparam ?

bicepparam file

using '../../bicep/01-ALL-RG.bicep'

param Prefix = 'AWU3'

param Environment = 'P'

param DeploymentID = '0'

param Global = {}

I am using PowerShell - Az.Resources Module - 6.7.0

Dynamic parameters and also overriding Global above appears to be working for me ?

---

This is the format that I currently use, that works... I tested some other formats that do not appear to work, however I haven't tested extensively.

example template - aaaas.bicep

param abc string
param global object


output abc string = abc
output global object = global

example bicepparam file - aaaas.bicepparam

using 'aaaas.bicep'

param abc = '123'
param global = {}

The way I do my powershell for dynamic parameters

$ResourceGroupName = 'AWU3-PE-AD-RG-P0'
$DeploymentName = 'mytest'
$TemplateParametersFile = 'D:\repos\ADF\ADF\bicep\demos\aaaas.bicepparam'
$TemplateFile = 'D:\repos\ADF\ADF\bicep\demos\aaaas.bicep'

$TemplateArgs = @{ }
$TemplateArgs.Add('TemplateParameterFile', $TemplateParametersFile)
$TemplateArgs.Add('TemplateFile', $TemplateFile)

$Global = @{ }
$Global.Add('test', 678)

$OptionalParameters = @{ }
$OptionalParameters['Global'] = $Global

$Common = @{
    Name          = $DeploymentName
    Location      = $ResourceGroupLocation
    Verbose       = $true
    ErrorAction   = 'Continue'
    ErrorVariable = 'e'
}

$Common.Remove('Location')
$Common['ResourceGroupName'] = $ResourceGroupName

New-AzResourceGroupDeployment @Common @TemplateArgs @OptionalParameters

DeploymentName          : mytest
ResourceGroupName       : AWU3-PE-AD-RG-P0
ProvisioningState       : Succeeded
Timestamp               : 6/19/2023 8:17:36 PM
Mode                    : Incremental
TemplateLink            : 
Parameters              : 
                          Name             Type                       Value
                          ===============  =========================  ==========
                          abc              String                     "123"
                          global           Object                     {"test":678}

Outputs                 : 
                          Name             Type                       Value
                          ===============  =========================  ==========
                          abc              String                     "123"
                          global           Object                     {"test":678}

EDIT:

Now I can't break it, it always appears to work, simple repro that works below.

New-AzResourceGroupDeployment -global @{test=123} -TemplateParameterFile .\aaaas.bicepparam -TemplateFile .\aaaas.bicep -ResourceGroupName $ResourceGroupName -verbose