Summary: Microsoft Scripting Guy, Ed Wilson, shares a portion from his popular Microsoft Press book Windows PowerShell 3.0 First Steps.

Microsoft Scripting Guy, Ed Wilson, is here. Today I want to share with you another portion from my new book, Windows PowerShell 3.0 First Steps, which was recently released by Microsoft Press.

To read the first part of this series, see: Windows PowerShell 3.0 First Steps: Part 1.

Understanding the basics of cmdlets

All Windows PowerShell cmdlets behave basically the same way. There are some idiosyncrasies between cmdlets from different vendors, or from teams at Microsoft, but in general, when you understand the way that Windows PowerShell cmdlets work, you can transfer the knowledge to other cmdlets, platforms, and applications.

To call a Windows PowerShell cmdlet, you type it on a line in the Windows PowerShell console. To modify the way the cmdlet retrieves or displays information, you supply options for parameters that modify the cmdlet. Many of these parameters are unique and apply only to certain cmdlets. However, some parameters are applicable to all Windows PowerShell cmdlets. In fact, these cmdlets are part of the strength of the Windows PowerShell design. Called “common parameters,” the parameters that are supported by all Windows PowerShell cmdlets are listed in the next section.

Common Windows PowerShell parameters

All Windows PowerShell cmdlets support common parameters. Each of the common parameters also permits the use of an alias for the parameter. The aliases for each parameter appear in parentheses behind the parameter name in the following lists.

  • Verbose (vb)
  • Debug (db)
  • WarningAction (wa)
  • WarningVariable (wv)
  • ErrorAction (ea)
  • ErrorVariable (ev)
  • OutVariable (ov)
  • OutBuffer (ob)

If a Windows PowerShell cmdlet changes system state (such as stopping a process or changing the startup value of a service), the following two additional parameters become available:

  • WhatIf (wi)
  • Confirm (cf)

Using the Verbose parameter

As an example of using a Windows PowerShell common parameter, we can use the –Verbose parameter to obtain additional information about the action that a cmdlet performs. The following command stops all instances of the Notepad.exe process running on the local system, and there is no output from the command:

PS C:\> Stop-Process -Name notepad
PS C:\>

To see what processes stop in response to the Stop-Process cmdlet, use the –Verbose common parameter. In the following example, two separate Notepad.exe processes stop in response to the Stop-Process cmdlet. Because the cmdlet uses the –Verbose common parameter, detailed information about each process appears in the output.

PS C:\> Stop-Process -Name notepad -Verbose
VERBOSE: Performing operation "Stop-Process" on Target "notepad (5564)".
VERBOSE: Performing operation "Stop-Process" on Target "notepad (5924)".
PS C:\>

Using the ErrorAction parameter

When you use the Stop-Process cmdlet to stop a process, if there is not an instance of the specified process running, a nasty error message displays on the Windows PowerShell console. In the following example, the Stop-Process cmdlet attempts to stop a process named notepad.exe, but there are no instances of the notepad.exe process running. Therefore, an error message displays as follows:

PS C:\> Get-Process -Name notepad
Get-Process : Cannot find a process with the name "notepad". Verify the process
name and call the cmdlet again.
At line:1 char:1
+ Get-Process -Name notepad
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (notepad:String) [Get-Process], Proce
   ssCommandException
    + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Comma
   nds.GetProcessCommand

PS C:\>

If you know (or at least suspect), that a process is not running, but you would like to verify this, you can use the –ErrorAction common parameter. To hide error messages arising from the Get-Process cmdlet, supply a value of SilentlyContinue for the –ErrorAction parameter prior to running the cmdlet. This technique is shown here:

PS C:\> Get-Process -Name notepad -ErrorAction SilentlyContinue
PS C:\>

Note  The previous command appears to be really long, but keep in mind that Tab expansion makes this easy to type correctly. In fact, the previous command is:

Get-Pro<tab><space>-n<tab><space>notepad<space>-e<tab><space>s<tab>

          You can use the parameter alias –EA instead of typing –ErrorAction (although with Tab expansion,
          it is exactly the same number of keystrokes to shorten the command):

 –E<tab> or –EA

In addition, when you work with the Get-Process cmdlet, the default parameter set is Name. This means that the –Name parameter from Get-Process is the default parameter; and therefore, Get-Process interprets any string in the first position as the name of a process. The revised command is shown here:

PS C:\> Get-Process notepad -ea SilentlyContinue

PS C:\>

If you are not certain about valid values for the –ErrorAction parameter, you can supply anything to the parameter and then carefully read the resulting error message. In the text of the error message, the first two lines state that Windows PowerShell is unable to convert the value to the System.Management.Automation.ActionPreference type. The fourth line of the error message lists allowed values for the –ErrorAction parameter. The allowed values are SilentlyContinue, Stop, Continue, Inquire, and Ignore. This technique of forcing an error message is shown in the following image:

Image of error message

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy