Advanced Windows PowerShell Scripting Video Training

Advanced Windows PowerShell Scripting Video Training
Advanced Windows PowerShell Scripting Video Training

Friday, December 4, 2015

Finding the Required Parameters in Parameter Sets

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                                           ==

===============================================================================

#>

}

No comments: