Fun With PowerShell Write-Verbose

Introduction

In my previous post, Fun With the PowerShell Switch Parameter, I introduced the use of switches with PowerShell functions. We learned how they work, and how to create your own. For all functions, PowerShell creates a set of switches that are just “built in” to PowerShell. You do not have to explicitly create these yourself, you can simply use them and implement them within your own functions.

Two of the most used are -Verbose and -Debug. When used with the Write-Verbose and Write-Debug cmdlets they will display informational messages to the user of your functions. In this post, we’ll focus on the Verbose switch. The next post in the series will examine the Debug switch.

We’ll take a deeper look at Verbose in a moment, but first let me mention that for all of the examples, we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.1.4, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.

Write-Verbose

Messages displayed using the -Verbose switch are intended for the users. It can advise a user of long running processes, or let the user know a function is indeed being executed. Let’s take a look at a function we’ll use for this demo.

function Show-FileInfo ()
{
  [CmdletBinding()]
  param ( [Parameter (ValueFromPipeline)]
          $file
        )

  process
  {
    $retVal = "$($file.Name) is {0:N0} bytes long." -f $file.Length
    $retVal
  }

}

The purpose of this function is to take a stream of files from the pipeline, then display the file name and the file size. It’s extremely simple but will serve for this blog post. If you need more info on how pipelined functions work, please see my recent post Fun With PowerShell Pipelined Functions. That post will explain the structure of the function, including the begin, process and end blocks.

Let’s run this function. First, highlight the function and execute it to get it in memory. Then let’s call the function.

Get-ChildItem | Show-FileInfo

Result:

01 - Cmdlets.ps1 is 3,732 bytes long.
02 - Providers.ps1 is 1,819 bytes long.
03 - Variables.ps1 is 4,717 bytes long.
04 - Strings.ps1 is 7,970 bytes long.
05 - Arrays and Hashtables.ps1 is 8,486 bytes long.
06 - Logic Branching and Looping.ps1 is 4,315 bytes long.
07 - Functions.ps1 is 9,574 bytes long.
08 - Classes.ps1 is 6,210 bytes long.
09 - Examples.ps1 is 3,125 bytes long.
Company.csv is 9,694 bytes long.
Company.json is 19,479 bytes long.
ReadMe.md is 1,115 bytes long.

So far so good, you can see the files I have in my current folder (obviously your list of files will vary). Now let’s say we want to let the user know when the function starts and ends, so the user can get an idea of how long it will take to execute. Most of the time our function runs in an automated fashion so we don’t need this, however there may be times when a user wants to manually run it so they can get execution times.

We can modify our function to use the Write-Verbose cmdlet to display this message when the built in -Verbose switch is used. First, we’ll add a begin block to our function to show the start time.

begin
  {
    $fn = "$($PSCmdlet.MyInvocation.MyCommand.Name)"
    $st = Get-Date
    Write-Verbose @"
  `r`n  Function: $fn
  Starting at $($st.ToString('yyyy-MM-dd hh:mm:ss tt'))
"@
  }

The first thing we do is get the function name. PowerShell has a built in variable called $PSCmdlet which has information about the code currently being executed. It has an object property called MyInvocation, which has an object property named MyCommand. This has a property called Name which holds the name of the function currently being executed.

While this seems a bit more complicated than just keying in $fn = 'Show-FileName', it actually leverages code reuse. I can paste this into any function and continue, without the need to update anything.

Next I capture the current date and time into a variable called $st, short for start time.

The call to Write-Verbose comes next. By default, when a Write-Verbose is executed, it displayes the text VERBOSE: followed by the message, such as:

VERBOSE: Your Message Here

In my example though I want to display a multi line message. The first line will hold the name of the function, the second will be the start time. To accomplish this I am using a here string. If you aren’t familiar with here strings, see my post from July 12, 2021 named Fun With PowerShell Strings.

In the here string I start with the characters `r`n. This will send a carriage return – line feed to the here string, so the VERBOSE: will appear on a line by itself. I then add two spaces so the line with the function name will be indented two spaces. Not necessary, but I think it makes it more readable.

The next line is the starting time, also indented two spaces. Here I take the start time and convert it to a string. Into the ToString function I pass in a date format string to display the current date and time. This will produce year-month-day hour:minute:second, with the tt becoming AM or PM. Finally I close out the here string as well as the process block.

As is, this code could be copy and pasted into any function without modification, ready to use. You could even go so far as to make it a snippet in VSCode, I have a project on GitHub, VSCode_User_Snippets that explains how to create user snippets in VSCode. It was written to target implementing MarkDown snippets, but I also included my default PowerShell snippets. Note that the PowerShell IDE used with PowerShell 5.1 also allows for reusable code snippets.

OK, we’ve handled the message we want to show when the function starts. Now we’ll add an end block to display the ending time.

end
  {
    $et = Get-Date
    Write-Verbose @"
  `r`n  Function: $fn
  Finished at $($et.ToString('yyyy-MM-dd hh:mm:ss tt'))
"@
  }

Since I already had the function name in the $fn variable I didn’t have to get it again. I just grab the current time into the variable $et (for end time) and display it as I did in the opening.

For reference here is the function again with the new blocks added.

function Show-FileInfo ()
{
  [CmdletBinding()]
  param ( [Parameter (ValueFromPipeline)]
          $file
        )

  begin
  {
    $fn = "$($PSCmdlet.MyInvocation.MyCommand.Name)"
    $st = Get-Date
    Write-Verbose @"
  `r`n  Function: $fn
  Starting at $($st.ToString('yyyy-MM-dd hh:mm:ss tt'))
"@
  }

  process
  {
    $retVal = "$($file.Name) is {0:N0} bytes long." -f $file.Length
    $retVal
  }

  end
  {
    $et = Get-Date
    Write-Verbose @"
  `r`n  Function: $fn
  Finished at $($et.ToString('yyyy-MM-dd hh:mm:ss tt'))
"@
  }
}

If I run this, you'll see I get the exact same results I did the first time.

Get-ChildItem | Show-FileInfo

Result:

01 - Cmdlets.ps1 is 3,732 bytes long.
02 - Providers.ps1 is 1,819 bytes long.
03 - Variables.ps1 is 4,717 bytes long.
04 - Strings.ps1 is 7,970 bytes long.
05 - Arrays and Hashtables.ps1 is 8,486 bytes long.
06 - Logic Branching and Looping.ps1 is 4,315 bytes long.
07 - Functions.ps1 is 9,574 bytes long.
08 - Classes.ps1 is 6,210 bytes long.
09 - Examples.ps1 is 3,125 bytes long.
Company.csv is 9,694 bytes long.
Company.json is 19,479 bytes long.
ReadMe.md is 1,115 bytes long.

So how do I get the verbose messages to display? Well all I have to do is add the -Verbose switch to the call.

Get-ChildItem | Show-FileInfo -Verbose

Result:

VERBOSE:   
  Function: Show-FileInfo
  Starting at 2021-08-15 07:28:26 PM
01 - Cmdlets.ps1 is 3,732 bytes long.
02 - Providers.ps1 is 1,819 bytes long.
03 - Variables.ps1 is 4,717 bytes long.
04 - Strings.ps1 is 7,970 bytes long.
05 - Arrays and Hashtables.ps1 is 8,486 bytes long.
06 - Logic Branching and Looping.ps1 is 4,315 bytes long.
07 - Functions.ps1 is 9,574 bytes long.
08 - Classes.ps1 is 6,210 bytes long.
09 - Examples.ps1 is 3,125 bytes long.
Company.csv is 9,694 bytes long.
Company.json is 19,479 bytes long.
ReadMe.md is 1,115 bytes long.
VERBOSE:   
  Function: Show-FileInfo
  Finished at 2021-08-15 07:28:26 PM

Simply by adding the -Verbose switch, it now displays the text passed into any Write-Verbose cmdlets you coded. If you look at our param block, you won’t see the Verbose switch declared, as we had to in the previous article Fun With the PowerShell Switch Parameter.

PowerShell automatically adds the Verbose switch to every advanced function you author. You don’t have to do anything special. If PowerShell sees you’ve added the switch when you (or a user) runs your function, it will automatically execute any Write-Verbose cmdlets for you.

Taking It to the Next Level

As is, this function requires our user to manually calculate the run time by comparing the start and end times. But PowerShell developers are a courteous bunch, and so we’ll take care of this for them.

Let’s update the end block to perform the calculation.

  end
  {
    $et = Get-Date

    $rt = $et - $st  # Run Time

    # Format the output time
    if ($rt.TotalSeconds -lt 1)
      { $elapsed = "$($rt.TotalMilliseconds.ToString('#,0.0000')) Milliseconds" }
    elseif ($rt.TotalSeconds -gt 60)
      { $elapsed = "$($rt.TotalMinutes.ToString('#,0.0000')) Minutes" }
    else
      { $elapsed = "$($rt.TotalSeconds.ToString('#,0.0000')) Seconds" }


    Write-Verbose @"
  `r`n  Function: $fn
  Finished at $($et.ToString('yyyy-MM-dd hh:mm:ss tt'))
  Elapsed Time $elapsed
"@
  }

After getting my end time, I subtract the start time from the end time, and place it in the $rt variable, short for run time. This will produce a variable that is a datetime datatype.

A PowerShell datetime datatype has some very useful methods. The first we’ll use is TotalSeconds, which indicates how many seconds are in our variable. In the if statement, check to see if the run time seconds is less than 1. If so, it uses another property TotalMilliseconds that (obviously) returns the total number of milliseconds in the run time variable. It converts it to a string, and we pass in a string format so we get a nice output. Finally it appends the text Milliseconds so the user will now what time unit they are dealing with, and places it all in a variable $elapsed.

The elseif is similar. If the total seconds exceeds 60, we’ll display the run time in minutes. The else script block covers the case when the elapsed time is between 1 and 60 seconds.

Finally we add a third line to the here string passed into Write-Verbose.

Highlight the entire function and execute it so the new version is in memory. Then call the function using the Verbose switch.

Get-ChildItem | Show-FileInfo -Verbose

Result:

VERBOSE:   
  Function: Show-FileInfo
  Starting at 2021-08-15 07:59:39 PM
01 - Cmdlets.ps1 is 3,732 bytes long.
02 - Providers.ps1 is 1,819 bytes long.
03 - Variables.ps1 is 4,717 bytes long.
04 - Strings.ps1 is 7,970 bytes long.
05 - Arrays and Hashtables.ps1 is 8,486 bytes long.
06 - Logic Branching and Looping.ps1 is 4,315 bytes long.
07 - Functions.ps1 is 9,977 bytes long.
08 - Classes.ps1 is 6,210 bytes long.
09 - Examples.ps1 is 3,125 bytes long.
Company.csv is 9,694 bytes long.
Company.json is 19,479 bytes long.
ReadMe.md is 1,115 bytes long.
VERBOSE:   
  Function: Show-FileInfo
  Finished at 2021-08-15 07:59:39 PM
  Elapsed Time 19.9018 Milliseconds

As you can see, these few extra lines of code provides a more professional looking output, not to mention accurate. The user will not be forced to manually calculate times.

And don’t forget you can place these into code snippets for fast and easy use. As constructed both the opening and closing sections can simply be inserted without modification. Again, see my GitHub project, VSCode_User_Snippets for examples on using code snippets in Visual Studio Code.

Conclusion

In this post we saw how the built in -Verbose switch works along with the companion Write-Verbose. This can provide a useful tool to keep users appraised of extra, “meta” information such as run times without obscuring the output of the function when it is used in normal circumstances.

In the next blog post we’ll look at the counterpart for verbose, -Debug and it’s Write-Debug cmdlet.

If you want to learn more about PowerShell, check out my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight . At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.

Fun With the PowerShell Switch Parameter

Introduction

Over the last few posts I’ve been covering PowerShell functions, both Basic Functions and Advanced Functions. In this post I had originally intended to cover two switches available to all advanced functions, Verbose and Debug.

But then it occurred to me, not everyone may know what a switch parameter is. And to be clear, I’m not talking about the switch statement. I covered that in my post Fun With PowerShell Logic and Branching.

Here, I’m talking about the ability to use what PowerShell calls a switch parameter.

We’ll take a deeper look in a moment, but first let me mention that for all of the examples, we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.1.3, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.

A Simple Switch Example

If you’ve been following my series, you know that you can pass in values, in other words parameters, to a function by name. For example:

Get-AValue -one 33 -two 42

-one and -two were the parameter names, and 33 and 42 the values passed in for them.

A switch is similar, you list the name of the switch on call to the function, but unlike a regular parameter you pass in no value. The presence of the switch is enough to tell the function what you want to do.

Let’s look at an example using the common Write-Host cmdlet.

Write-Host 'Hi Mom' -NoNewline -ForegroundColor Green
Write-Host ' and Dad' -ForegroundColor Yellow

Result:
Hi Mom and Dad Image

Normally, Write-Host displays its text, then automatically moves the cursor to the next line. However, Write-Host has a -NoNewLine switch. Including the switch will keep Write-Host from adding the line feed at the end, and allows us do fun things like having two different colors of text on the same line.

Note that we didn’t have to pass in any value, didn’t have to set it to true or false. Just including the switch was enough to say “hey don’t wrap to a new line”.

Implementing Your Own Switches

Switches wouldn’t be any fun if we couldn’t use them too! And it’s actually quite easy. I started off the whole PowerShell series on my blog with a post Fun With PowerShell Get-Random. In it I described (among other things) how to use the Get-Random cmdlet to return a random value from an array. We’ll borrow on that idea for this function.

function Get-RandomSouthAmericanCountry()
{
[CmdletBinding()]
param(
[switch] $UpperCase
)

$array = (
'Argentina', 'Bolivia', 'Brazil',
'Chile', 'Columbia', 'Ecuador',
'Guyana', 'Paraguay', 'Peru',
'Suriname', 'Uruguay', 'Venezuela'
)

# Get an item from the array and convert from
# a generic object to a string
$retVal = $($array | Get-Random).ToString()

# If user passed in upper case switch,
# upper case return value
if ($UpperCase.IsPresent)
{
$retVal = $retVal.ToUpper()
}

return $retVal

}

I’ll give a shout of sorts to my wonderful geek friends who live on the South American continent with this example, our Get-RandomSouthAmericanCountry function. Of course we start with [CmdletBinding()] to indicate this is an advanced function. Then we have our param block.

param(
[switch] $UpperCase
)

We have one parameter named $UpperCase. But instead of having a traditional data type in front, we have [switch]. This will indicate to PowerShell that $UpperCase is a switch. We’ll see how to use it within our code in a moment, but first let’s take a quick look at the rest of the function.

After the param block we have an array which lists the countries in South America (according to the countries of the world website I found).

I then fall to this line to get the country:

$retVal = $($array | Get-Random).ToString()

First, I use $array | Get-Random to get a random country. This will return an element from the array, but I need it to be a datatype of string rather than a generic object. So I wrap the result of Get-Random in $( ) to make PowerShell evaluate it as an object. Then I can call the .ToString() method of the object to convert it to a string. Finally it gets assigned to my return variable, $retVal.

The next part is where I look to see if my switch was used.

if ($UpperCase.IsPresent)
{
$retVal = $retVal.ToUpper()
}

Here, you use the name of the switch and access its .IsPresent property. This returns $true if the switch was passed in. Thus if it was passed in, the if statement will take affect and call the .ToUpper() method on our $retVal string. This is why we had to convert to a string, string data types have a .ToUpper() method, generic objects don’t.

As the final step we return the value held in $retVal, which sticks to the rule of having one exit point for a function.

After highlighting the function and running it using F8/F5 to get it in memory, we’ll call it. First, we’ll so so using it without the switch.

Get-RandomSouthAmericanCountry

Result:
Venezuela

Great, now let’s call it with our switch.

Get-RandomSouthAmericanCountry -UpperCase

Result:
URUGUAY

In this call, just including the switch caused the output to display in upper case.

Switches Work with Basic Functions Too

In the above example I used an advanced function. Be aware that if you are using a basic function, as I described in a previous article, you can still use a switch.

Here is the previous example rewritten as a basic function. (Note the function declaration should all be on one line, the blog layout will probably wrap it.)

function Get-RandomSouthAmericanCountryBasic([switch] $UpperCase)
{
$array = (
'Argentina', 'Bolivia', 'Brazil',
'Chile', 'Columbia', 'Ecuador',
'Guyana', 'Paraguay', 'Peru',
'Suriname', 'Uruguay', 'Venezuela'
)

# Get an item from the array and convert from
# a generic object to a string
$retVal = $($array | Get-Random).ToString()

# If user passed in upper case switch,
# upper case return value
if ($UpperCase.IsPresent)
{
$retVal = $retVal.ToUpper()
}

return $retVal

}

The only real difference is the removal of the [CmdletBinding()} statement and the param block. I then declared the [switch] $UpperCase inside the parenthesis like you would do with a basic function.

By the way, like most things in PowerShell casing isn’t important. These are all the same to PowerShell:

[switch] $UpperCase
[SWITCH] $UpperCase
[Switch] $UpperCase

When you strongly type your variables, for example using [int] or [string], it’s common to use lower case, so I generally stick to lower for [switch], but it’s not mandatory. Just pick a standard for you and your team, then stick with it.

Naming Switches

When creating your switches, be sure to use clear names. In our example, UpperCase was a good switch name. Especially when using the Get- verb in our function name, as it implied the results should be in upper case. It doesn’t occur to me that I need to pass in some value to make it happen.

Contrast that with a switch name like MaxValue. Here, I wonder if I want to return a maximum value, or if I need to pass in a value that I want to be the maximum value, or something else.

A Note on $switchName -eq $true

You may see examples on the web such as:

if ($UpperCase -eq $true)

to check to see if a switch is present. This is a much older, and very much out of date method. Microsoft recommends you use the .IsPresent method that you saw in these examples, you should stick to it in your code.

Conclusion

In this post we covered the useful switch parameter. It’s very easy to use, and can add a lot of flexibility to your functions. This also gives a good foundation for discussion of the Verbose and Debug switches built into all Advanced Functions in our next blog post.

The demos in this series of blog posts came from my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight. At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.

Fun With PowerShell Pipelined Functions

Introduction

In my previous post, I covered the use of PowerShell Advanced Functions. I highly suggest you read it if you haven’t, it provides some foundational knowledge that will be important to understand for this post.

In this post, we’ll see how to pipeline enable your functions. Just like a cmdlet, you’ll be able to take input from the pipeline, work with it, then send it out your function back into the pipeline.

For all of the examples, we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.1.3, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.

Pipelining Your Advanced Functions

Pipelining is what gives PowerShell it’s real power. The ability to have small, focused cmdlets (or functions) that you can chain together to produce a useful output. Let’s see this simple, common example:

Get-ChildItem | Sort-Object -Property Length

Result:
Mode  LastWriteTime       Length Name
----  -------------       ------ ----
la--- 11/24/2020  3:37 PM   1115 ReadMe.md
la--- 11/24/2020  3:42 PM   1819 02 - Providers.ps1
la--- 11/24/2020  3:42 PM   3125 09 - Examples.ps1
la--- 11/24/2020  3:42 PM   3732 01 - Cmdlets.ps1
la---  7/15/2021  4:48 PM   4315 06 - Logic Branching and Looping.ps1
la--- 11/24/2020  3:42 PM   4717 03 - Variables.ps1
la--- 11/24/2020  3:42 PM   6210 08 - Classes.ps1
la---  7/20/2021  4:35 PM   6843 07 - Functions.ps1
la---  7/18/2021  8:18 PM   7970 04 - Strings.ps1
la---  7/9/2021   8:00 PM   8486 05 - Arrays and Hashtables.ps1
la--- 11/20/2020 12:58 AM   9694 Company.csv
la--- 11/20/2020 12:58 AM  19479 Company.json

As you can see, Get-ChildItem‘s output was piped into the Sort-Object cmdlet using the pipe symbol, the vertical bar | . Sort-Object took a parameter of a property name, in this case Length, and sorted its output based on that property name.

So how fun would it be to write your own functions that could work with the pipeline? Well as it turns out it’s not only fun but easy too. Here’s an example of a simple pipeline enabled function.

function Get-PSFiles ()
{
  [CmdletBinding()]
  param ( [Parameter (ValueFromPipeline) ]
          $file
        )

  begin  { }

  process
  {
    if ($file.Name -like "*.ps1")
    {
      $retval = "  PowerShell file is $($file.Name)"
      # This is the equivalent of: return $retval
      $retval
    }
  }

  end { }
}

The purpose of Get-PSFiles is to examine each file being passed in from the pipeline. If it finds the file name ends in .ps1, it will pass it onto the next item in the pipeline. Otherwise it gets ignored.

First off is the [CmdletBinding()], which you know by now is needed to let Powershell know this is an advanced function.

Now we have our param block. Note that the parameter block has an attribute of (ValueFromPipeline). When an object comes in from the pipeline it will get copied into the variable with the (ValueFromPipeline) attribute, in this case $file.

The next block in the function is the begin { } block. The begin block executes once, and only once, when the function is first called. Here you could do things like set variables or perform a calculation that will be used later in the function.

In my experience the begin block isn’t used a lot, and if yours is empty you can actually omit it completely from your function.

The next section is the process block. This is where all the fun happens! Here we can work with the objects as they are passed in, one by one, from the pipeline.

In this simple script, I look at the Name property of the item being passed in, which is stored in the variable $file. If it ends in .ps1, I set the return value ($retVal) to a string which has some text including the file name. If it doesn’t end in .ps1, I just don’t do anything with it.

I then have a simple line of $retVal. Since it’s not consumed by any other code PowerShell pushes it out into the next item in the pipeline. If there is no next item, it is displayed to the screen.

Once all the incoming items from the pipeline have been processed, the function continues to the end { } block. This is where you would do any cleanup. Similar to the begin block, end does not get used a lot, and you can omit it entirely if it is empty.

To use our Get-PSFiles function, we first need to highlight it and use F5/F8 to load it into memory. Once done we’ll be ready to call it. In this case when we call it we’ll save the output into a variable then display the contents of the variable.

$output = Get-ChildItem | Get-PSFiles
$output

Result:
  PowerShell file is 01 - Cmdlets.ps1
  PowerShell file is 02 - Providers.ps1
  PowerShell file is 03 - Variables.ps1
  PowerShell file is 04 - Strings.ps1
  PowerShell file is 05 - Arrays and Hashtables.ps1
  PowerShell file is 06 - Logic Branching and Looping.ps1
  PowerShell file is 07 - Functions.ps1
  PowerShell file is 08 - Classes.ps1
  PowerShell file is 09 - Examples.ps1

The directory I’m running from has other files in it besides PowerShell scripts, but the function we wrote filtered those out and only returns my PowerShell script files.

You may wonder, what datatype gets returned? We can find out by checking the type of the variable using the GetType() method built into all PowerShell variables.

$output.GetType()

Result:
IsPublic IsSerial Name     BaseType
-------- -------- ----     --------
True     True     Object[] System.Array

As you can see, it returns an array of objects.

So this function is useful, but limited in one way. It can only work with file type objects such as ones retrieved using Get-ChildItem. What if instead we wanted a function that only worked on a single property?

Line Continuation

Before we get into the next section, I want to bring up the topic of line continuation. Sometimes a line of PowerShell code will get very long. It can be useful to break it up across multiple lines for readability.

PowerShell uses the backtick character, the ` as its line continuation character. On US keyboard this is typically to the left of the number 1. If you are outside the US you’ll have to hunt around to find it, I’ll have to claim ignorance of keyboard layouts for other areas of our globe.

The line continuation character simply tells PowerShell “hey, this set of commands continues on the next line, treat it all as one line of code until you no longer find another backtick character”.

Here’s a simple example:

Write-Host 'Here are the names!' `
  -ForegroundColor Green

As you can see I have a simple Write-Host which displays information to the screen. At the very end of the line I have the backtick character. Then the Write-Host cmdlet continues, passing in the parameter of ForegroundColor.

I encourage you to use line continuation characters whenever you have a long line of code as it will make it much easier to read. It’s also useful to folks like myself who write blog posts or give presentations where my display area is limited. If you go look at some examples on my GitHub site, you’ll see I use them quite a bit.

On a large monitor such as the one I normally use it’s not as needed. But when I write a blog post like this one, or go present at a user group, the amount of space I have is much more limited.

It’s also worth mentioning that the pipe symbol | has line continuation built right into it. I could have taken my earlier example and entered into my editor like so:

Get-ChildItem |
  Sort-Object -Property Length

The pipe symbol has to be the very last character on the line. There cannot be any spaces, comments, or other code after it. On the next line I chose to indent the Sort-Object command by two spaces, this is strictly to make the code easier to read and is not required, but is a good habit.

OK that little detour complete, let’s continue our fun by using just a single property from the pipeline in our function.

Using a Single Property in your Pipeline Function

One way we can make our functions more reusable is to work with a single property. For example, almost all cmdlets return a set of objects that have a Name property. We could create a function that works with just that property, and thus use it with all cmdlets that return objects with a Name property.

This next example is a bit contrived, to show you the concepts, and isn’t something I’d normally code in “real life” but it will serve to show you how this concept works.

function Show-BName ()
{
  [CmdletBinding()]
  param ( [Parameter (ValueFromPipelineByPropertyName)]
          $Name
        )

  begin
  {
    Write-Host 'Here are the names!' `
      -ForegroundColor Green
    $names = @()
  }

  process
  {
    $names += $name
    "  Here is the name: $name"
  }

  end
  {
    Write-Host "Those were the names you passed in:" `
      -ForegroundColor Green
    foreach ($n in $names)
    {
       Write-Host "  You passed in " `
         -ForegroundColor White -NoNewline
      Write-Host $n -ForegroundColor Yellow
    }
  }
}

In the parameter block, we use a slightly different attribute, ValueFromPipelineByPropertyName. This tells PowerShell to take each object being passed in, and copy it’s Name property into our variable, in this case $Name.

Note that the name of the parameter must match the name of the property you want to work with. Thus the Name property is copied into the $Name parameter. The rest of the object will be discarded, and not available to you in the function.

The function falls into our begin block, in which I’ve included a Write-Host statement to display a message our function is beginning. Let me stress, you normally do not include Write-Host messages in functions. Typically the script that calls the function will take the output, and display the results. I’m doing this here only to demonstrate how each piece of the advanced function works.

I then do something you might do, I create a variable called $names. I initialize it as an empty array.

Now the function moves into the process block. In it, I take the name that came in from the pipeline and add it to the array. I then embed the name in a string. Since I don’t do anything with the string, it is now passed out to return to the pipeline.

Finally we hit the end block. Here, I’m using some Write-Host statements to show we’re done and what names were processed. In a real world situation you might use this for logging or some other reason that fits your needs.

So let’s see this in action. As before, highlight the function and run it using F8/F5 to get it into memory. Then we can call it.

Get-ChildItem |
  Show-BName

Result:
Here are the names!
  Here is the name: 01 - Cmdlets.ps1
  Here is the name: 02 - Providers.ps1
  Here is the name: 03 - Variables.ps1
  Here is the name: 04 - Strings.ps1
  Here is the name: 05 - Arrays and Hashtables.ps1
  Here is the name: 06 - Logic Branching and Looping.ps1
  Here is the name: 07 - Functions.ps1
  Here is the name: 08 - Classes.ps1
  Here is the name: 09 - Examples.ps1
  Here is the name: Company.csv
  Here is the name: Company.json
  Here is the name: ReadMe.md
Those were the names you passed in:
  You passed in 01 - Cmdlets.ps1
  You passed in 02 - Providers.ps1
  You passed in 03 - Variables.ps1
  You passed in 04 - Strings.ps1
  You passed in 05 - Arrays and Hashtables.ps1
  You passed in 06 - Logic Branching and Looping.ps1
  You passed in 07 - Functions.ps1
  You passed in 08 - Classes.ps1
  You passed in 09 - Examples.ps1
  You passed in Company.csv
  You passed in Company.json
  You passed in ReadMe.md

The first set of “Here is the names…” is what came out of the function into the pipeline. Since we didn’t do anything with them, they were displayed on the screen. The second set, with “You passed in…” is from the end block.

We can have even more fun, let’s take the output of our function and pipe it into another cmdlet. We’ll use Sort-Object to display our results in descending order.

Get-ChildItem |
  Show-BName |
  Sort-Object -Descending

Result:
Here are the names!
Those were the names you passed in:
  You passed in 01 - Cmdlets.ps1
  You passed in 02 - Providers.ps1
  You passed in 03 - Variables.ps1
  You passed in 04 - Strings.ps1
  You passed in 05 - Arrays and Hashtables.ps1
  You passed in 06 - Logic Branching and Looping.ps1
  You passed in 07 - Functions.ps1
  You passed in 08 - Classes.ps1
  You passed in 09 - Examples.ps1
  You passed in Company.csv
  You passed in Company.json
  You passed in ReadMe.md
  Here is the name: ReadMe.md
  Here is the name: Company.json
  Here is the name: Company.csv
  Here is the name: 09 - Examples.ps1
  Here is the name: 08 - Classes.ps1
  Here is the name: 07 - Functions.ps1
  Here is the name: 06 - Logic Branching and Looping.ps1
  Here is the name: 05 - Arrays and Hashtables.ps1
  Here is the name: 04 - Strings.ps1
  Here is the name: 03 - Variables.ps1
  Here is the name: 02 - Providers.ps1
  Here is the name: 01 - Cmdlets.ps1

There are a couple of things to notice with this version. First, the result of the end block, the “You passed in…” comes first. That’s because the function ended, but the data it produced is now being consumed by Sort-Object.

Second, you can see Sort-Object took the output and sorted in reverse (descending) order.

As they say on TV, but wait, there’s more!

Because our function only acts on the Name property, it could care less what type of object is coming in as long as it has a Name property. Thus we could use it with any cmdlet as long as that cmdlet produces objects with a Name property!

Get-Process returns objects with a Name property, so let’s use it with our new function.

Get-Process | Show-BName

Result:
  Here is the name: 5KPlayer
  Here is the name: aesm_service
  Here is the name: Airplay
  Here is the name: AppleMobileDeviceProcess
  Here is the name: ApplicationFrameHost
  Here is the name: CepstralLicSrv
  Here is the name: Code
  (many more here, truncated for brevity)
Those were the names you passed in:
  You passed in 5KPlayer
  You passed in aesm_service
  You passed in Airplay
  You passed in AppleMobileDeviceProcess
  You passed in ApplicationFrameHost
  You passed in CepstralLicSrv
  You passed in Code
  (many more here too, again truncated for brevity)

Because we were able to keep the needs of our function tightly scoped to just the Name property, we were able to create a function that was highly flexible and reusable.

Conclusion

In this post we saw how to create a function that would work in the pipeline. We did it two ways, first by passing in entire objects, then by passing in a specific property of an object.

But there’s still more fun to be had! In a future post we’ll see how to implement two switches common to all cmdlets and advanced functions, Verbose and Debug.

The demos in this course came from my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight. At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.

Fun With PowerShell Advanced Functions

Introduction

In my previous post, I covered the use of PowerShell Basic Functions. In this post we’ll cover Advanced Functions.

Advanced Functions provide several abilities over basic ones. First, you can create a detailed parameter list, including the ability to include optional parameters.

Second, you can pipeline enable your functions. Just like a cmdlet, you’ll be able to take input from the pipeline, work with it, then send it out your function back into the pipeline. This will be the subject of our next post.

Finally, you can use features such as Verbose and Debug, which will be the subject of an upcoming blog post.

For all of the examples, we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.1.3, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.

A Simple Advanced Function

In my Basic Functions post, I created a simple function Get-AValue that multiplied two values together and returned the result. Let’s take a look at the advanced version, Get-BValue.

function Get-BValue()
{
  [CmdletBinding()]
  param (
          [Parameter( Mandatory = $true
                    , HelpMessage = 'Enter value one.'
                    )
          ]
          [int] $one
        , [Parameter( Mandatory = $false
                    , HelpMessage = 'Enter value two.'
                    )
          ]
          [int] $two = 42
        )

  return $one * $two

}

We start with the function keyword, followed by the name we’ve chosen for the function, in this case Get-BValue. Note the parenthesis are empty, unlike a basic function advanced ones declare their parameters in a different spot.

The first line you’ll see in the function is [CmdletBinding()]. This is the indicator to PowerShell that this is an advanced function. It must be included in the first line for PowerShell to treat this as advanced.

Next up are the parameters, inside a param () block. Within we list each parameter, separated by commas.

A useful feature is the ability to add parameter attributes. For the first parameter, $one, we have the following block:

[Parameter( Mandatory = $true
          , HelpMessage = 'Enter value one.'
          )
]

The first attribute is Mandatory. This indicates that this is a required parameter, and can be set to either $true or $false. When $true, if the user does not enter it they will be prompted to supply a value.

The HelpMessage is text that will be displayed when the user gets help on your function. We won’t do much with it in this demo, but I’ve included it to show there are a variety of attributes you can use with parameters.

Next up is the actual parameter declaration, [int] $one. In this demo we’ve strongly typed our variable. Only integer values will be allowed, any string our decimal value (such as 3.14) will be rejected by PowerShell.

Note that for readability I’ve chosen to split the code onto separate lines, you could have condensed all this into a single line if you’d wanted.

Strong typing has its pros and cons. It can be very helpful in cases where the data must be of a specific type. On the other hand, it can prevent other uses. In this demo for example, we could just have easily multiplied a decimal value.

If you want a flexible variable, then you can leave off the type declaration. In this example we’ll leave it in, so you can see how it works.

Next up is the second variable declaration.

, [Parameter( Mandatory = $false
             , HelpMessage = 'Enter value two.'
             )
  ]
  [int] $two = 42

Here, we’ve set Mandatory to $false. This means if the user does not supply a value for $two, it will use the default value. Where does the default value come from?

If you look you’ll see [int] $two = 42. The 42 is the default value, and is used when the user does not supply a value.

After the parameter block ends we have the actual code for the function, in this case a simple return $one * $two.

So let’s see some examples of how this works. In your development environment highlight the function and press F8 (for VSCode) or F5 (for the PowerShell IDE). Now that it’s in memory you can call it.

Get-BValue -one 33 -two 42

Result:
1386

Here I called the function, passing in the parameters by name. I could have also left off the names and called it by position, as we did in the tutorial on basic functions.

Now lets call it only passing in a value for -one.

Get-BValue -one 33

Result:
1386

In this case, it took our input for -one, but since no value for -two was passed in, the function used the default value of 42.

So what happens if we call it and pass in no values?

Get-BValue

Result:
cmdlet Get-BValue at command pipeline position 1
Supply values for the following parameters:
one: 33
1386

As you can see in the Result: output area, we were prompted for a value for one. I entered 33 and hit enter, then got the expected result of 1386.

To illustrate how the strong typing works, let’s call passing in a string for the -one parameter.

Get-BValue -one "x"

Result:
Get-BValue: Cannot process argument transformation on parameter 'one'. Cannot convert value "x" to type "System.Int32". Error: "Input string was not in a correct format."

As you can see, PowerShell rejects our input with the resulting error message.

Conclusion

In this post we got a start in PowerShell Advanced Functions. We covered a simple advanced function, including parameters and how to use attributes with them.

But there’s still more fun to be had! In the next post we’ll see how to pipeline enable your advanced functions. Then in a future post we’ll implement two switches common to all cmdlets and advanced functions, Verbose and Debug.

The demos in this course came from my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight. At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.