The following are naming conventions to keep in mind when coming up with a name for your parameters.
In addition, a recommended list of parameter names can be found here.
From the Strongly Encouraged Development Guidelines:
Your cmdlet should use standard parameter names so that the user can quickly determine what a particular parameter means. If a more specific name is required, use a standard parameter name, and then specify a more specific name as an alias. For example, the
Get-Servicecmdlet has a parameter that has a generic name (Name) and a more specific alias (ServiceName). Both terms can be used to specify the parameter.
Similar to cmdlets, parameters should follow pascal casing. From the Strongly Encouraged Development Guidelines:
Use Pascal case for parameter names. In other words, capitalize the first letter of each word in the parameter name, including the first letter of the name.
We discourage use of acronyms for clarity reasons. Use acronyms with caution.
From the Strongly Encouraged Development Guidelines:
Avoid using plural names for parameters whose value is a single element. This includes parameters that take arrays or lists because the user might supply an array or list with only one element.
Plural parameter names should be used only in those cases where the value of the parameter is always a multiple-element value. In these cases, the cmdlet should verify that multiple elements are supplied, and the cmdlet should display a warning to the user if multiple elements are not supplied.
If there's a separate nomenclature for the parameter name, or if you would like to shorten the name of the parameter so it's easier to remember, you can add an alias attribute to your parameter to allow for this functionality.
The type of parameters should always be defined; a parameter should never be of type object, PSObject, PSCustomObject or the like. Defining a parameter with any of these types can make it difficult for the user to know what value they should be providing to the parameter, and makes it difficult for the breaking change analyzer to detect any breaking changes made to the parameter since it has no knowledge about changes in the types' properties.
From the Strongly Encouraged Development Guidelines:
When the same parameter is used by multiple cmdlets, always use the same parameter type. For example, if the Process parameter is an Int16 type for one cmdlet, do not make the Process parameter for another cmdlet a UInt16 type.
For parameters that require a collection of elements to be provided, use an array instead of any other enumerable type to represent this collection.
From the Strongly Encouraged Development Guidelines:
Frequently, users must perform the same operation against multiple arguments. For these users, a cmdlet should accept an array as parameter input so that a user can pass the arguments into the parameter as a Windows PowerShell variable. For example, the
Get-Processcmdlet uses an array for the strings that identify the names of the processes to retrieve.
For parameters whose type is string and which represent a value that should be kept secret (such as a password, secret, key, etc.), the type of the parameter should be SecureString to limit the exposure of sensitive string data from unexpected leakage during cmdlet execution. The practice also applies to output properties whose type is string and that should be kept in secret.
Notice that DO NOT use SecureString for encryption purposes. We only recommend using SecureString as a wrapper of string to prevent unexpected leakage of information as string may still be exposed to any process or operation that has access to raw memory.
From How secure is SecureString?
SecureString is more secure than String because it limits the exposure of sensitive string data. However, those strings may still be exposed to any process or operation that has access to raw memory, such as a malicious process running on the host computer, a process dump, or a user-viewable swap file. Instead of using SecureString to protect passwords, the recommended alternative is to use an opaque handle to credentials that are stored outside of the process.
Parameters of type bool are strongly discouraged in PowerShell. The SwitchParameter type of a parameter acts a flag that signals whether or not some action should be taken based on if the parameter was provided or not.
The only case where a bool parameter should be used to is for a PATCH operation wrapped by an Update-* cmdlet; in this case, the user can set the value to true or false, or not provide a value at all, which keeps the value the same on the server. For a PUT operation wrapped by a Set-* cmdlet, the normal SwitchParameter type should be used.
The following are naming conventions to keep in mind when coming up with a name for your parameter set.
Similar to parameters (mentioned above), parameter set names should follow pascal casing. From the Strongly Encouraged Development Guidelines:
Use Pascal case for cmdlet names. In other words, capitalize the first letter of the verb and all terms used in the noun. For example, "Remove-EntraUserManager".
The following are guidelines that should be followed when working with the attributes of a parameter set.
For PowerShell to determine which parameter set a user is intending to use with a set of provided parameters, the parameter sets need to be designed in such a way that they're mutually exclusive. From the remarks section of Parameter Attribute Declaration:
Each parameter set must have at least one unique parameter. Good cmdlet design indicates this unique parameter should also be mandatory if possible. If your cmdlet is designed to be run without parameters, the unique parameter cannot be mandatory.
It's possible to call a PowerShell cmdlet without providing the parameter names, but just the values you would like to pass through. This is done by specifying the position at which the value of each parameter should be provided by using the Position property for a parameter. However, when there are too many positional parameters in a single parameter set, it can be difficult for the user to remember the exact ordering in which the parameter values should be provided. From the remarks section of Parameter Attribute Declaration:
When you specify positional parameters, limit the number of positional parameters in a parameter set to less than five. And, positional parameters do not have to be contiguous. Positions 5, 100, and 250 work the same as positions 0, 1, and 2.
In addition, there should be no two parameters with the same position in the same parameter set. From the remarks section of Parameter Attribute Declaration:
No parameter set should contain more than one positional parameter with the same position.
Allowing the user to pipe an object from one cmdlet to another is a major scenario in PowerShell, but allowing multiple parameters in the same parameter set to accept their value from the pipeline can cause issues. From the remarks section of Parameter Attribute Declaration:
Only one parameter in a parameter set should declare ValueFromPipeline = true. Multiple parameters can define ValueFromPipelineByPropertyName = true.
In PowerShell documentation, square brackets ([]) indicate optional.
Convention is as follows:
command-name
-RequiredParameterName <RequiredParameterValue>
[-OptionalParameterName <OptionalParameterValue>]
[-OptionalSwitchParameters]
[-OptionalParameterName] <RequiredParameterValue>Using New-Alias cmdlet as an example:
New-Alias
-Name <string> -required 'positional' parameter
[-Value] <string>
[-Description <string>] -optional parameter
[-Force] -optional switch parameter (all switch parameters are optional, non-positional)
[-Option {None | ReadOnly | Constant | Private | AllScope}]
[-PassThru]
[-Scope <string>]
[-Confirm]
[-WhatIf]
[<CommonParameters>]