How to Use PowerShell Functions to Improve Readability of Your Scripts

When programming scripts to automate tasks, one of the recommended practices is creating functions to optimize the reusability of code. Administrators who automate multiple tasks with Microsoft Windows PowerShell  will see that code lines are often repeated or need to separate large sections of code into different blocks to make scripts understandable and reduce coding time for writing additional scripts. PowerShell functions can solve this.

A function is a group of PowerShell statements. Like cmdlets, functions work with input parameters and can return values that can be displayed, assigned to variables, or piped to other functions or cmdlets. Once the function has been created, it may be called as many times as required instead of repeatedly repeating its code. There are two different types of functions in PowerShell: basic and advanced.

PowerShell Functions and Cmdlet Parameters

A cmdlet is a lightweight script you can use in a PowerShell environment to perform a single task such as changing directories or moving files. You can create cmdlets as PowerShell functions without writing and compiling a binary cmdlet. Hence, unlike functions that are integrated PowerShell environment before compiling, cmdlets are .NET classes that are already compiled into “.dll” files so that PowerShell can access them.

Like functions, cmdlets can have parameters and return values to display or assign to variables. You can add parameters to the cmdlet at the command prompt or pass them to other cmdlets via a pipeline as an output from the previous cmdlet. In this case, each parameter or argument’s values indicate the actual input that cmdlet accepts and how the cmdlets process such an input.

You can also incorporate switches (specialized arguments) that provide selections or presets for the parameter. For example, “Get-Help” is a simple cmdlet that you can use to get desired help concerning various commands. The syntax of getting support for a desired cmdlet from online documentation is:

Get-Help <cmd-name> -online

In the syntax above, the parameter<cmd-name> argument is the name of the command that you want to get more information about. For example, if you wanted to get more details about the Get-EventLog cmdlet with the switch “-online,” the PowerShell command would appear like this one:

Get-Help Get-EventLog -online

Add Parameters to your PowerShell Functions

You can also add parameters to the advanced functions that you write. These parameters are made available to your users in addition to the common parameters added by PowerShell to all cmdlets. Compiled cmdlets can carry out the culture-sensitive conversion, allows you to declare static parameters, and declare the attributes of parameters such as:

ParameterSetName argument, ValueFromPipeline Argument, ValueFromPipelineByPropertyName argument, HelpMessage Argument, Alias Attribute, SupportsWildcards Attribute etc.

Best Practices

To allow for consistent user experience with other cmdlets, adhere to the following best practices:

Basic PowerShell Functions

Using Basic functions is the simplest option for administrators when working with PowerShell functions. These functions do not offer any built-in inherited features; hence, all types of error streams or parameter management requirements must be explicitly defined and covered in the function’s code.

The following image shows a basic function definition and its execution. This function lists all running services containing the string “RAS” in their Display Name:

Figure 1 - PowerShell Functions

Functions do not need to be complex to be helpful. Basic functions are often used to run simple tasks that do not require a complex parameter list or deep analysis on failed executions but are significantly important for a company’s day-to-day maintenance tasks.

Advanced PowerShell Functions

It’s really easy to convert a PowerShell function into an advanced function. One of the distinctions in between a regular function and an advanced form is that the latter includes a number of automated additions to the function of common parameters. These common settings include Verbose and Debug parameters.

Basic functions can be converted into advanced functions by simply adding the CmdletBinding attribute, the Parameter attribute, or both. The CmdletBinding attribute allows functions to operate like compiled cmdlets, thus enabling some of the built-in features that cmdlets provide, such as error streams. On the other hand, the Parameter attribute is used to predefine certain conditions of the function’s parameters such as establishing mandatory parameters.

Following the previous example, the function has been modified by adding the CmdletBinding attribute. Now, the PowerShell ISE auto-completion feature shows a list of built-in parameters that can be used to enhance the function performance.

Figure 2 - PowerShell Functions

Using advanced functions is a recommended practice when building scripts to be executed along separate environments and by different administrators because script programmers like common cmdlets can use them.

Parallels RAS PowerShell SDK

An SDK (Software Development Kit) is a collection of software tools and programs used by developers to manage specific products. SDK tools include some elements, libraries, processes, or documentation, and they are designed to be used with particular platforms and programming languages.

Check out the complete set of commands to manage a Parallels RAS Farm.

Download the Trial