Every once and a while, a good mystery can be fun. For IT Professionals taking a class, not so much. During my last PowerShell class, one of my students made an observation in a help file. The Cmdlet in question was Set-ADUser. Take a look at the help information on these two parameters.
-Identity <ADUser>
Specifies an Active Directory user object by providing one of the following property values. The identifier in parentheses is the LDAP display name for the attribute. The acceptable values for this parameter are:
-- A Distinguished Name
-- A GUID (objectGUID)
-- A Security Identifier (objectSid)
-- A SAM Account Name (sAMAccountName)
Required? true
Position? 1
Default value
Accept pipeline input? True (ByValue)
Accept wildcard characters? false
-Identity <ADUser>
Specifies an Active Directory user object by providing one of the following property values. The identifier in parentheses is the LDAP display name for the attribute. The acceptable values for this parameter are:
-- A Distinguished Name
-- A GUID (objectGUID)
-- A Security Identifier (objectSid)
-- A SAM Account Name (sAMAccountName)
Required? true
Position? 1
Default value
Accept pipeline input? True (ByValue)
Accept wildcard characters? false
Notice how both are “required” but we do not have to use both of them. There is our mystery. This behavior is because they are in different parameters sets. A parameter set is created when the author of the cmdlet adds functionality in which some of the parameters cannot be used at the same time as other parameters. If you use a parameter that is in a parameter set other than the default set, then all the parameters that are not part of the new set are filtered out of TAB completion and the ISE intellisense. The problem is that the help files do not make note of which parameter set these parameters are a part of. I decided to play around a little bit and create a cmdlet that uncovers this mystery.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | Function Get-RequiredParameters { Param ( $Cmdlet ) # Get all the parameters from the source. $Sets = Get-help $Cmdlet -full | Select -ExpandProperty Syntax | Select -ExpandProperty SyntaxItem
# Create the object template for the output. $Object = New-Object -TypeName PSObject -Property @{ Set = $Null Parameter = $Null Required = $False }
# Get the Parameter Sets from the Source $CMD = Get-Command -Name $Cmdlet $SetNames = $Cmd.ParameterSets.Name
# Used to cycle through the Parameter sets # whiel creating the output. $Index = 0
ForEach ($Set in $Sets) {
$Items = $Set
ForEach ($Item in $Items) {
ForEach ($P in $Item.Parameter) { $Obj = $Object $Obj.Set = $SetNames[$Index] $Obj.Parameter = $P.Name $Obj.Required = $P.Required
Write-Output $Obj
} $Index++ } } <# .SYNOPSIS Displays all parameter Sets and the required parameters of a Cmdlet
.DESCRIPTION Displays all parameter Sets and the required parameters of a Cmdlet. This will help to clear up any confusion as to why a help files says that a parameter is required, when it may not be.
.PARAMETER Cmdlet The name of the cmdlet (or script) that you want to view the parameter information from.
.Example Get-RequiredParameters -Cmdlet Measure-object Parameter Required Set --------- -------- --- Property false GenericMeasure Average false GenericMeasure InformationAction false GenericMeasure InformationVariable false GenericMeasure InputObject false GenericMeasure Maximum false GenericMeasure Minimum false GenericMeasure Sum false GenericMeasure Property false TextMeasure Character false TextMeasure IgnoreWhiteSpace false TextMeasure InformationAction false TextMeasure InformationVariable false TextMeasure InputObject false TextMeasure Line false TextMeasure Word false TextMeasure
Displays the parameter information for each parameter set of Measure-Object
.Example Get-RequiredParameters -Cmdlet Set-ADUser | where Required -eq $True Parameter Required Set --------- -------- --- Identity true Identity Instance true Instance
Displays only the parameters that are required in each parameter set,
.NOTES =============================================================================== == Cmdlet: Get-RequiredParameters == == Author: Jason A. Yoder == == Company: MCTExpert of Arizona == == Date: December 3, 2015 == == Copyright: All rights reserved. == == Version: 1.0.0.0 == == Legal: The user assumes all responsibility and liability for the usage of == == this PowerShell code. MCTExpert of Arizona, Its officers, shareholders, == == owners, and their relatives are not liable for any damages. As with all == == code, review it and understand it prior to usage. It is recommended that == == this code be fully tested and validated in a test environment prior to == == usage in a production environment. == == == == Does this code make changes: NO == =============================================================================== #> } |
Comments