<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=1678611822423757&amp;ev=PageView&amp;noscript=1">

Advanced PowerShell Functions: Upping Your Game

Adam Bertram| November 07 2016

| security

advanced-powershell-functions

When writing large PowerShell scripts or modules, it will eventually become necessary to split up the code into modular pieces. Modularity can be achieved by using basic and advanced PowerShell functions. It also encourages good coding practices. One way to build modular code in PowerShell is to use functions. At their most basic, PowerShell functions allow you to compartmentalize code rather than stringing it all together in one large script.

PowerShell provides two different kinds of functions: basic and advanced. Basic functions are just that: basic. They are the simplest form a function can be. Basic functions do not allow you to do things like accept pipeline input, control streams and so on. For that, we'll have to write advanced functions. But what makes a basic function "advanced"? Let's find out.

Related Article: Leveraging PowerShell Automation in the Cloud

Advanced functions give you a few advantages: accepting pipeline input, allowing you to use built-in parameters like -Verbose, -ErrorAction, -ErrorVariable and so on. They also allow you to use advanced parameter attributes and write help content as well.

 

Pipeline Input

To demonstrate, let's start with a basic function that tests connectivity of a remote server. Our example of basic function might look something like this:

PowerShell advanced function

This is a function that pings a computer and tests to ensure the c$ administrative share is available on a Windows server. If the computer is online and has the c$ share available, it will return True. Otherwise, it will return False.

powershell-ebook-cta-9x3

Passing a computer name to the function works great.

PowerShell advanced function

However, what if you have lots of computers perhaps stored in a text file? To run this function for all of those computers, you'll have to use a foreach loop. This is ugly.

PowerShell advanced function

It'd be much easier to use the pipeline but doing this won't work with our basic function.

PowerShell advanced function

This is because a basic function isn't capable of accepting pipeline input. This is just one feature we're missing with basic functions. Let's convert this basic function to an advanced function. To do this, we'll need to add a [CmdletBinding()] reference as well as building a parameter block. Our function now looks like this:

PowerShell advanced function

This "converts" the basic function to advanced but you're still not going to notice much difference. This step just gives you the ability to do all the cool stuff that advanced functions allow. To accept pipeline input, we have to change our parameter to use parameter attributes.

PowerShell advanced function

Notice that I've added a ValueFromPipeline parameter attribute as well as adding a process block. The process block is necessary for accepting all kinds of pipeline input. The ValueFromPipeline attribute is one of two ways to accept pipeline input. For more information on pipeline support, visit Boe Prox's blog post.

PowerShell advanced function

Parameter Validation

Parameter validation is another feature you'll get when using PowerShell's advanced functions. This feature allows you to limit input coming into your function. It's important to limit input as strictly as possible when building functions. To demonstrate, let's take our existing function and ensure that only the MEMBERSRV1 and COMPUTER2 computers are allowed in. We can do this by using the ValidateSet validation attribute. This attribute limits the values the ComputerName parameter will accept from an array of strings.

Related Article: The PowerShell Script Orchestrator

Parameter validation attributes are placed right below the Parameter declaration as shown below.

PowerShell advanced function

Notice now when I try to pass a name, not on the list, it will not work.

PowerShell advanced function

Stream Control in Advanced Functions

Finally, advanced functions allow you to control the streams that are output to the console. It's possible to use commands like Write-Verbose, Write-Warning and so on inside an advanced function and control when these messages are displayed. For example, let's add a status message to our function.

PowerShell advanced function

Running the function as-is does not change. However, notice now we have a -Verbose parameter. Using this parameter displays that verbose message.

PowerShell advanced function

You'll find that advanced functions have many parameters by default without having to create them. Just type out the function name, press "-" and start hitting the tab key. This will allow you to see all of the parameters that are now available to you.

Make advanced functions part of your daily scripting habits. They provide lots of extra functionality with minimal code changes to basic functions.

To learn more about how to automate in PowerShell and achieve lean IT, download this eBook.

 

Topics: security

Leave a Reply

Your email address will not be published. Required fields are marked *

THIS POST WAS WRITTEN BY Adam Bertram

Adam Bertram is a 20-year veteran of IT. He’s currently an automation engineer, blogger, independent consultant, freelance writer, author, and trainer. Adam focuses on DevOps, system management, and automation technologies as well as various cloud platforms. He is a Microsoft Cloud and Datacenter Management MVP and efficiency nerd that enjoys teaching others a better way to leverage automation.

Free Trials

Getting started has never been easier. Download a trial today.

Download Free Trials

Contact Us

Let us know how we can help you. Focus on what matters. 

Send us a note

Subscribe to our Blog

Let’s stay in touch! Register to receive our blog updates.