PowerShell Troubleshooting Guide

Windows PowerShell (or just PowerShell, for short) was introduced by Microsoft in late 2006 accompanied by little fanfare. In the last seven years, PowerShell has gone from being what might have seemed like a research project to what is now the mainstay of Windows automation and is included in every Windows operating system and most of the major Microsoft products including Exchange, System Center, SQL Server, SharePoint, and Azure.

PowerShell is often thought of as a command-line language, and that is an accurate (but incomplete) view. Working on the command line in PowerShell is a joy compared to MS-DOS batch files and most of the command-line tools that IT professionals are used to having at their fingertips work with no changes in the PowerShell environment. PowerShell is also a first-class scripting language where the knowledge you gain from the command line pays off big time. Unlike MS-DOS, PowerShell was designed from the beginning to be a powerful tool for scripting. Unlike VBScript, there is an interactive PowerShell console that allows you to iteratively develop solutions a bit at a time as you work your way through a sequence of objects, methods, and properties.

PowerShell includes several different elements that work together to create a very powerful and flexible ecosystem. While this chapter will give you an overview of several of these pieces, be aware that the PowerShell language is the subject of many books. For in-depth coverage of these topics, refer to PowerShell In Practice by Don Jones, Jeffery Hicks, and Richard Siddaway, Manning Publications.

In PowerShell, a cmdlet (pronounced "command-let") describes a unit of functionality specific to PowerShell. In version 1.0 of PowerShell, the only way to create a cmdlet was by using managed (compiled) code, but 2.0 introduced advanced functions, which have the same capabilities as cmdlets. Built-in cmdlets exist to interact with the filesystem, services, processes, event logs, WMI, and other system objects. Some examples of cmdlets, which also show the flexibility in parameter passing, are shown as follows:

Cmdlets are named with a two-part construction: verb-noun. Verbs in PowerShell describe the actions to be performed and come from a common list provided by Microsoft. These include Get, Set, Start, Stop, and other easy-to-remember terms. The Get-Verb cmdlet provides the list of approved verbs with some information on how the verbs can be grouped. The following screenshot shows the beginning of the list of verbs and their corresponding groups:

PowerShell nouns specify on which kind of objects the cmdlet operates. Examples of nouns are Service, Process, File, or WMIObject Unlike the list of verbs, there is no managed list of approved nouns. The reason for this is simple. With every new version of Windows, more and more cmdlets are being delivered which cover more and more of the operating system's features. An up-to-date reference for verbs along with guidance between similar or easily confused verbs can be found at http://msdn.microsoft.com/en-us/library/ms714428.aspx.

Putting nouns and verbs together, you get full cmdlet names such as Get-Process and Start-Service. By providing a list of verbs to choose from, the PowerShell team has gone a long way toward simplifying the experience for users. Without the guidance of a list such as this, cmdlet authors would often be forced to choose between several candidates for a cmdlet name. For instance, Stop-Service is the actual cmdlet name, but names such as Kill-Service and Terminate-Service would both convey the same effect. Knowing that Stop is the approved verb not only makes the decision simple, it also makes it simple to guess how one would terminate a process (as opposed to a service). The obvious answer would be Stop-Process.

Cmdlets each have their own set of parameters that allow values to be supplied on the command line or through a pipeline. Switch parameters also allow for on/off options without needing to pass a value. There is a large set of common parameters that can be used with all cmdlets. Cmdlets that modify the state of the system also generally allow the use of the –Whatif and –Confirm risk mitigation parameters. Common parameters and risk mitigation parameters are covered in detail in Chapter 5, Proactive PowerShell.

The big three cmdlets

When learning PowerShell, it's customary to emphasize three important cmdlets that are used to get PowerShell to give information about the environment and objects that are returned by the cmdlets. The first cmdlet is Get-Command. This cmdlet is used to get a list of matching cmdlets, scripts, functions, or executables in the current path. For instance, to get a list of commands related to services, the Get-Command *service* command would be a good place to start. The list displayed might look like this:

The thought behind listing Get-Command as the first cmdlet you would use is that it is used to discover the name of cmdlets. This is true, but in my experience you won't be using Get-Command for very long. The verb-noun naming convention combined with PowerShell's very convenient tab-completion feature will mean that as you get familiar with the language you will be able to guess cmdlet names quickly and won't be relying on Get-Command. It is useful though, and might show you commands that you didn't know existed. Another use for Get-Command is to figure out what command is executed. For instance, if you encountered the Compare $a $b command line and didn't know what the Compare command was, you could try the Get-Command command to find that Compare is an alias for Compare-Object.

Note

PowerShell provides aliases for two reasons. First, to provide aliases that are commands in other shells (such as dir or ls), which lead us to PowerShell cmdlets that perform similar functions. Secondly, to give abbreviations that are shorter and quicker to type for commonly used cmdlets (for example, ? for Where-Object and gsv for Get-Service). In the PowerShell community, a best practice is to use aliases only in the command line and never in scripts. For that reason, I will generally not be using aliases in example scripts.

A similar trick can be used to find out where an executable is found: Get-Command nslookup | Select-Object Path returns the path C:\Windows\system32\nslookup.exe.

The second and probably most important cmdlet is Get-Help. Get-Help is used to display information in PowerShell's help system. The help system contains information about individual cmdlets and also contains general information about PowerShell-related topics. The cmdlet help includes syntax information about parameters used with each cmdlet, detailed information about cmdlet functionality, and it also often contains helpful examples illustrating common ways to use the cmdlet.

Tip

Pay attention to the help files. Sometimes, the problem you are having is because you are using a cmdlet or parameter differently than the designer intended. The examples in the help system might point you in the right direction.

The following screenshot shows the beginning of the help information for the Get-Help cmdlet:

Another source of information in the help files are topics about the PowerShell language. The names of these help topics start with about_, and range from a few paragraphs to several pages of detailed information. In a few cases, the about_ topics are more detailed than most books' coverage of them. The following screenshot shows the beginning of the about_Language_Keywords topic (the entire topic is approximately 13 pages long):

The Get-Help cmdlet has a number of switches that control precisely what help information is displayed. The default display is somewhat brief and can be expanded by using the –Full or –Detailed switches. The –Examples switch displays the list of examples associated with the topic. The full help output can also be viewed in a pop-up window in PowerShell 3.0 or higher using the –ShowWindow switch.

Tip

PowerShell 3.0 and above do not ship with any help content. To view help in these systems you will need to use the Update-Help cmdlet in an elevated session.

The final member of the big three is Get-Member. In PowerShell, all output from commands comes in the form of objects. The Get-Member cmdlet is used to display the members (for example, properties, methods, and events) associated with a set of objects as well as the types of those objects. In general, you will pipe objects into Get-Member to see what you can do with those objects. An example involving services is shown as follows:

Functions are similar to cmdlets and should follow the same naming conventions. Whereas cmdlets are compiled units of PowerShell functionality written in managed code like C#, functions are written using the PowerShell language. Starting with PowerShell 2.0, it has been possible to write advanced functions, which are very similar to cmdlets. It is possible to use common parameters and risk mitigation parameters with advanced functions. An example of a function is shown as follows:

function get-PowerShellVersionMessage{
param($name)
    $PowerShellVersion=$PSVersionTable.PSVersion
    return "We're using $PowerShellVersion, $name!"
}

Calling the function at the command line is straightforward, as shown in the following screenshot:

Scripts are simply files with a .ps1 file extension, which contain PowerShell code. It is possible to parameterize a script file in the same way that you would a function using a Param() statement at the beginning of the file. If we were to store the following code in a file called Get-PowerShellVersionMessage.ps1, it would be roughly equivalent to the Get-PowerShellVersionMessage function in the previous section:

param($name)
    $PowerShellVersion=$PSVersionTable.PSVersion
    return "We're using $PowerShellVersion, $name!"

A security feature of PowerShell is that it won't run a script in the current directory without specifically referring to the directory, so calling this script would look like this:

.\get-powershellversionmessage –name Mike

The following screenshot shows the aforementioned code being stored in a file:

And the output would be (on the computer I'm using): We're using PowerShell 4.0, Mike.

It is also possible to define multiple functions in a script. However, when doing so, it is important to understand the concept of scope. When a script or function is executed, PowerShell creates a new memory area for definitions (for example, variables and functions) that are created during the execution. When the script or function exits, that memory is destroyed, thereby removing the new definitions. Executing a script with multiple functions will not export those functions into the current scope. Instead, the script executes in its own scope and defines the functions in that scope. When the script execution is finished, the newly created scope is exited, removing the function definitions. To overcome this situation, the dot-source operator was created. To dot-source a file means to run the file, without creating a new scope in which to run. If there was a script file with function definitions called myFuncs.ps1, dot-sourcing the file would use the following syntax:

. .\myFuncs.ps1

Note that there is a space after the first dot, and that since the script is in the current directory explicit use of the directory is required.

PowerShell expressions involving cmdlets and functions can be connected together using pipelines. Pipelines are not a new concept, and have been in DOS for a long time (and in Unix/Linux forever). The idea of a pipeline is similar to a conveyor belt in a factory. Materials on a conveyor belt move from one station to the next as workers or machinery work on the materials to connect, construct, or somehow modify the work in progress. In the same way, pipelines allow data to move from one command to the next, as the output of one command is treated as the input for the next. There is no practical limit to the number of commands that can be connected this way, but readability does keep command lines from continuing forever. It can be tempting to string more and more expressions together to create a single-line solution, but troubleshooting a pipeline evaluation can be tricky.

Prior to PowerShell, pipelines dealt with output and input in terms of text, passing strings from one program to the next regardless of what kind of information was being processed. PowerShell makes a major change to this paradigm by treating all input and output as objects. By doing this, PowerShell cmdlets are able to work with the properties, methods, and events that are exposed by the data rather than simply dealing with the string representation. The PowerShell community often refers to the methods used by string-based pipelines as parse-and-pray, which is named after the twin operations of string parsing based on an understanding of the text format and hoping that the format of the output doesn't ever change. An example, shown in the following screenshot, illustrates this quite well:

It's easy to think of the output of the MS-DOS dir command as a sequence of files and folders, but if the output is carefully studied, something different becomes clear. There is a tremendous amount of other information provided:

To work with this output and deal with, for instance, the file names, there's a tremendous amount of work that would need to be done to analyze the formatting of all of these elements. Also, there are several different formatting parameters that can be used with the MS-DOS dir command that would affect the output. By passing data between cmdlets as objects, all of this work is eliminated. The PowerShell Get-ChildItem cmdlet, which is similar to the MS-DOS dir command, outputs a sequence of file and directory objects if the current location is a filesystem location.

How pipelines change the game

To see how the choice of an object-oriented pipeline changes the way work is done, it is sufficient to look at the MS-DOS dir command. I am picking on the dir command because it has a simple function and everyone in IT has some level of experience with it. If you wanted to sort the output of a dir command, you would need to know what the parameters built into the command are. To do that, you'd do something like this:

It's clear that the designer of the command had sorting in mind, because there is a /O option with five different ways to sort (ten if you include reverse). That is helpful, but files have a lot more than five properties. What if you wanted to sort by more than one property? Ignoring those questions for a moment, does the collection of sorting options for this command help you at all if you were trying to sort the output of a different command (say an ATTRIB or SET command)? You might hope that the same developer wrote the code for the second command, or that they used the same specifications, but you would be disappointed. Even the simple operation of sorting output is either not implemented or implemented differently by MS-DOS commands.

PowerShell takes an entirely different approach. If you were to look at the help for Get-ChildItem, you would find no provision for sorting at all. In fact, PowerShell cmdlets do not use parameters to supply sorting information. Instead, they use the object-oriented pipeline. MS-DOS developers needed to encode the sort parameters for the dir command inside the dir command itself is because that is the only place that the properties exist (including sorting criteria). Once the command has been executed, all that is left is text, and sorting text based on properties is a complex parse-and-pray operation (which we have already discussed). In PowerShell, however, the output of Get-ChildItem is a sequence of objects, so cmdlets downstream can still access the properties of the objects directly. Sorting in PowerShell is accomplished with the Sort-Object cmdlet, which is able to take a list of properties (among other things) on which to sort the sequence of objects that it receives as input. The following are some examples of sorting a directory listing in MS-DOS and also in PowerShell:

Sorting method	DOS command	PowerShell equivalent
Sort by filename	DIR /O:N	Get-childitem | sort-object Name
Sort by extension	DIR /O:E	Get-ChildItem | Sort-object Extension
Sort by size	DIR /O:S	Get-ChildItem | Sort-object Size
Sort by write date	DIR /O:D	Get-ChildItem | Sort-object LastWriteTime
Sort by creation date	Out of luck	Get-ChildItem | Sort-object CreationTime
Sort by name and size	Out of luck	Get-ChildItem | Sort-object Name,Size

It can be clearly seen by these examples that:

• PowerShell examples are longer

• PowerShell examples are easier to read (at least the sorting options)

• PowerShell techniques are more flexible

The most important thing about learning how to sort directory entries using Sort-Object is that sorting any kind of objects is done the exact same way. For instance, if you retrieved a list of applied hotfixes on the current computer using Get-hotfix, in order to sort it by HotFixID, you would issue the Get-Hotfix | Sort-Object –Property HotFixID command:

Another point to note about sorting objects by referring to properties is that the sorting is done according to the type of the property. For instance, sorting objects by a numeric property would order the objects by the magnitude of the property values, not by the string representation of those values. That is, a value of 10 would sort after 9, not between 1 and 2. This is just one more thing that you don't have to worry about.

Get-ChildItem | Where-object {$_.Size –lt 100}

Get-ChildItem | Where-object {$PSItem.Size –lt 100}

Where-Object Property Operator Value

Get-ChildItem | Where-Object Size –lt 100

PowerShell variables, similar to variables in other programming languages, are names for data stored in memory. PowerShell variable references begin with a dollar sign and are created by assigning a value with the assignment operator (the equals sign). Unlike many programming languages, you do not need to define variables before using them or even specify what type of information the variable is going to point to. For instance, the following statements are all valid:

$var = 5
$anothervar = "Hello"
$files = dir c:\

Note that while the first two assignments were simple (integer and string constants), the third involved executing a pipeline (with a single statement) and storing the results of that pipeline in a variable. The command in the third line returns a collection of more than one kind of object (it has files and folders). Note that there is no special notation required to store a collection of objects.

Several common parameters in PowerShell take the name of a variable in order to store results of some kind in that variable. The –ErrorVariable, –WarningVariable, –OutVariable parameters, and (new in Version 4.0) –PipelineVariable parameter all follow this pattern. Also, all of the *–Variable cmdlets have a –Name parameter. These parameters are expecting the name of the variable rather than the contents of the variable. The name of the variable does not include the dollar sign. In the following screenshot, you can see that the –outvariable parameter was passed the file value, which caused a copy of the output to be stored in the variable called file:

In short, referencing the content of the variable involves the dollar sign, but referencing the variable name does not.

In Version 1.0 of PowerShell, the only ways to group lists of functions were to either put script files for each function in a directory or to include several functions in a script file and use dot-sourcing to load the functions. Neither solution provided much in the way of functionality, though. Version 2.0 introduced the concept of modules. A PowerShell module usually consists of a folder residing in one of the directories listed in the PSModulePath environment variable and contains one of the following:

One tremendous advantage that modules have over scripts is that while every function in a script is visible when the script is run, visibility of functions (as well as variables and aliases) defined within a module can be controlled by using the Export-ModuleMember cmdlet.

The following module file, named TroubleShooting.psm1, re-implements the Get-PowerShellMessage function from earlier in the chapter using a helper function (Get-Message). Since only Get-PowerShellVersionMessage was exported, the helper function is not available after the module is imported but it is available to be called by the exported function.

function Get-Message{
param($ver,$name)
  return "We're using $ver, $name!"
}

function Get-PowerShellVersionMessage{
param($name)
  $version=$PSVersionTable.PSVersion
  $message=Get-Message $version $name
  return $message
}

Export-ModuleMember Get-PowerShellVersionMessage

Importing a module is accomplished by using the Import-Module cmdlet. Version 3.0 of PowerShell introduced the concept of automatic importing. With this feature enabled, if you refer to a cmdlet or function that does not exist, the shell looks in all of the modules that exist on the system for a matching name. If it finds one, it imports the module automatically. This even works with tab-completion. If you hit the Tab key, PowerShell will look for a cmdlet or function in memory that matches, but If it doesn't find one it will attempt to load the first module that has a function whose name matches the string you're trying to complete. Listing the cmdlets that have been loaded by a particular module is as simple as the Get-Command –Module module name.

For more information, check out the following references:

In this chapter, we have seen the main building blocks of PowerShell as a language. We have demonstrated how similar functionality can be implemented using a function, a script, and a module. An emphasis was placed on how PowerShell's use of an object-oriented pipeline gives tremendous advantages in terms of flexibility without re-implementing common features such as sorting and filtering in each function.

PowerShell provides an innovative programming and scripting experience. The next chapter will highlight various ways that the PowerShell language functions differently from other programming languages.