To learn more about this book, visit Microsoft Learning at http://www.microsoft.com/mspress/books/9541.aspx
Table of Contents Acknowledgments............................................................ xvii Introduction................................................................. xix Is This Book for Me?...................................................... xix About the Companion CD.................................................. xx System Requirements..................................................... xxi Technical Support........................................................ xxi 1 The Shell in Windows PowerShell..................................1 Installing Windows PowerShell.............................................. 1 Verifying Installation with VBScript...................................... 1 Deploying Windows PowerShell........................................ 2 Interacting with the Shell................................................... 3 Introducing Cmdlets....................................................... 5 Configuring Windows PowerShell........................................... 6 Creating a Windows PowerShell Profile.................................. 6 Configuring Windows PowerShell Startup Options........................ 6 Security Issues with Windows PowerShell..................................... 7 Controlling the Execution of Cmdlets................................... 7 Confirming Commands............................................... 9 Suspending Confirmation of Cmdlets.................................. 10 Supplying Options for Cmdlets............................................. 11 Working with Get-Help................................................... 12 Working with Aliases to Assign Shortcut Names to Cmdlets.................... 15 Additional Uses of Cmdlets................................................ 16 Using the Get-ChildItem Cmdlet....................................... 17 Formatting Output.................................................. 17 Using the Get-Command Cmdlet...................................... 24 What do you think of this book? We want to hear from you! Microsoft is interested in hearing your feedback so we can continually improve our books and learning resources for you. To participate in a brief online survey, please visit: www.microsoft.com/learning/booksurvey/ vii
viii Table of Contents Exploring with the Get-Member Cmdlet................................ 27 Summary............................................................... 31 2 Scripting Windows PowerShell.................................. 33 Why Use Scripting?...................................................... 33 Configuring the Scripting Policy........................................... 36 Running Windows PowerShell Scripts....................................... 39 Use of Variables.......................................................... 39 Use of Constants......................................................... 40 Using Flow Control Statements............................................ 41 Adding Parameters to ForEach-Object................................. 42 Using the Begin Parameter........................................... 42 Using the Process Parameter.......................................... 43 Using the End Parameter............................................. 43 Using the For Statement.................................................. 43 Using Decision-Making Statements......................................... 44 Using If Elseif Else............................................... 45 Using Switch........................................................ 46 Working with Data Types................................................. 49 Unleashing the Power of Regular Expressions................................ 53 Using Command-Line Arguments.......................................... 56 Summary............................................................... 58 3 Managing Logs............................................... 59 Identifying the Event Logs................................................ 59 Reading the Event Logs................................................... 60 Exporting to Text.................................................... 61 Export to XML...................................................... 62 Perusing General Log Files................................................ 64 Examining Multiple Logs............................................. 65 Retrieving a Single Event Log Entry.................................... 66 Searching the Event Log.................................................. 68 Filtering on Properties............................................... 69 Selecting the Source................................................. 69 Selecting the Severity................................................ 70 Selecting the Message............................................... 70
Table of Contents ix Managing the Event Log.................................................. 71 Identifying the Sources............................................... 71 Modifying the Event Log Settings...................................... 71 Examining WMI Event Logs................................................ 75 Making Changes to the WMI Logging Level............................. 76 Using the Windows Event Command-Line Utility........................ 76 Writing to Event Logs..................................................... 77 Creating a Source................................................... 77 Putting Cmdlet Output into the Log................................... 78 Creating Your Own Event Logs............................................. 79 Summary................................................................ 80 4 Managing Services............................................ 81 Documenting the Existing Services......................................... 81 Working with Running Services....................................... 82 Writing to a Text File................................................. 83 Writing to a Database................................................ 85 Setting the Service Configuration........................................... 94 Accepting Command-Line Arguments................................. 97 Stopping Services................................................... 97 Performing a Graceful Stop........................................... 99 Starting Services................................................... 101 Performing a Graceful Start.......................................... 102 Desired Configuration Maintenance....................................... 107 Verifying Desired Services Are Stopped................................ 108 Reading a File to Check Service Status................................. 109 Verifying Desired Services Are Running................................ 110 Confirming the Configuration............................................. 110 Producing an Exception Report........................................... 111 Summary............................................................... 113 5 Managing Shares............................................. 115 Documenting Shares..................................................... 115 Documenting User Shares........................................... 122 Writing Shares to Text............................................... 125 Documenting Administrative Shares.................................. 126 Writing Share Information to a Microsoft Access Database............... 126
x Table of Contents Auditing Shares......................................................... 130 Modifying Shares....................................................... 133 Using Parameters with the Script..................................... 134 Translating the Return Code......................................... 135 Creating New Shares.................................................... 137 Creating Multiple Shares................................................. 141 Deleting Shares......................................................... 143 Deleting Only Unauthorized Shares....................................... 145 Summary.............................................................. 146 6 Managing Printing........................................... 147 Inventorying Printers.................................................... 147 Querying Multiple Computers....................................... 148 Logging to a File................................................... 150 Writing to a Microsoft Access Database............................... 152 Reporting on Printer Ports............................................... 157 Identifying Printer Drivers................................................ 163 Installing Printer Drivers................................................. 165 Installing Printer Drivers Found on Your Computer..................... 165 Installing Printer Drivers Not Found on Your Computer................. 167 Summary.............................................................. 169 7 Desktop Maintenance........................................ 171 Maintaining Desktop Health.............................................. 171 Inventorying Drives................................................ 171 Writing Disk Drive Information to Microsoft Access..................... 175 Working with Partitions............................................. 179 Matching Disks and Partitions....................................... 181 Working with Logical Disks.......................................... 184 Monitoring Disk Space Utilization......................................... 188 Logging Disk Space to a Database.................................... 192 Monitoring File Longevity........................................... 196 Monitoring Performance................................................. 199 Using Performance Counter Classes.................................. 200 Identifying Sources of Page Faults.................................... 204 Summary.............................................................. 204
Table of Contents xi 8 Networking................................................. 207 Working with Network Settings........................................... 207 Reporting Networking Settings....................................... 207 Working with Adapter Configuration.................................. 212 Filtering Only Properties that Have a Value............................ 218 Configuring Network Adapter Settings..................................... 223 Detecting Multiple Network Adapters................................. 223 Writing Network Adapter Information to a Microsoft Excel Spreadsheet... 224 Identifying Connected Network Adapters.............................. 228 Setting Static IP Address............................................. 230 Enabling DHCP..................................................... 235 Configuring the Windows Firewall......................................... 239 Reporting Firewall Settings.......................................... 240 Configuring Firewall Settings......................................... 241 Summary............................................................... 243 9 Configuring Desktop Settings.................................. 245 Working with Desktop Configuration Issues................................. 245 Setting Screen Savers.................................................... 245 Auditing Screen Savers.............................................. 246 Listing Only Properties with Values................................... 252 Reporting Secure Screen Savers...................................... 256 Managing Desktop Power Settings........................................ 263 Changing the Power Scheme............................................. 269 Summary............................................................... 275 10 Managing Post-Deployment Issues............................. 277 Setting the Time........................................................277 Setting the Time Remotely........................................... 278 Logging Results to the Event Log..................................... 283 Configuring the Time Source............................................. 289 Using the Net Time Command....................................... 290 Querying the Registry for the Time Source............................. 292 Enabling User Accounts.................................................. 297 Creating a Local User Account............................................ 303 Creating a Local User............................................... 303 Creating a Local User Group......................................... 306
xii Table of Contents Configuring the Screen Saver............................................. 309 Renaming the Computer................................................. 316 Shutting Down or Rebooting a Remote Computer........................... 319 Summary.............................................................. 323 11 Managing User Data.......................................... 325 Working with Backups................................................... 325 Configuring Offline Files................................................. 328 Enabling the Use of Offline Files.......................................... 331 Working with System Restore............................................. 340 Retrieving System Restore Settings................................... 340 Listing Available System Restore Points................................ 344 Summary.............................................................. 347 12 Troubleshooting Windows.................................... 349 Troubleshooting Startup Issues........................................... 349 Examining the Boot Configuration................................... 349 Examining Startup Services.......................................... 352 Displaying Service Dependencies......................................... 355 Examining Startup Device Drivers.................................... 360 Investigating Startup Processes...................................... 365 Investigating Hardware Issues............................................ 368 Troubleshooting Network Issues.......................................... 373 Summary.............................................................. 377 13 Managing Domain Users...................................... 379 Creating Organizational Units............................................ 379 Creating Domain Users.................................................. 382 Modifying User Attributes................................................ 385 Modifying General User Information.................................. 386 Modifying the Address Tab.......................................... 387 Modifying the Profile Tab........................................... 388 Modifying the Telephone Tab........................................ 389 Modifying the Organization Tab..................................... 389 Modifying a Single User Attribute.................................... 390 Creating Users from a.csv File............................................ 393 Setting the Password............................................... 394 Enabling the User Account.......................................... 394
Table of Contents xiii Creating Domain Groups................................................. 395 Adding a User to a Domain Group......................................... 398 Adding Multiple Users with Multiple Attributes.............................. 400 Summary............................................................... 404 14 Configuring the Cluster Service................................ 405 Examining the Clustered Server........................................... 405 Reporting Cluster Configuration...................................... 411 Reporting Node Configuration....................................... 416 Querying Multiple Cluster Classes.................................... 420 Managing Nodes........................................................ 431 Adding and Evicting Nodes.......................................... 431 Removing the Cluster............................................... 437 Summary............................................................... 442 15 Managing Internet Information Services........................ 443 Enabling Internet Information Services Management........................ 443 Reporting IIS Configuration............................................... 445 Reporting Site Information.......................................... 445 Reporting on Application Pools...................................... 447 Reporting on Application Pool Default Values.......................... 451 Reporting Site Limits................................................ 454 Listing Virtual Directories............................................ 457 Creating a New Web Site................................................. 459 Creating a New Application Pool.......................................... 464 Starting and Stopping Web Sites.......................................... 467 Summary............................................................... 471 16 Working with the Certificate Store............................. 473 Locating Certificates in the Certificate Store................................. 473 Listing Certificates.................................................. 479 Locating Expired Certificates......................................... 483 Identifying Certificates about to Expire................................ 488 Managing Certificates................................................... 492 Inspecting a Certificate.............................................. 492 Importing a Certificate.............................................. 497 Deleting a Certificate............................................... 501 Summary............................................................... 507
xiv Table of Contents 17 Managing the Terminal Services Service......................... 509 Configuring the Terminal Service Installation............................... 509 Documenting Terminal Service Configuration.......................... 509 Disabling Logons.................................................. 513 Modifying Client Properties......................................... 517 Managing Users........................................................ 521 Enabling Users to Access the Server.................................. 524 Configuring Client Settings.......................................... 527 Summary.............................................................. 539 18 Configuring Network Services................................. 541 Reporting DNS Settings.................................................. 541 Configuring DNS Logging Settings................................... 548 Reporting Root Hints............................................... 556 Querying A Records............................................... 557 Configuring DNS Server Settings.......................................... 562 Reporting DNS Zones................................................... 568 Creating DNS Zones..................................................... 571 Managing WINS and DHCP.............................................. 576 Summary.............................................................. 581 19 Working with Windows Server 2008 Server Core................. 583 Initial Configuration..................................................... 583 Joining the Domain................................................ 584 Setting the IP Address.............................................. 592 Configuring the DNS Settings........................................ 597 Renaming the Server............................................... 605 Managing Windows Server 2008 Server Core............................... 611 Monitoring the Server.............................................. 611 Querying Event Logs............................................... 614 Summary.............................................................. 617 A Cmdlet Naming Conventions.................................. 619 B ActiveX Data Object Provider Names........................... 621 C Frequently Asked Questions................................... 623
Table of Contents xv D Scripting Guidelines.......................................... 631 General Script Construction............................................... 631 Include Functions in the Script that Calls the Function................... 631 Use Full Cmdlet Names and Full Parameter Names...................... 632 Use Get-Item to Convert Path Strings to Rich Types..................... 633 General Script Readability................................................ 633 Formatting Your Code................................................... 634 Working with Functions............................................. 635 Creating Template Files.............................................. 637 Writing Functions.................................................. 637 Creating and Naming Variables and Constants......................... 638 E General Troubleshooting Tips.................................. 639 Index.................................................................... 643 What do you think of this book? We want to hear from you! Microsoft is interested in hearing your feedback so we can continually improve our books and learning resources for you. To participate in a brief online survey, please visit: www.microsoft.com/learning/booksurvey/
Chapter 1 The Shell in Windows PowerShell After completing this chapter, you will be able to: Install and configure Windows PowerShell. Tackle security issues with Windows PowerShell. Understand the basics of cmdlets. Work with aliases to assign shortcut names to cmdlets. Get help using Windows PowerShell. On the Companion Disc All the scripts used in this chapter are located on the CD-ROM that accompanies this book in the \scripts\chapter01 folder. Installing Windows PowerShell Because Windows PowerShell is not installed by default on any operating system released by Microsoft, it is important to verify the existence of Windows PowerShell on the platform before the actual deployment of either scripts or commands. This can be as simple as trying to execute a Windows PowerShell command and looking for errors. You can easily accomplish this from inside a batch file by querying the value %errorlevel%. Verifying Installation with VBScript A more sophisticated approach to the task of verifying the existence of Windows PowerShell on the operating system is to use a script that queries the Win32_QuickFixEngineering Windows Management Instrumentation (WMI) class. FindPowerShell.vbs is an example of using Win32_QuickFixEngineering in Microsoft Visual Basic Scripting Edition (VBScript) to find an installation of Windows PowerShell. The FindPowerShell.vbs script uses the WMI moniker to create an instance of the SwbemServices object and then uses the execquery method to issue the query. The WMI Query Language (WQL) query uses the like operator to retrieve hotfixes with a hotfix ID such as 928439, which is the hotfix ID for Windows PowerShell on Windows XP, Windows Vista, Windows Server 2003, and Windows Server 2008. Once the hotfix is identified, the script simply prints out the name of the computer stating that Windows PowerShell is installed. This is shown in Figure 1-1. 1
2 Windows PowerShell Scripting Guide Figure 1-1 The FindPowerShell.vbs script displays a pop-up box indicating that Windows PowerShell has been found. If the hotfix is not found, the script indicates that Windows PowerShell is not installed. The FindPowerShell.vbs script can easily be modified to include additional functionality you may require on your specific network. For example, you may want to run the script against multiple computers. To do this, you can turn strcomputer into an array and type in multiple computer names. Or, you can read a text file or perform an Active Directory directory service query to retrieve computer names. You could also log the output from the script rather than create a pop-up box. FindPowerShell.vbs Const RtnImmedFwdOnly = &h30 strcomputer = "." wmins = "\root\cimv2" wmiquery = "Select * from win32_quickfixengineering where hotfixid like '928439'" Set objwmiservice = GetObject("winmgmts:\\" & strcomputer & wmins) Set colitems = objwmiservice.execquery(wmiquery,,rtnimmedfwdonly) For Each objitem in colitems Wscript.Echo "PowerShell is present on " & objitem.csname Wscript.quit Next Wscript.Echo PowerShell is not installed Deploying Windows PowerShell Once Windows PowerShell is downloaded from http://www.microsoft.com/downloads, you can deploy Windows PowerShell in your environment by using any of the standard methods you currently use. A few of the methods customers use to deploy Windows PowerShell follow: Create a Microsoft Systems Management Server (SMS) package and advertise it to the appropriate organizational unit (OU) or collection. Create a Group Policy Object (GPO) in Active Directory and link it to the appropriate OU. Call the executable by using a logon script. If you are not deploying to an entire enterprise, perhaps the easiest way to install Windows PowerShell is to simply double-click the executable and step through the wizard.
Chapter 1 The Shell in Windows PowerShell 3 Keep in mind that Windows PowerShell is installed by using hotfix technology. This means it is an update to the operating system, and not an add-on program. This has certain advantages, including the ability to provide updates and fixes to Windows PowerShell through operating system service packs and through Windows Update. But there are also some drawbacks, in that hotfixes need to be uninstalled in the same order that they were installed. For example, if you install Windows PowerShell on Windows Vista and later install a series of updates, then install Service Pack 1, and suddenly decide to uninstall Windows PowerShell, you will need to back out Service Pack 1 and each hotfix in the appropriate order. (Personally, at that point I think I would just back up my data, format the disks, and reinstall Windows Vista. I think it would be faster. But all this is a moot point anyway, as there is little reason to uninstall Windows PowerShell.) Understanding Windows PowerShell One issue with Windows PowerShell is grasping what it is. In fact, the first time I met Jeffrey Snover, the chief architect for Windows PowerShell, one of the first things he said was, How do you describe Windows PowerShell to customers? So what is Windows PowerShell? Simply stated, Windows PowerShell is the next generation command shell and scripting language from Microsoft that can be used to replace both the venerable Cmd.exe command interpreter and the VBScript scripting language. This dualistic behavior causes problems for many network administrators who are used to the Cmd.exe command interpreter with its weak batch language and the powerful (but confusing) VBScript language for automating administrative tasks. These are not bad tools, but they are currently used in ways that were not intended when they were created more than a decade ago. The Cmd.exe command interpreter was essentially the successor to the DOS prompt, and VBScript was more or less designed with Web pages in mind. Neither was designed from the ground up for network administrators. Interacting with the Shell Once Windows PowerShell is launched, you can use it in the same manner as the Cmd.exe command interpreter. For example, you can use dir to retrieve a directory listing. You can also use cd to change the working directory and then use dir to produce a directory listing just as you would perform these tasks from the CMD shell. This is illustrated in the UsingPower- Shell.txt example that follows, which shows the results of using these commands. UsingPowerShell.txt PS C:\Users\edwils> dir Directory: Microsoft.PowerShell.Core\FileSystem::C:\Users\edwils
4 Windows PowerShell Scripting Guide Mode LastWriteTime Length Name ---- ------------- ------ ---- d-r-- 11/29/2006 1:32 PM Contacts d-r-- 4/2/2007 12:51 AM Desktop d-r-- 4/1/2007 6:53 PM Documents d-r-- 11/29/2006 1:32 PM Downloads d-r-- 4/2/2007 1:10 AM Favorites d-r-- 4/1/2007 6:53 PM Links d-r-- 11/29/2006 1:32 PM Music d-r-- 11/29/2006 1:32 PM Pictures d-r-- 11/29/2006 1:32 PM Saved Games d-r-- 4/1/2007 6:53 PM Searches d-r-- 4/2/2007 5:53 PM Videos PS C:\Users\edwils> cd music PS C:\Users\edwils\Music> dir In addition to using traditional command interpreter commands, you can also use some of the newer command-line utilities such as Fsutil.exe, as shown here. Keep in mind that access to Fsutil.exe requires administrative rights. If you launch the standard Windows PowerShell prompt from the Windows PowerShell program group, you will not have administrative rights, and the error shown in Figure 1-2 will appear. Figure 1-2 Windows PowerShell respects user account control and by default will launch with normal user privileges. This can generate errors when trying to execute privileged commands. Fsutil.txt PS C:\Users\edwils> sl c:\mytest PS C:\mytest> fsutil file createnew c:\mytest\mynewfile.txt 1000 File c:\mytest\mynewfile.txt is created PS C:\mytest> dir Directory: Microsoft.PowerShell.Core\FileSystem::C:\mytest Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 5/8/2007 7:30 PM 1000 mynewfile.txt PS C:\mytest>
Chapter 1 The Shell in Windows PowerShell 5 Tip I recommend creating two Windows PowerShell shortcuts and saving them to the Quick Launch bar. One shortcut launches with normal user permissions and the other launches with administrative rights. By default you should use the normal user shortcut and document those occasions that require administrative rights. When you are finished working with the files and the folder, you can delete the file very easily by using the del command. To keep from typing the entire file name, you can use wildcards such as *.txt. This is safe enough, since you have first used the dir command to ensure there is only one text file in the folder. Once the file is removed, you can use rd to remove the directory. As shown in DeleteFileAndFolder.txt example that follows, these commands work exactly the same as you would expect when working with the command prompt. DeleteFileAndFolder.txt PS C:\> sl c:\mytest PS C:\mytest> dir Directory: Microsoft.PowerShell.Core\FileSystem::C:\mytest Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 5/8/2007 7:30 PM 1000 mynewfile.txt PS C:\mytest> del *.txt PS C:\mytest> cd c:\ PS C:\> rd c:\mytest PS C:\> dir c:\mytest Get-ChildItem : Cannot find path 'C:\mytest' because it does not exist. At line:1 char:4 + dir <<<< c:\mytest PS C:\> With these examples, you have been using Windows PowerShell in an interactive manner. This is one of the primary uses of Windows PowerShell. In fact, the Windows PowerShell team expects that 80 percent of users will work with Windows PowerShell interactively simply as a better command prompt. You open up a Windows PowerShell prompt and type in commands. The commands can be typed one at a time or they can be grouped together like a batch file. This will be discussed later, as the process doesn t work by default. Introducing Cmdlets In addition to using traditional programs and commands from the Cmd.exe command interpreter, you can also use the cmdlets that are built into Windows PowerShell. Cmdlet is a name created by the Windows PowerShell team to describe these native commands. They are like executable programs but because they take advantage of the facilities built into Windows
6 Windows PowerShell Scripting Guide PowerShell, they are easy to write. They are not scripts, which are uncompiled code, because they are built using the services of a special Microsoft.NET Framework namespace. Because of their different nature, the Windows PowerShell team came up with the new term cmdlet. Windows PowerShell comes with more than 120 cmdlets designed to assist network administrators and consultants to easily take advantage of Windows PowerShell without having to learn the Windows PowerShell scripting language. These cmdlets are documented in Appendix A, Cmdlet Naming Conventions. In general, the cmdlets follow a standard naming convention such as Get-Help, Get-EventLog, or Get-Process. The get cmdlets display information about the item that is specified on the right side of the dash. The set cmdlets are used to modify or to set information about the item on the right side of the dash. An example of a set cmdlet is Set-Service, which can be used to change the startmode of a service. An explanation of this naming convention is found in Appendix A, Cmdlet Naming Conventions. Configuring Windows PowerShell Once Windows PowerShell is installed on a platform, there are still some configuration issues to address. This is in part due to the way the Windows PowerShell team at Microsoft perceives the use of the tool. For example, the Windows PowerShell team believes that 80 percent of Windows PowerShell users will not utilize the scripting features of Windows PowerShell; thus, the scripting capability is turned off by default. Find more information on enabling scripting support in Windows Power Shell in Chapter 2, Scripting Windows PowerShell. Creating a Windows PowerShell Profile There are many settings that can be stored in a Windows PowerShell profile. These items can be stored in a psconsole file. To export the console configuration file, use the Export-Console cmdlet as shown here: PS C:\> Export-Console myconsole The psconsole file is saved in the current directory by default, and will have an extension of.psc1. The psconsole file is saved in an.xml format; a generic console file is shown here: <?xml version="1.0" encoding="utf-8"?> <PSConsoleFile ConsoleSchemaVersion="1.0"> <PSVersion>1.0</PSVersion> <PSSnapIns /> </PSConsoleFile> Configuring Windows PowerShell Startup Options There are several methods available to start Windows PowerShell. For example, if the logo you receive when clicking the default Windows PowerShell icon seems to get in your way, you can launch without it. You can start Windows PowerShell using different profiles and even run a
Chapter 1 The Shell in Windows PowerShell 7 single Windows PowerShell command and exit the shell. If you need to start a specific version of Windows PowerShell, you can do that as well by supplying a value for the version parameter. Each of these options is illustrated in the following list. Launch Windows PowerShell without the banner by using the -nologo argument as shown here: PowerShell -nologo Launch a specific version of Windows PowerShell by using the -version argument: PowerShell -version 1.0 Launch Windows PowerShell using a specific configuration file by specifying the -psconsolefile argument: PowerShell -psconsolefile myconsole.psc1 Launch Windows PowerShell, execute a specific command, and then exit by using the -command argument. The command must be prefixed by the ampersand sign and enclosed in curly brackets: powershell -command "& {get-process}" Security Issues with Windows PowerShell As with any tool as versatile as Windows PowerShell, there are some security concerns. Security, however, was one of the design goals in the development of Windows PowerShell. When you launch Windows PowerShell, it opens in your Users\userName folder; this ensures you are in a directory where you will have permission to perform certain actions and activities. This technique is far safer than opening at the root of the drive or opening in the system root. To change to a directory, you can t automatically go up to the next level; you must explicitly name the destination of the change directory operation (but you can use the dotted notation with the Set-Location cmdlets as in Set-Location..). Running scripts is disabled by default but this can be easily managed with Group Policy or login scripts. Controlling the Execution of Cmdlets Have you ever opened a CMD interpreter prompt, typed in a command, and pressed Enter so you could see what happens? If that command happens to be Format C:\, are you sure you want to format your C drive? There are several arguments that can be passed to cmdlets to control the way they execute. These arguments will be examined in this section.
8 Windows PowerShell Scripting Guide Tip Most of the Windows PowerShell cmdlets support a prototype mode that can be entered by using the -whatif parameter. The implementation of the whatif switch can be decided by the person developing the cmdlet; however, the Windows PowerShell team recommends that developers implement -whatif if the cmdlet will make changes to the system. Although not all cmdlets support these arguments, most of the cmdlets included with Windows PowerShell do. The three ways to control execution are -whatif, -confirm, and suspend. Suspend is not an argument that gets supplied to a cmdlet, but it is an action you can take at a confirmation prompt, and is therefore another method of controlling execution. To use -whatif, first enter the cmdlet at a Windows PowerShell prompt. Then type the -whatif parameter after the cmdlet. The use of the -whatif argument is illustrated in the following WhatIf.txt example. On the first line, launch Notepad. This is as simple as typing the word notepad as shown in the path. Next, use the Get-Process cmdlet to search for all processes that begin with the name note. In this example, there are two processes with a name beginning with notepad. Next, use the Stop-Process cmdlet to stop a process with the name of notepad, but because the outcome is unknown, use the -whatif parameter. Whatif tells you that it will kill two processes, both of which are named notepad, and it also gives the process ID number so you can verify if this is the process you wish to kill. Just for fun, once again use the Stop- Process cmdlet to stop all processes with a name that begins with the letter n. Again, wisely use the whatif parameter to see what would happen if you execute the command. WhatIf.txt PS C:\Users\edwils> notepad PS C:\Users\edwils> Get-Process note* Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 45 2 1044 3904 53 0.03 3052 notepad 45 2 1136 4020 54 0.05 3140 notepad PS C:\Users\edwils> Stop-Process -processname notepad -WhatIf What if: Performing operation "Stop-Process" on Target "notepad (3052)". What if: Performing operation "Stop-Process" on Target "notepad (3140)". PS C:\Users\edwils> Stop-Process -processname n* -WhatIf What if: Performing operation "Stop-Process" on Target "notepad (3052)". What if: Performing operation "Stop-Process" on Target "notepad (3140)". So what happens if the whatif switch is not implemented? To illustrate this point, notice that in the following WhatIf2.txt example, when you use the New-Item cmdlet to create a new directory named mynewtest off the root, the whatif switch is implemented and it confirms that the command will indeed create C:\myNewtest. Note what happens, however, when you try to use the whatif switch on the Get-Help cmdlet. You might guess it would display a message such as, What if: Retrieving help information for
Chapter 1 The Shell in Windows PowerShell 9 Get-Process cmdlet. But what is the point? As there is no danger with the Get-Help cmdlet, there is no need to implement whatif on Get-Help. WhatIf2.txt PS C:\Users\edwils> New-Item -Name mynewtest -Path c:\ -ItemType directory -WhatIf What if: Performing operation "Create Directory" on Target "Destination: C:\myNewTest". PS C:\Users\edwils> get-help Get-Process -whatif Get-Help : A parameter cannot be found that matches parameter name 'whatif'. At line:1 char:28 + get-help Get-Process -whatif <<<< Best Practices The use of the -whatif parameter should be considered an essential tool in the network administrator s repertoire. Using it to model commands before execution can save hours of work each year. Confirming Commands As you saw in the previous section, you can use -whatif to create a prototype cmdlet in Windows PowerShell. This is useful for checking what a command will do. However, to be prompted before the command executes, use the -confirm switch. In practice, using the -confirm switch can generally take the place of -whatif, as you will be prompted before the action occurs. This is shown in the ConfirmIt.txt example that follows. In the ConfirmIt.txt file, first launch Calculator (Calc.exe). Because the file is in the path, you don t need to hard-code either the path or the extension. Next, use Get-Process with the c* wildcard pattern to find all processes that begin with the letter c. Notice that there are several process names on the list. The next step is to retrieve only the Calc.exe process. This returns a more manageable result set. Now use the Stop-Process cmdlet with the -confirm switch. The cmdlet returns the following information: Confirm Are you sure you want to perform this action? Performing operation "Stop-Process" on Target "calc (2924)". [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): You will notice this information is essentially the same as the information provided by the whatif switch but it also provides the ability to perform the requested action. This can save time when executing a large number of commands. ConfirmIt.txt PS C:\Users\edwils> calc PS C:\Users\edwils> Get-Process c*