Skip to content

Commit bdcd025

Browse files
SteveMutungi254SteveMutungi254
authored
Bug fix 1324: User resources - Cmdlet help documentation improvements to drive consistency (#1461)
1 parent 70e0b67 commit bdcd025

80 files changed

Lines changed: 914 additions & 515 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎module/Entra/Microsoft.Entra/Users/Get-EntraUserRole.ps1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ function Get-EntraUserRole {
3737
[System.String[]] $Property,
3838

3939
[Parameter(Mandatory = $false, HelpMessage = "Order items by property values.")]
40+
[Alias('OrderBy')]
4041
[System.String[]] $Sort
4142
)
4243

‎module/Entra/Microsoft.Entra/Users/New-EntraUser.ps1‎

Lines changed: 61 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -6,107 +6,113 @@ function New-EntraUser {
66
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingUserNameAndPassWordParams", "", Scope = "Function", Target = "*")]
77
[CmdletBinding(DefaultParameterSetName = 'CreateUser')]
88
param (
9-
[Parameter(ParameterSetName = "CreateUser")]
9+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The state or province in the user's address. Maximum length is 128 characters.")]
1010
[System.String] $State,
1111

12-
[Parameter(ParameterSetName = "CreateUser")]
13-
[System.String] $FacsimileTelephoneNumber,
12+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's fax number.")]
13+
[Alias('FacsimileTelephoneNumber', 'Fax')]
14+
[System.String] $FaxNumber,
1415

15-
[Parameter(ParameterSetName = "CreateUser")]
16+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The type of user (e.g., Member, Guest).")]
1617
[System.String] $UserType,
1718

18-
[Parameter(ParameterSetName = "CreateUser")]
19+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's preferred language (e.g., en-US).")]
1920
[System.String] $PreferredLanguage,
2021

21-
[Parameter(ParameterSetName = "CreateUser")]
22+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The street address of the user's place of business. Maximum length is 1,024 characters.")]
2223
[System.String] $StreetAddress,
2324

24-
[Parameter(ParameterSetName = "CreateUser")]
25+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Indicates how the user was created (e.g., LocalAccount, Invitation).")]
2526
[System.String] $CreationType,
2627

27-
[Parameter(ParameterSetName = "CreateUser")]
28+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Immutable identifier for the user from on-premises directory.")]
2829
[System.String] $ImmutableId,
2930

30-
[Parameter(ParameterSetName = "CreateUser")]
31+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's company name, useful for identifying a guest's organization. Maximum length: 64 characters.")]
3132
[System.String] $CompanyName,
3233

33-
[Parameter(ParameterSetName = "CreateUser")]
34+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's postal code, specific to their country or region (ZIP code in the U.S.). Maximum length: 40 characters.")]
3435
[System.String] $PostalCode,
3536

36-
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true)]
37+
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true, HelpMessage = "The display name of the user.")]
38+
[ValidateNotNullOrEmpty()]
3739
[System.String] $DisplayName,
3840

39-
[Parameter(ParameterSetName = "CreateUser")]
41+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Indicates if consent was obtained for minors. Values: null, Granted, Denied, or NotRequired.")]
4042
[System.String] $ConsentProvidedForMinor,
4143

42-
[Parameter(ParameterSetName = "CreateUser")]
44+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's department.")]
4345
[System.String] $Department,
4446

45-
[Parameter(ParameterSetName = "CreateUser")]
47+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's mobile phone number.")]
4648
[System.String] $Mobile,
4749

48-
[Parameter(ParameterSetName = "CreateUser")]
49-
[System.String] $UserStateChangedOn,
50+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Timestamp of the most recent change to the *externalUserState* property.")]
51+
[Alias('UserStateChangedOn')]
52+
[System.String] $ExternalUserStateChangeDateTime,
5053

51-
[Parameter(ParameterSetName = "CreateUser")]
54+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The given name (first name) of the user. Maximum length is 64 characters.")]
5255
[System.String] $GivenName,
5356

54-
[Parameter(ParameterSetName = "CreateUser")]
57+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's country or region; for example, US or UK. Maximum length is 128 characters.")]
5558
[System.String] $Country,
5659

57-
[Parameter(ParameterSetName = "CreateUser")]
60+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Set password policies like DisableStrongPassword or DisablePasswordExpiration. You can use both, separated by a comma.")]
5861
[System.String] $PasswordPolicies,
5962

60-
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true)]
63+
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true, HelpMessage = "Defines the user's password profile. Required when creating a user. The password must meet the policy requirements-strong by default.")]
64+
[ValidateNotNullOrEmpty()]
6165
[Microsoft.Open.AzureAD.Model.PasswordProfile] $PasswordProfile,
6266

63-
[Parameter(ParameterSetName = "CreateUser")]
67+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's mail alias. Required when creating a user. Maximum length: 64 characters.")]
6468
[System.String] $MailNickName,
6569

66-
[Parameter(ParameterSetName = "CreateUser")]
70+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's job title. Maximum length: 128 characters.")]
6771
[System.String] $JobTitle,
6872

69-
[Parameter(ParameterSetName = "CreateUser")]
70-
[System.String] $UserState,
73+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's external state for invited guest users (e.g., PendingAcceptance, Accepted).")]
74+
[Alias('UserState')]
75+
[System.String] $ExternalUserState,
7176

72-
[Parameter(ParameterSetName = "CreateUser")]
77+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's city location. Maximum length: 128 characters.")]
7378
[System.String] $City,
7479

75-
[Parameter(ParameterSetName = "CreateUser")]
80+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "A two-letter country code (ISO 3166). Required for licensed users to verify service availability. Examples: US, JP, GB.")]
7681
[System.String] $UsageLocation,
7782

78-
[Parameter(ParameterSetName = "CreateUser")]
83+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's surname (last name). Maximum length: 64 characters.")]
7984
[System.String] $Surname,
8085

81-
[Parameter(ParameterSetName = "CreateUser")]
86+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "A list of the user’s additional email addresses (e.g., ['bob@contoso.com', 'Robert@fabrikam.com']). Supports up to 250 entries, each up to 250 characters.")]
8287
[System.Collections.Generic.List`1[System.String]] $OtherMails,
8388

84-
[Parameter(ParameterSetName = "CreateUser")]
89+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's sign-in name (UPN) in the format alias@domain. It should match the user's email and use a verified domain in the tenant.")]
90+
[Alias('UPN')]
91+
[ValidateNotNullOrEmpty()]
92+
[ValidateScript({
93+
try {
94+
$null = [System.Net.Mail.MailAddress]$_
95+
return $true
96+
}
97+
catch {
98+
throw "UserPrincipalName must be a valid email address."
99+
}
100+
})]
85101
[System.String] $UserPrincipalName,
86102

87-
[Parameter(ParameterSetName = "CreateUser")]
88-
[System.Collections.Generic.Dictionary`2[System.String, System.String]] $ExtensionProperty,
89-
90-
[Parameter(ParameterSetName = "CreateUser")]
91-
[System.Nullable`1[System.Boolean]] $IsCompromised,
92-
93-
[Parameter(ParameterSetName = "CreateUser")]
94-
[System.String] $TelephoneNumber,
95-
96-
[Parameter(ParameterSetName = "CreateUser")]
97-
[System.String] $PhysicalDeliveryOfficeName,
103+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "The user's phone number. Only one number is allowed. Read-only for users synced from on-premises.")]
104+
[Alias('TelephoneNumber')]
105+
[System.String] $BusinessPhones,
98106

99-
[Parameter(ParameterSetName = "CreateUser")]
107+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Sets the user's age group. Options: null, Minor, NotAdult, or Adult.")]
100108
[System.String] $AgeGroup,
101109

102-
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true)]
110+
[Parameter(ParameterSetName = "CreateUser", Mandatory = $true, HelpMessage = "Indicates if the account is active. Required when creating a user.")]
103111
[System.Nullable`1[System.Boolean]] $AccountEnabled,
104112

105-
[Parameter(ParameterSetName = "CreateUser")]
106-
[System.Nullable`1[System.Boolean]] $ShowInAddressList,
107-
108-
[Parameter(ParameterSetName = "CreateUser")]
109-
[System.Collections.Generic.List`1[Microsoft.Open.AzureAD.Model.SignInName]] $SignInNames
113+
[Parameter(ParameterSetName = "CreateUser", HelpMessage = "Represents the identities that can be used to sign in to this user account. Microsoft (also known as a local account), organizations, or social identity providers such as Facebook, Google, and Microsoft can provide identity and tie it to a user account. It might contain multiple items with the same signInType value.")]
114+
[Alias('SignInNames')]
115+
[System.Collections.Generic.List`1[Microsoft.Open.AzureAD.Model.SignInName]] $Identities
110116
)
111117

112118
begin {
@@ -142,26 +148,20 @@ function New-EntraUser {
142148
if ($null -ne $PSBoundParameters["ConsentProvidedForMinor"]) {
143149
$params["ConsentProvidedForMinor"] = $PSBoundParameters["ConsentProvidedForMinor"]
144150
}
145-
if ($null -ne $PSBoundParameters["PhysicalDeliveryOfficeName"]) {
146-
$params["PhysicalDeliveryOfficeName"] = $PSBoundParameters["PhysicalDeliveryOfficeName"]
147-
}
148151
if ($null -ne $PSBoundParameters["OtherMails"]) {
149152
$params["OtherMails"] = $PSBoundParameters["OtherMails"]
150153
}
151154
if ($null -ne $PSBoundParameters["PasswordPolicies"]) {
152155
$params["PasswordPolicies"] = $PSBoundParameters["PasswordPolicies"]
153156
}
154-
if ($null -ne $PSBoundParameters["IsCompromised"]) {
155-
$params["IsCompromised"] = $PSBoundParameters["IsCompromised"]
156-
}
157157
if ($null -ne $PSBoundParameters["SignInNames"]) {
158158
$params["Identities"] = $PSBoundParameters["SignInNames"]
159159
}
160160
if ($null -ne $PSBoundParameters["PreferredLanguage"]) {
161161
$params["PreferredLanguage"] = $PSBoundParameters["PreferredLanguage"]
162162
}
163-
if ($null -ne $PSBoundParameters["UserState"]) {
164-
$params["ExternalUserState"] = $PSBoundParameters["UserState"]
163+
if ($null -ne $PSBoundParameters["ExternalUserState"]) {
164+
$params["ExternalUserState"] = $PSBoundParameters["ExternalUserState"]
165165
}
166166
if ($null -ne $PSBoundParameters["ImmutableId"]) {
167167
$params["OnPremisesImmutableId"] = $PSBoundParameters["ImmutableId"]
@@ -172,14 +172,11 @@ function New-EntraUser {
172172
if ($null -ne $PSBoundParameters["AgeGroup"]) {
173173
$params["AgeGroup"] = $PSBoundParameters["AgeGroup"]
174174
}
175-
if ($null -ne $PSBoundParameters["ExtensionProperty"]) {
176-
$params["ExtensionProperty"] = $PSBoundParameters["ExtensionProperty"]
177-
}
178175
if ($null -ne $PSBoundParameters["UsageLocation"]) {
179176
$params["UsageLocation"] = $PSBoundParameters["UsageLocation"]
180177
}
181-
if ($null -ne $PSBoundParameters["UserStateChangedOn"]) {
182-
$params["ExternalUserStateChangeDateTime"] = $PSBoundParameters["UserStateChangedOn"]
178+
if ($null -ne $PSBoundParameters["ExternalUserStateChangeDateTime"]) {
179+
$params["ExternalUserStateChangeDateTime"] = $PSBoundParameters["ExternalUserStateChangeDateTime"]
183180
}
184181
if ($null -ne $PSBoundParameters["AccountEnabled"]) {
185182
$params["AccountEnabled"] = $PSBoundParameters["AccountEnabled"]
@@ -217,14 +214,14 @@ function New-EntraUser {
217214
if ($null -ne $PSBoundParameters["CompanyName"]) {
218215
$params["CompanyName"] = $PSBoundParameters["CompanyName"]
219216
}
220-
if ($null -ne $PSBoundParameters["FacsimileTelephoneNumber"]) {
221-
$params["FacsimileTelephoneNumber"] = $PSBoundParameters["FacsimileTelephoneNumber"]
217+
if ($null -ne $PSBoundParameters["FaxNumber"]) {
218+
$params["faxNumber"] = $PSBoundParameters["FaxNumber"]
222219
}
223220
if ($null -ne $PSBoundParameters["Surname"]) {
224221
$params["Surname"] = $PSBoundParameters["Surname"]
225222
}
226-
if ($null -ne $PSBoundParameters["TelephoneNumber"]) {
227-
$params["BusinessPhones"] = @($PSBoundParameters["TelephoneNumber"])
223+
if ($null -ne $PSBoundParameters["BusinessPhones"]) {
224+
$params["BusinessPhones"] = @($PSBoundParameters["BusinessPhones"])
228225
}
229226
if ($null -ne $PSBoundParameters["CreationType"]) {
230227
$params["CreationType"] = $PSBoundParameters["CreationType"]

‎module/Entra/Microsoft.Entra/Users/New-EntraUserAppRoleAssignment.ps1‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,23 @@
55
function New-EntraUserAppRoleAssignment {
66
[CmdletBinding(DefaultParameterSetName = 'ByUserIdAndRoleParameters')]
77
param (
8-
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true)]
9-
[System.String] $PrincipalId,
8+
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true, HelpMessage = "Specifies the object ID of the principal (user, group, or service principal) to assign the app role to.")]
9+
[ValidateNotNullOrEmpty()]
10+
[guid] $PrincipalId,
1011

11-
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true)]
12-
[System.String] $ResourceId,
12+
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true, HelpMessage = "Specifies the object ID of the resource service principal (application) that exposes the app role.")]
13+
[ValidateNotNullOrEmpty()]
14+
[guid] $ResourceId,
1315

14-
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true)]
16+
[Parameter(ParameterSetName = "ByUserIdAndRoleParameters", Mandatory = $true, HelpMessage = "Specifies the ID of the app role to assign to the user.")]
17+
[ValidateNotNullOrEmpty()]
1518
[Alias("Id")]
16-
[System.String] $AppRoleId,
19+
[guid] $AppRoleId,
1720

18-
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
21+
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Specifies the ID of the user (as a UserPrincipalName or ObjectId) to whom the app role is assigned.")]
22+
[ValidateNotNullOrEmpty()]
1923
[Alias("ObjectId")]
20-
[System.String] $UserId
24+
[guid] $UserId
2125
)
2226

2327
begin {

‎module/Entra/Microsoft.Entra/Users/Remove-EntraUser.ps1‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,17 @@
44
# ------------------------------------------------------------------------------
55
function Remove-EntraUser {
66
[CmdletBinding(DefaultParameterSetName = 'Default')]
7-
param (
8-
[Alias('ObjectId')]
9-
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
7+
param (
8+
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Specifies the ID of a user (as a UserPrincipalName or ObjectId) in Microsoft Entra ID.")]
9+
[Alias('ObjectId', 'UPN', 'Identity', 'UserPrincipalName')]
10+
[ValidateNotNullOrEmpty()]
11+
[ValidateScript({
12+
if ($_ -match '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' -or
13+
$_ -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
14+
return $true
15+
}
16+
throw "UserId must be a valid email address or GUID."
17+
})]
1018
[System.String] $UserId
1119
)
1220

‎module/Entra/Microsoft.Entra/Users/Remove-EntraUserAppRoleAssignment.ps1‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,20 @@
55
function Remove-EntraUserAppRoleAssignment {
66
[CmdletBinding(DefaultParameterSetName = 'Default')]
77
param (
8-
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
9-
[System.String] $AppRoleAssignmentId,
8+
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Specifies the ID of the app role assignment to remove.")]
9+
[ValidateNotNullOrEmpty()]
10+
[guid] $AppRoleAssignmentId,
1011

11-
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
12-
[Alias("ObjectId")]
12+
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Specifies the ID of a user (as a UserPrincipalName or ObjectId) in Microsoft Entra ID.")]
13+
[Alias('ObjectId', 'UPN', 'Identity', 'UserPrincipalName')]
14+
[ValidateNotNullOrEmpty()]
15+
[ValidateScript({
16+
if ($_ -match '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' -or
17+
$_ -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
18+
return $true
19+
}
20+
throw "UserId must be a valid email address or GUID."
21+
})]
1322
[System.String] $UserId
1423
)
1524

‎module/Entra/Microsoft.Entra/Users/Remove-EntraUserManager.ps1‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,17 @@
44
# ------------------------------------------------------------------------------
55
function Remove-EntraUserManager {
66
[CmdletBinding(DefaultParameterSetName = 'Default')]
7-
param (
8-
[Alias('ObjectId')]
7+
param (
98
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
9+
[Alias('ObjectId', 'UPN', 'Identity', 'UserPrincipalName')]
10+
[ValidateNotNullOrEmpty()]
11+
[ValidateScript({
12+
if ($_ -match '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' -or
13+
$_ -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
14+
return $true
15+
}
16+
throw "UserId must be a valid email address or GUID."
17+
})]
1018
[System.String] $UserId
1119
)
1220

‎module/Entra/Microsoft.Entra/Users/Remove-EntraUserSponsor.ps1‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,21 @@ function Remove-EntraUserSponsor {
66
[CmdletBinding(DefaultParameterSetName = 'Default')]
77
param (
88
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The unique identifier (User ID) of the user whose sponsor you want to remove.")]
9+
[Alias('ObjectId', 'UPN', 'Identity', 'UserPrincipalName')]
10+
[ValidateNotNullOrEmpty()]
11+
[ValidateScript({
12+
if ($_ -match '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' -or
13+
$_ -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
14+
return $true
15+
}
16+
throw "UserId must be a valid email address or GUID."
17+
})]
918
[System.String] $UserId,
1019

1120
[Alias('DirectoryObjectId')]
1221
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "The User Sponsor ID to be removed.")]
13-
[System.String] $SponsorId
22+
[ValidateNotNullOrEmpty()]
23+
[guid] $SponsorId
1424
)
1525

1626
begin {

0 commit comments

Comments
 (0)