GroupName property of New-AzManagementGroupSubscription should be updated to match its meaning

[nguyenlamlll]

Current implementation

Currently, New-AzManagementGroupSubscription accepts a parameter called GroupName, depicted as "Management Group Id". This is quite confusing (at least, to me, when I read the docs).

GroupName is confusing because, on the Azure Portal, we have Group Name and Group ID. Group Name is allowed to have spaces. When we see the param's name of the PS command, we naturally pass in the Group Name from Azure Portal.

PS /home/user > New-AzManagementGroupSubscription -GroupName 'A B C D' -SubscriptionId $subscriptionId
New-AzManagementGroupSubscription: The provided management group name 'A B C D' has these invalid characters: ' ,  '. The name can only be an ASCII letter, digit, -, _, (, ), .

It's even more confusing when I read the error. It clearly says "the provided management group name".

However, in the end, the command works when I pass the ID of the management group.

Description of the new feature

The parameter should be named accordingly to its meaning.

Proposed implementation details

Is it this source file here? Sorry, I am not familiar with the source code structure of this repo.

If so, rename the property GroupName to the name GroupId or ManagementGroupId.

[dingmeng-xue]

@nguyenlamlll, thanks for your reporting. It seems all AzManagementGroup related cmdlets have the similar issues. Could you help to confirm format of ID you are using? Does its format like /subscriptions/{sub}/resourceGroups/groupname?

[nguyenlamlll]

Could you help to confirm format of ID you are using? Does its format like /subscriptions/{sub}/resourceGroups/groupname?

Hi @dingmeng-xue, I don't quite get what you need me to do here.

In my scenario, I create a new "Management group". There is one field called "Management group ID" (user-provided) and "Management group display name". So, let's say I create a management group call "My Group" with an Id "c4be30d9-e22b-475b-af49-a6cf6230a114".

Next, I move my existing subscriptions to the newly created management group using the script below (and the result):

PS > New-AzManagementGroupSubscription -GroupName 'My Group' -SubscriptionId $subscriptionId
New-AzManagementGroupSubscription: The provided management group name 'My Group' has these invalid characters: ' ,  '. The name can only be an ASCII letter, digit, -, _, (, ), .

This is confusing like I have reported above. And the one that works is to use the ID of the management group "c4be30d9-e22b-475b-af49-a6cf6230a114".
So, the working script would be:

PS > New-AzManagementGroupSubscription -GroupName 'c4be30d9-e22b-475b-af49-a6cf6230a114' -SubscriptionId $subscriptionId

The param's name here is clearly vague and confusing as what I'm required to pass in is the ID, not the name.

[dcaro]

@nguyenlamlll the reference documentation for the [New-AzManagementGroupSubscription cmdlets] (https://docs.microsoft.com/en-us/powershell/module/az.resources/new-azmanagementgroupsubscription), indicates that the -GroupName parameter is expecting the "Management Group Id".
I agree that the name of the parameter is confusing and we should consider changing it to -GroupId for example. We will not be able to do this until the next breaking change opportunity in few months.

[dingmeng-xue]

@wyunchi-ms , can you add breaking change warning for the time being?

[dcaro]

as per @mikefrobbins can we rename the GroupName parameter to be GroupId and create a parameter alias for GroupName that we will deprecate at the next breaking change window?