PowerShell Functions Explained: WhatIf, Verbose, and Passing Parameters

In my previous article, I explained how you can use cmdlet binding to enable error handling within a PowerShell function. In this article, I will build on that and introduce some additional things you can do using advanced PowerShell functions.

WhatIf Parameter

Cmdlet bindings let you add “What If” capabilities to your functions. If you haven’t used the WhatIf parameter before, it is a native parameter supported by certain PowerShell cmdlets. When you append -WhatIf to a supported cmdlet, you can see what the cmdlet would do without actually executing it. Integrating this capability into your functions can be tremendously helpful, especially when debugging complex or potentially destructive code.

To demonstrate how the WhatIf parameter works, I have modified the script used in Part 1 of this series. For the sake of simplicity, I have removed the error line and the error handling, but I have included new code related to the WhatIf parameter. Here is the updated script:

Function Do-Something {[Cmdletbinding(SupportsShouldProcess)]Param()If($PSCmdlet.ShouldProcess("Console", "Displaying the text: The Function is Executing")){            Write-Host 'The function is executing'}If($PSCmdlet.ShouldProcess("Console", "Displaying the text: The Function Continues Executing")){            Write-Host 'The function continues executing'}            }#Main BodyWrite-Host 'The main body is executing'Write-Host 'The function is about to be called'Do-Something -WhatifWrite-Host 'The function has ended and the main body is executing once again'

I have made three main changes to the code.

Related:How To Write PowerShell Output to a File

When you use the WhatIf parameter, you must write any lines of code that need to be evaluated as if-then statements. These lines of code essentially tell PowerShell, “If the WhatIf parameter has been specified, then evaluate the code; otherwise, run the code normally”.

In this case, one of the lines in the function checks for the presence of the WhatIf parameter. If the parameter exists, PowerShell displays a message that the function is executing, simulating what would happen without actually performing the action. On the other hand, if the WhatIf parameter has not been specified, the code would simply display the words, “The function is executing,” as it did before.

Let’s put this into perspective with Figures 1 and 2.

PowerShell Advanced 2-1

Figure 1. This shows how the script runs without using the WhatIf parameter.

PowerShell Advanced 2-2

Figure 2. This demonstrates what happens when you include the WhatIf parameter in the function call.

Of course, in real-world scenarios, there is no real benefit to building WhatIf capabilities into a line that merely displays literal text. The true advantage of using WhatIf comes into play when you have lines of code that involve variables. It lets you see how those variables would be used if the code were to be executed. For instance, if my text saying, “The Function is Executing,” were stored in a variable called $Text, the line of code might look like this:

If($PSCmdlet.ShouldProcess("Console", "Displaying the text: '$Text'")){

Verbose Parameter

Cmdlet binding also allows you to include extra output that is shown only when the Verbose parameter is used in the function call.

Looking back at Figure 1, note two lines of text: one indicating that the function is executing and the other saying that the function continues executing. The second line, which was initially meant to demonstrate error handling, is no longer necessary. As such, let’s turn this into verbose text that will be displayed only when the function is called with the Verbose parameter.

Incorporating verbose text is super easy to do. In the code below, you can see that I have reverted the Cmdletbinding line to its original form. Instead of using Write-Host, I changed the line of text to use the Write-Verbose cmdlet. Lastly, I updated the function call to include the Verbose parameter. Here is the script:

Function Do-Something {[Cmdletbinding()]Param()            Write-Host 'The function is executing'            Write-Verbose 'The function continues executing'            }#Main BodyWrite-Host 'The main body is executing'Write-Host 'The function is about to be called'Do-Something -VerboseWrite-Host 'The function has ended and the main body is executing once again'

Figure 3 shows what happens when this script is run without the Verbose parameter, and Figure 4 shows what happens when you include this parameter.

PowerShell Advanced 2-3

Figure 3. The script is running without the Verbose parameter being included in the function call.

PowerShell Advanced 2-4

Figure 4. Adding the Verbose parameter to the function call causes verbose text to be displayed.

Passing a Parameter to a Function

There’s one more thing I would like to demonstrate: how to pass a parameter to a function.

While it is possible to pass multiple parameters, I will focus on a single parameter for the sake of simplicity. Here is the script:

Function Do-Something {[Cmdletbinding()]Param(            [String]$Text            )            Write-Host $Text            }#Main BodyWrite-Host 'The main body is executing'Write-Host 'The function is about to be called'Do-Something -Text "The function is executing"Write-Host 'The function has ended and the main body is executing once again'

If you examine the function call, you will notice that I have appended a parameter called Text, followed by the string, “The function is executing.” Although I have chosen to name the parameter Text, I could have used any other name.

Now let’s look at the function. In the Param section, you will find the line of code that says [String]$Text. This tells PowerShell that the parameter is going to supply string data and that the data should be stored in a variable called $Text. In other words, I am passing the words, “The function is executing,” to the function as a parameter. The function then receives the text, treats it as a string, and stores it in the variable called $Text. Subsequently, the function uses the Write-Host cmdlet to display the contents of the $Text variable. In Figure 5, you can see what the script looks like when it runs.

PowerShell Advanced 2-5

Figure 5. This is the output when the script runs.