[Feedback wanted!] Configuration Cmdlets for Azure PowerShell

[isra-fel]

Hi 👋, this is Yeming from Azure PowerShell team. In the upcoming releases we plan to introduce a set of cmdlets to help you configure the behavior of Azure PowerShell, which used to be done by environment variables or several seperate cmdlets. Here's a first peek of what it looks like:

Examples

# Get-AzConfig by default lists all the configs.
PS C:\> Get-AzConfig

Key     Value       Scope AppliesTo    HelpMessage    DefaultValue
---     -----       ----- ---------    -----------    ------------
ConfigA     3 CurrentUser Az           {help message}           -1
ConfigA   100 CurrentUser Use-AzConfig {help message}           -1
ConfigB  True CurrentUser Az           {help message}         True

# You can filter them with some filter parameters and config key parameters (in this example, -ConfigA)
PS C:\> Get-AzConfig -ConfigA -AppliesTo Az

Key     Value       Scope AppliesTo HelpMessage    DefaultValue
---     -----       ----- --------- -----------    ------------
ConfigA     3 CurrentUser Az        {help message}           -1

# Update-AzConfig updates configs. The update can be effective for this PowerShell session, or be persistent for future ones. It can also apply to whole Az or a certain module or a cmdlet.

PS > Update-AzConfig -BreakingChangeMessage $false

Key          : BreakingChangeMessage
Value        : False
Scope        : CurrentUser
AppliesTo    : Az
HelpMessage  :
DefaultValue :

# Clear-AzConfig undoes Update-AzConfig.
PS > Clear-AzConfig -BreakingChangeMessage

{ Does not return }

Syntax

Get-AzConfig [-AppliesTo <string>] [-Scope {CurrentUser | Process}] [-ConfigA] [-ConfigB]

Update-AzConfig [-AppliesTo <string>] [-Scope {CurrentUser | Process}] [-WhatIf] [-Confirm] [-ConfigA <int>] [-ConfigB <bool>]

Clear-AzConfig -All [-PassThru] [-AppliesTo <string>] [-Scope {CurrentUser | Process}] [-WhatIf] [-Confirm]
Clear-AzConfig [-PassThru] [-AppliesTo <string>] [-Scope {CurrentUser | Process}] [-WhatIf] [-Confirm] [-ConfigA] [-ConfigB]

How to specify the key of a config

One interesting design decision we made is how to specify the key of a config in these cmdlets. Considering the scenario to update 2 configs.

# The updates are passed as seperate parameters
Update-AzConfig -ConfigA 10 -ConfigB $false

Take a look at the -ConfigA and -ConfigB - these parameters are mapped from configs and dynamically added to the cmdlets. We find this design more intuitive to use. Also you can easily learn about every config by Get-Help.
However, the weakness is the list of parameters grows as the number of supported configs grows. The cmdlet syntax can be quite long as time goes.

Comparing to a more traditional approach, for example:

# The updates are passed as an array of hash tables each carrying key and the updated value.
Update-AzConfig -Config @(
    @{ Key = "ConfigA"; Value = 10 },
    @{ Key = "ConfigB"; Value = $false }
);

The traditional design scales better as more configs are added to Azure PowerShell -- cmdlet syntax does not change at all. But it loses the benifits in documentation and is a little bit more complex.

We want to hear from you 😉

How do you like the two different approaches of specifying a config key?
Which one do you prefer?
Have these cmdlets satisfied your needs in configs?

Let us know down in the comments. Looking forward to hearing your thoughts!

[abroeke]

I can see both the approaches working, would prefer the first (dynamic params) one.

Maybe it's al little bit of topic, but don't know where to drop this. Would it be possible for the 'BreakingChangeMessage' to appear once per session (per cmdlet call) instead of on every call?

[isra-fel]

Thanks for the feedback :)
I'm also interested in the idea of displaying warning messages of upcoming breaking changes once per PS session. Looping in our PM @dcaro for triaging .

[KevinMarquette]

It's also important to remember that the first option also supports splatting.

$options = @{
    ConfigA = 10
    ConfigB = $false
}
Update-AzConfig @options

And if you use ValueFromPipelineByPropertyName on those parameters, we can pipe it in directly from a JSON file.

Get-Content -Path $path | 
    ConvertFrom-Json |  
    Update-AzConfig

Both of these will be more intuitive and naturally fit into PowerShell. Lean in on how PowerShell was intended to be used before trying other stuff.

I also think you are taking the wrong approach in the "traditional" example. Change that from an array of hashtables to just a hashtable, then you can just do this: (assuming -Config is positional parameter 0)

Update-AzConfig @{
    ConfigA = 10
    ConfigB = $false
}

This is a DSL style approach. A little bit clever, but still more natural to work with than your original traditional example. I think an array of hashtables would be the worst of all the options. (Design for the user, not the internal data structures)

[isra-fel]

Hey Kevin. Appreciate your feedback and many suggestions! You are indeed very true that using hashtable should be the more common way to do this.