Additionally, apart from the parameters added to a function with the Param block, Windows PowerShell automatically adds Common Parameters. This guide covers the syntax of Powershell Param, types of Powershell Parameters, their attributes, and arguments. It also gives some examples of how to use the Param block to add parameters to a script or function.
Syntax Of A PowerShell Param Block
The syntax of PowerShell Param is… To add a parameter to a function, begin with the word Param, followed by the parameter block, (). Here is a simple form of a param block…
Within the Param block – param () – you will define the Parameter attributes and their arguments. Furthermore, a parameter attribute is enclosed in a [()] block. Within the parameter block, you will define parameter arguments, separated by commas. An example of a PowerShell Param attribute is the parameter attribute. Additionally, an example of a param argument is the mandatory argument. Another example of a param argument is ParameterSetName. Finally, you will define the name of the parameter. Moreover, you will also specify the parameter data type. In the next section, I will discus the common types of PowerShell parameters. Then, section three covers common parameter attributes and their arguments. Finally, in the last section of this guide, I will give a real-life SysAdmin example of a PowerShell Param. The section will also give examples of how to use the param block in an Advanced Function.
Types Of PowerShell Parameters
The most common types of parameters you can set are string or switch parameters. Additionally, you can also define int, bool, DateTime or char parameter types. In this section, I will explain some of these types of parameters. I will also give some examples of how to define them in a param block.
PowerShell Param String Parameter
When you create PowerShell parameters, it is likely that you will create a string parameter. A string parameter accepts any string value. In Windows PowerShell, a string can be numbers, words or characters. Specifically, anything you declare in a double or single quote is a string. In PowerShell, the object type of a string is System.String. To declare a PowerShell parameter as a string parameter, before the name of the parameter, enclose the word string in [] brackets. Here is an example…
PowerShell Param int Parameter
An int data type is a 32-bit signed integer. In English, an int is a number, for example 1, 2 or 3. Unlike a string parameter data type that can take any type of data, an int parameter is very prescriptive. If you define an int parameter, the parameter can only accept numbers. Furthermore, if you enter words as the value for the int parameter, PowerShell will throw an error message. Before I show you how to define a PowerShell Param int parameter, here is a general example of how to define an int data type… If I run the code in PowerShell, it will return 123. On the contrary, if I replace, 123 with “this is an int”, PowerShell will throw an error message. Now that you have had an int data type crash course, to create a PowerShell Param int parameter called number, here is the code… This will force the users of your script or function to provide the right data type.
PowerShell Param DateTime Parameter
Like an int parameter, a DateTime parameter is also very prescriptive of the type of input it accepts. As the name implies, the DateTime parameter will only accept inputs of Date and Time format. If you want to define a PowerShell parameter that will only accept dates, use the sample code below… In this example, EnterDate is the name of the parameter. Additionally, DateTime defines the data type.
PowerShell Param Switch Parameter
In the first three sub-sections of this section, I have discussed PowerShell parameter types that require input from a user. However, there is a PowerShell parameter type that does not require input from a user. Unlike the other types of parameters, a switch parameter does not require user input. The way you define a switch parameter is similar to the way you define other types of parameters. However, in place of switch, int, or datetime, use the word switch. For example to define a PowerShell param Switch parameter, ExportCSV, use the code below… Finally, for this section, you may be wondering about the application of switch parameters. Think of a PowerShell script or function that can display results on the Powershell console. You may also want to give the user the option to either export the result to a text file or a CSV file. One way to code the function is to create 3 switch parameters. A user can then select one of the parameters, depending on how they want the function to deliver the result. This type of parameter does not require the user to enter an input. By simply selecting the parameter, the function will display the output accordingly.
PowerShell Param Parameter Attributes And Arguments
In the PowerShell Param Syntax of this guide, I hinted that a PowerShell parameter has attributes. Moreover, I also pointed out that each parameter attribute also has arguments. In this section, I will be discussing parameter attributes and their arguments. To explain parameter attributes and their arguments, I will be referring to the syntax of PowerShell param introduced in the first section of this guide.
PowerShell Param CmdletBinding Attribute
The CmdletBinding attribute is usually specified before the param block. When you define the CmdletBinding attribute, PowerShell will recognize the script as an advanced function. In the syntax section of this guide, I used this code as a simplified version of a param block. In this section, I will focus on the CmdletBinding Attribute portion of the code. Here is how to define the Attribute… In the next 3 sub-sections, I will discuss some of the common arguments, you can define in the CmdletBinding attribute. For the avoidance of doubt, you must define all Arguments within the () block of the Attribute. Also, you MUST separate all attributes by a comma (,), except the last Arguments within the Attribute.
PowerShell Param DefaultParameterSetName Argument
When you develop a PowerShell function, it can contain multiple parameters that a user can use in the same command. Additionally, the same PowerShell function can contain another set of parameters that a user can use in another command. However, the user cannot mix the parameters in the first set with the parameters in the second set. Furthermore, a function developer defines all parameters that a user can use in the same command with the ParameterSetName argument. The ParameterSetName argument is defined within the Parameter Attribute (more on this in the next section). The implication of having different sets of “grouped” parameters is that you will have different ParameterSetNames. With different ParameterSetNames defied in your param block, you may decide to define one of the ParameterSetNames as the default. This is where you use the DefaultParameterSetName Argument. The DefaultParameterSetName Argument is defined within the CmdletBinding attribute block. Here is an example… Finally, to retain our PowerShell param block format, I will reintroduce the param block below…
PowerShell Param SupportsShouldProcess Argument
This is another argument that you can define in the CmdletBinding Attribute. Like the DefaultParameterSetName Argument, the SupportsShouldProcess Argument is optional. The SupportsShouldProcess Argument adds the Confirm and WhatIf common parameters to the function. To add this argument, add a comma (,) to the end of the DefaultParameterSetName argument. Then, add the line – SupportsShouldProcess=$true or $false. With this new argument included, the CmdletBinding Attribute will now look like this…
PowerShell Param HelpURI Argument
If you are familiar with the PowerShell Get-Help Cmdlet, you may have come across its Online parameter. When you run Get-Help with the Online parameter, PowerShell opens the online help page of the Cmdlet. For example, to open the online help page of the Out-File Cmdlet, run the command below… The page opened by this command is defined in a function by the HelpURI Argument. So, if you want users to access the online help page of your function, define the HelpURI Argument. Here is an example… I will now include this last Argument in the CmdletBinding Attribute. Here is the updated code…
PowerShell Param Parameter Attribute
In the “PowerShell Param CmdletBinding Attribute” sub-section, I discussed 3 arguments that you can include in the CmdletBinding Attribute block. As you have seen, the CmdletBinding Attribute block is the only attribute defined outside the param block. In this sub-section, you will learn about the Parameter Attribute. Additionally, you will also learn about the common Arguments you can add to this Attribute. As you may have deduced from the examples already used in this guide, the Parameter Attribute defines arguments that control the behavior of a PowerShell param parameter. You can define the Parameter Attribute by enclosing the word Parameter, followed by () brackets in a [] block. Here is an example… Moving on, you MUST define all the arguments of the Parameter Attribute within the () block. In the following sub-sections of the “PowerShell Param Parameter Attribute” section, I will introduce and explain the common arguments you can define within the Parameter Attribute.
PowerShell Param ParameterSetName Argument
When I explained DefaultParameterSetName earlier in this guide, I introduced ParameterSetName Argument. You can use this argument to “batch” or “group” parameters that a user can run in the same command. For example, to define a ParameterSetName called ParameterSetName1, enter the code below in the Parameter Attribute () block. When I introduce this updated code, the param block of my sample code will now look this this.. If I bring back the CmdletBinding attribute, my sample PowerShell param code will now look like this…
PowerShell Param Mandatory Argument
You can use the Mandatory argument to define whether a parameter is required or optional. The Mandatory argument accepts a $true or $false value – $true means require, $false, not required. Furthermore, the Mandatory argument is optional. However, if this argument is not defined, the parameter will be treated as optional. To define the Mandatory Argument, add the code below to the Parameter Attribute block… Finally, if I include the Mandatory Argument code to my PowerShell param code, I will now have…
PowerShell Param Position Argument
The Position Argument of the Parameter Attribute defines the position of the parameter. The value is an integer, starting from 0 (zero). The benefit of the Position Argument is to allow users to run the function using the position of the parameters. Specifically, when you define the Position Argument, a user can enter values for each parameter in the command line without specifying the parameter. PowerShell will then assign each value in the command line according to the parameter position. For example, the Get-ChildItem Cmdlet has a parameter called Path (with position 0). The Cmdlet also has another parameter, Filter (with position 1). By default, if I run the Get-ChildItem command, I have to include the parameter names before adding their values. See the command below… In this command, I called the parameters and then specified their values. However, since I know the positions of these 2 parameters, I can add values in their positions, without expressly calling the parameters. I will then modify my command as shown below… Obviously, this saves me time! However, if you are looking at a long PowerShell code, this may cause some confusion. The command gives the same result in PowerShell… PowerShell will automatically assign the values in the positions to the parameters based on their Position Argument. Moving on, here is how you define the Position Argument… I will now add this argument to my sample code…
PowerShell Param ValueFromPipeline Argument
Another commonly used parameter augment is the ValueFromPipeline Argument. As the name implies, this argument determines whether a parameter accepts values from pipeline. Her is how you define this argument… If I add this new argument to my code, it will look like this… There is another argument called ValueFromPipelineByPropertyName. To read about this argument, visit about_Functions_Advanced_Parameters.
PowerShell Param HelpMessage Argument
You can use this argument to specify the message to show users how to use a parameter. To define a HelpMessage Argument for a parameter, use a code similar to the one below… And here is now my updated code… So far in this section, I have discussed 2 PowerShell param attributes – CmdletBinding and Parameter. Additionally, I also discussed the common arguments you can define for these attributes. In the remaining 3 sub-sections of this section, I will teach you 3 more commonly used PowerShell param attributes. However, these 3 attributes do not require you to define arguments.
PowerShell Param Alias Attribute
The alias attribute is used to specify the aliases of a parameter. As you may have guessed, the alias of a PowerShell parameter can be used instead of the parameter. Before I show you how to define the alias attribute for a parameter, let me first show you how to find aliases of all Cmdlets, and Functions on your computer. To list all the aliases for Cmdlets and Functions, run the command below This will list all aliases… Moving on to Alias Attribute, to define one for a PowerShell param parameter, use a code similar to the one below… If I add this to my code, the updated version will look like this…
PowerShell Param SupportsWildcards Attribute
This parameter param attribute determines whether a parameter accepts wildcards. Here is how you define this attribute…
PowerShell Param ValidateNotNullOrEmpty Validation Attribute
Like most attributes already covered in this guide, the name of this attribute also gives it away. It is a validation attribute. When you define this attribute, the parameter will NOT accept a null ($null) value. Additionally, it will not accept an empty (“”) value. If a user enters $null, or “”, the function will throw an error. To define this attribute, enter the code below… Finally, I will update my code with the last 2 attributes…
PowerShell Param Parameter Name
After you have defined all the attributes and arguments of a parameter, you need to add the parameter name. A PowerShell param parameter is defined like a variable – with a dollar sign ($), followed by the name of the parameter. You can also optionally enter a data type for the parameter. In section 2 of this guide, I discussed different types of PowerShell parameters. Here is how you define a parameter that can accept string data type. Here is my updated code example…
How To Define One PowerShell Parameter In Multiple Parameter Sets
If you are new to coding PowerShell functions, chances are that you will fall into the temptation of defining one parameter multiple times. One reason you may want to have a parameter multiple times is when a parameter is used in multiple ParameterSetNames (multiple parameter sets). To drive this home, let’s say you are developing a PowerShell function that has a Path parameter. However, you have 2 ParameterSetNames that require the Path parameter. Most people new to PowerShell scripting will likely define the parameters are shown below… If you define the parameters, as shown above, you will receive an error message. To test this theory, I will copy the code to PowerShell ISE. So, how do you fix this? The solution is to define the 2 parameter attributes and their arguments – including their ParameterSetNames. Then, at the end of both parameter attributes, define a single parameter name that is common to both parameter attributes. In the previous example, I will remove the first parameter name and leave the last one. Now if I copy this code to PowerShell ISE, it will be okay.
PowerShell Param Examples
In this last section of the guide, I will give a real-life SysAdmin PowerShell param example. While I was writing this guide I started developing a PowerShell script/function to get folder size and file count. Here is the param part of the function… In the next few subsections of this section, I will explain the different elements of the param. Finally, the last section introduces a function block and adds the param block into the function. To make it easy for you to follow the lines on the code referenced in the next sub-sections, download PowerShellParamExample.zip. Then, unzip the file and open the .ps1 file in PowerShell ISE.
ParameterSetName PowerShell Param Example
My PowerShell param example code has three ParameterSetNames – DisplayResult, ExportTxt and ExportCSV. I used these names to make it easy to identify what they do. In the introduction of this section, I mentioned that the function I am building with this param code will display folder size and file count for each sub-folder in a specified folder. Therefore, the three ParameterSetNames offer a user the option to display results on the PowerShell console. Alternatively, a user has the option to export the result to a text file or a CSV file. Furthermore, each ParameterSetName define all parameters that a user can call in a single command. Based on this idea, the function I am building will have three command options or syntaxes. I will expand on this idea in the subsequent subsections and examples.
CmdletBinding Attribute And DefaultParameterSetName Argument Examples
In the previous sections of this guide, you came across the CmdletBinding Attribute. Moreover, you also came across one of its arguments – DefaultParameterSetName. The DefaultParameterSetName argument is used to define the default parameter set that a function calls. In this example, the default parameter set name is DisplayResult. The DefaultParameterSetName is declared in line 1 of the code. PowerShell will attempt to use the parameter set declared by the DefaultParameterSetName if it cannot determine which parameter set to use. However, if you set mandatory parameters, you can avoid this problem. In any case, there is no harm with declaring a default parameter set name.
FolderPath String Parameter Example
This is where the fun begins! The FolderPath parameter is used to input the folder path the function will get the size of its sub-folders – and count the number of files in each sub-folder. This is a string parameter. Meaning that it accepts any string as input. One exciting feature of the FolderPath parameter is that it is common to the 3 parameter set names. Earlier in this article, I explained the challenge that new PowerShell script developers may face with this situation. To declare the FolderPath parameter in the three parameter set names, I created three parameter attributes. The first parameter attribute is between lines 5 and 11. Additionally, this first parameter attribute has multiple arguments. However, I will like you to pay particular attention to the ParameterSetName argument – DisplayResult. Secondly, between lines 12 and 18, I declared another parameter attribute with a ParameterSetName argument called ExportTxt. Finally, between lines 19 and 25, I declared a third parameter attribute with a ParameterSetName argument called ExportCSV. Moreover, if you notice, unlike declaring 3 parameter attributes, I declared a single Alias, and ValidateNotNullOrEmpty attributes. These attributes can be found in lines 26 and 27. Finally, just below all the attributes and their arguments, I included the name of the parameter – FolderPath. The parameter name is in line 28.
DisplayResult, ExportTxt And ExportCSV Switch Parameter Example
From line 29 of the param code, I declared another set of parameter attributes and their arguments. Firstly, between lines 29 and 37, I declare the parameter attributes and arguments for the DisplayResult parameter. Then, between lines 38 and 47, I declare another parameter called ExportTxt. Finally, between lines 48 and 57, I declared the ExportCSV parameter. The 3 parameters I have described in this section are all Switch parameters. As you already know, this means that the parameters do not require any input from the user. When a user selects any of the parameter, the function changes the way it displays results.
How To Use PowerShell Param In A PowerShell Function
In this sub-section, I want to introduce the PowerShell function block into my example code.
The syntax of a PowerShell function block is…
For the final example in this guide, I will replace the PowerShell param block within the syntax of the function with my param code from the last sub-section. Additionally, I will replace the function
Testing My PowerShell Parameters In The PowerShell Function
In this final section, I will test the parameters in the function I created in the last section. If you like to test it yourself, you can download the code by clicking this link – Get-FolderSizeFileCount.zip. Then, unzip the zip file. Once you unzip the file, open PowerShell and run the command below: When you run the command, you will receive a warning message. At the message prompt, enter R and press the enter key on your keyboard. Once the module is imported, on the same PowerShell console, run the command below: Here is the result of the command… What I want to show you is the SYNTAX section of the help page of my Function. From the screenshot above, you can run the Get-FolderSizeFileCount command in 3 different commands: The first thing to note is that the three syntaxes have the FolderPath string parameter. If you read through this guide, you will know why. Additionally, you will notice that the first syntax has the DisplayResult switch parameter as well. Finally, in the second and third syntaxes, you have the ExportCSV, and ExportTxt switch parameter respectively. That is it – a comprehensive guide about PowerShell param! I hope you found it helpful? If you found this article helpful, kindly spare 2 minutes to share your experience with our community at Itechguides Community Forum. You could also ask a question, leave a comment or provide feedback regarding the article at Itechguides Community Forum. Our team and other community members will get back to you with a response or answer as soon as possible. Finally, for more PowerShell tech Itechguides, visit our Windows PowerShell How-To guide page. You may also find our Work from Home page very helpful.
