Designing Cmdlets That Have Lots of Parameters
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
Light
Dark
0 comments