Designing Cmdlets That Have Lots of Parameters

Designing Cmdlets That Have Lots of Parameters

Rate This
  • Comments 2

We often get the question of what to do about a cmdlet that has lots of parameters.  Do you break it up into multiple commands or just have a single cmdlet with lots of parameters.  Here is the way I think about it:

If you have to enter 100 things to get a job done, it doesn’t really matter whether you enter those 100 things via 1 cmdlet with 100 parameters or 10 cmdlets with 10 parameters each.  If anything, there are a number of good reasons to have 1 cmdlet with 100 parameters including the fact that you don’t have to enter 10 cmdlets and you produce an abstraction which is much more friendly to being exposed as a REST API.

Let me be quick to point out the trick – that is all about if you have to enter 100 things to do something.  Most often that is not the situation we find ourselves in.  Often is the case that you can specify 100 things but 80% of the scenarios are handled by 20 parameters.  That is a very different situation.  Let’s look at New-PSSession for an example.  New-PSSession takes a number (14) of useful parameters like –ComputerName, –Port, –Credential, –UseSSL etc.  It also takes a parameters called –SessionOption.  Let’s look at that:

PS> Get-Help New-PSSession -Parameter SessionOption

-SessionOption <PSSessionOption>
    Sets advanced options for the session.  Enter a SessionOption object that y
    ou create by using the New-PSSessionOption cmdlet.

    The default values for the options are determined by the value of the $PSSe
    ssionOption preference variable, if it is set. Otherwise, the session uses
    the system defaults.

    For a description of the session options, including the default values, see
     New-PSSessionOption. For information about the $PSSessionOption preference
     variable, see about_Preference_Variables.

    Required?                    false
    Position?                    named
    Default value
    Accept pipeline input?       false
    Accept wildcard characters?  false

 

So the way you get an object to pass to –SessionOption is by calling the New-PSSessionOption cmdlet.  That cmdlet takes 20 parameters!  So why not just put those parameters on New-PSSession?  Well, if you did that then when you looked at the help for New-PSSession, it would have 34 parameters that you’d have to read through and when you did tab-completion, you’d cycle through 34 values instead of 14. 

We put the parameters that we felt would cover 80% of the scenarios in New-PSSession and then put the rest of the parameters in New-PSSesssionOption.  (In all honesty I think there are a few parameters in New-PSSession that belong in New-PSSessionOption.).

I consider this to be a best practice because it makes it easier for admins to learn the cmdlets while still being able to cover the full range of functions.

NOTE – for reasons that will become apparent in the future, it is critical that the object that contains the  extra parameters have a NULL-CONSTRUCTOR which initializes the object with the default values.  Don’t bother trying to get a sneak preview of the future by asking me to explain what will happen in the future – just take my word for it – objects will Null-Constructors are good things.

That ends the blog but I’ve included the help for the parameters of New-PSSessionOption below for those people who are interested.

Enjoy!

Jeffrey Snover [MSFT]
Distinguished Engineer

PS> Get-Help New-PSSessionOption -Parameter *


-ApplicationArguments <PSPrimitiveDictionary>
    Specifies a hash table that is sent directly to the session configuration w
    ithout interpretation. This hash table is available to the session configur
    ation as a property of the PSSenderInfo class.
   
    Required?                    false
    Position?                    named
    Default value               
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-CancelTimeOut <int>
    Determines how long Windows PowerShell waits for a cancel operation (CTRL +
     C)  to complete before terminating it. Enter a value in milliseconds.
   
    The default value is 60000 (one minute). A value of 0 (zero) means no timeo
    ut; the command continues indefinitely.
   
    Required?                    false
    Position?                    named
    Default value                60000
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-Culture <CultureInfo>
    Specifies the culture to use for the PSSession. Enter a culture name in <la
    nguagecode2>-<country/regioncode2> format, such as "ja-jP",  a variable tha
    t contains a CultureInfo object, or a command that gets a CultureInfo objec
    t, such as "get-culture".
   
    The default value is $null, and the culture that is set in the operating sy
    stem when the PSSession is created is used in the PSSession.
   
    Required?                    false
    Position?                    named
    Default value                Current culture
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-IdleTimeOut <int>
    Determines how long the PSSession stays open if the remote computer does no
    t receive any communication from the local computer, including the heartbea
    t signal. When the interval expires, the PSSession closes.
   
    Enter a value in milliseconds. The default value is 240000 (4 minutes). The
     minimum value is 60000 (1 minute).
   
    If both the local and remote computers specify an idle timeout value, the P
    SSession uses the shorter timeout value. The local computer can set an idle
     timeout value by using this parameter or by setting an idle timeout in the
     $PSSessionOption preference variable. The remote computer can specify an i
    dle timeout value in the WS-Management configuration (WSMAN:\localhost\shel
    l\idletimeout).
   
    Required?                    false
    Position?                    named
    Default value                240000
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-MaximumReceivedDataSizePerCommand <int>
    Specifies the maximum number of bytes that the local computer can receive f
    rom the remote computer in a single command. Enter a value in bytes. By def
    ault, there is no data size limit.
   
    This option is designed to protect the resources on the client computer.
   
    Required?                    false
    Position?                    named
    Default value                No limit
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-MaximumReceivedObjectSize <int>
    Specifies the maximum size of an object that the local computer can receive
     from the remote computer. Enter a value in bytes. By default, there is no
    data size limit.
   
    This option is designed to protect the resources on the client computer.
   
    Required?                    false
    Position?                    named
    Default value                No limit
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-MaximumRedirection <int>
    Determines how many times Windows PowerShell redirects a connection to an a
    lternate Uniform Resource Identifier (URI) before the connection fails. The
     default value is 5. A value of 0 (zero) prevents all redirection.
   
    This option is used in the PSSession only when the AllowRedirection paramet
    er is used in the command that creates the PSSession.
   
    Required?                    false
    Position?                    named
    Default value                5
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-NoCompression [<SwitchParameter>]
    Turns off packet compression in the PSSession. Compression uses more proces
    sor cycles, but it makes transmission faster.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-NoEncryption [<SwitchParameter>]
    Turns off data encryption.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-NoMachineProfile [<SwitchParameter>]
    Prevents loading the user's Windows user profile. As a result, the PSSessio
    n might be created faster, but user-specific registry settings, items such
    as environment variables, and certificates are not available in the PSSessi
    on.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-OpenTimeOut <int>
    Determines how long the client computer waits for the session connection to
     be established. When the interval expires, the command to establish the co
    nnection fails. Enter a value in milliseconds.
   
    The default value is 180000 (3 minutes). A value of 0 (zero) means no time-
    out; the command continues indefinitely.
   
    Required?                    false
    Position?                    named
    Default value                180000
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-OperationTimeOut <int>
    Determines the maximum time that any operation in the PSSession can run. Wh
    en the interval expires, the operation fails. Enter a value in milliseconds
    .
   
    The default value is 180000 (3 minutes). A value of 0 (zero) means no time-
    out; the operation continues indefinitely.
   
    Required?                    false
    Position?                    named
    Default value                180000
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-ProxyAccessType <ProxyAccessType>
    Determines which mechanism is used to resolve the host name. Valid values a
    re IEConfig, WinHttpConfig, AutoDetect, NoProxyServer and None. The default
     value is None.
   
    For information about the values of this parameter, see the description of
    the System.Management.Automation.Remoting.ProxyAccessType enumeration in th
    e MSDN (Microsoft Developer Network) Library at <a href="http://go.microsoft.com/fwl">http://go.microsoft.com/fwl</a>
    ink/?LinkId=144756.
   
    Required?                    false
    Position?                    named
    Default value                None
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-ProxyAuthentication <AuthenticationMechanism>
    Specifies the authentication method that is used for proxy resolution. Vali
    d values are Basic, Digest, and Negotiate. The default value is Negotiate.
   
    For information about the values of this parameter, see the description of
    the System.Management.Automation.Runspaces.AuthenticationMechanism enumerat
    ion in the MSDN library at <a href="http://go.microsoft.com/fwlink/?LinkID=144382">http://go.microsoft.com/fwlink/?LinkID=144382</a>.
   
    Required?                    false
    Position?                    named
    Default value                Negotiate
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-ProxyCredential <PSCredential>
    Specifies the credentials to use for proxy authentication. Enter a variable
     that contains a PSCredential object or a command that gets a PSCredential
    object, such as Get-Credential. If this option is not set, no credentials a
    re specified.
   
    Required?                    false
    Position?                    named
    Default value                None
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-SkipCACheck [<SwitchParameter>]
    Specifies that when connecting over HTTPS, the client does not validate tha
    t the server certificate is signed by a trusted certificate authority (CA).
    
   
    Use this option only when the remote computer is trusted by using another m
    echanism, such as when the remote computer is part of a network that is phy
    sically secure and isolated, or the remote computer is listed as a trusted
    host in a WinRM configuration.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-SkipCNCheck [<SwitchParameter>]
    Specifies that the certificate common name (CN) of the server does not need
     to match the hostname of the server. This option is used only in remote op
    erations that use the HTTPS protocol.
   
    Use this option only for trusted computers.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-SkipRevocationCheck [<SwitchParameter>]
    Does not validate the revocation status of the server certificate.
   
    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-UICulture <CultureInfo>
    Specifies the UI culture to use for the PSSession.
   
    Enter a culture name in <languagecode2>-<country/regioncode2> format, such
    as "ja-jP",  a variable that contains a CultureInfo object, or a command th
    at gets a CultureInfo object, such as Get-Culture.
   
    The default value is $null, and the UI culture that is set in the operating
     system when the PSSession is created is used in the PSSession.
   
    Required?                    false
    Position?                    named
    Default value                Current UI culture
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-UseUTF16 [<SwitchParameter>]
    Encode the request in UTF16 format rather than UTF8 format.
   
    Required?                    false
    Position?                    named
    Default value                False (UTF8 encoding)
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

Leave a Comment
  • Please add 8 and 2 and type the answer here:
  • Post
  • I fully agree, that is a rock solid best practice.

    Just wondering if parametersets could/should play along ?

  • AWESOME!!!

    uh...what is this about?

Page 1 of 1 (2 items)