Section 2.5. Find Out What a Command Will Do Before Running It

2.5. Find Out What a Command Will Do Before Running It

MSH introduces several so-called ubiquitous parameters that are available throughout the command shell. Three important ones, -Verbose, -WhatIf, and -Confirm, tell you exactly what's going on, tell you what should be going on and check whether you'd like it to be going on (respectively) when running any MSH command. They can be used to get a better picture of how a script will perform before it is run, allowing you to verify the actions before they are performed.

Let's take a look at some of these safeguards in action.

I Wonder What This Button Does...

Picture this: You have an extensive folder structure containing a number of important files. Intermingled with these files are backups, or older versions, that really shouldn't be there. It makes sense to write a housekeeping script to walk through the structure and remove any files with a .bak extension. You've written the script and tested it on a simple (separate) test folder structure. Now you point it at the real folder and give it a whirl, only this time the results aren't quite as good as you expected. Alas, it's time to "try out" those disaster-recovery procedures. Something went wrong, but it's not entirely clear how or where. Surely there has to be a better way.

Thankfully, MSH has a few universal features that allow an administrator to ponder the "what if?" question, rather than the "what now?" question.

2.5.1. How Do I Do That?

Using the get-childitem cmdlet, it's an easy task to walk through a folder tree and pick out the files that match a certain criteria. Casting caution aside, you could pipe that output into remove-item to delete the matching files. This could remove more files than expected, however, so it's a good idea to use the -WhatIf switch to see what would happen before making any irreparable changes:

     MSH D:\MshScripts> get-childitem . *.bak -Recurse | remove-item -WhatIf     What if: Operation "Remove File" on Target "test.bak"     What if: Operation "Remove File" on Target "reports.bak"     What if: Operation "Remove File" on Target "authors.bak"     What if: Operation "Remove File" on Target "contracts.bak"     What if: Operation "Remove File" on Target "accounts.bak"

The list looks goodnone of these files should be there. Now it's time to rerun the command, this time without the -WhatIf switch, to remove the redundant files. Because this command is going to affect a large number of files, it makes sense to keep a log of the changes made in case any problems surface later. The -Verbose switch is used to instruct remove-item to explicitly report the files that it is deleting. If we so choose, it's easy to send this output into a file for record keeping:

     MSH D:\MshScripts> get-childitem -Recurse -Filter *.bak | remove-item     -Verbose     Operation "Remove File" on Target "test.bak"     Operation "Remove File" on Target "reports.bak"     Operation "Remove File" on Target "authors.bak"     Operation "Remove File" on Target "contracts.bak"     Operation "Remove File" on Target "accounts.bak"

Because these parameters are ubiquitous, they work almost anywhere and with many different cmdlets. Suppose we have a number of open Internet Explorer windows and would like to close a couple of them. We can build a pipeline that will send all IEXPLORE instances to stop-process, but this time we'll use the -Confirm switch to ensure we only close those processes that we've finished using:

     MSH D:\MshScripts> get-process iexplore | stop-process -Confirm     Continue with this operation?     Operation "stop-process" on Target "iexplore (316)"     [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help     (default is "Y"):y     Confirm     Continue with this operation?     Operation "stop-process" on Target "iexplore (2176)"     [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help     (default is "Y"):y

2.5.2. What Just Happened?

The -WhatIf, -Verbose, and -Confirm options can change the behavior of the cmdlets to which they're applied. As a cmdlet receives an object from the pipeline, it may do either more or fewer actions, depending on the object type, the cmdlet, and the presence of these options.

It's important to realize that while these options are suggested standards, they are not enforced or tested by MSH. Cmdlet and script authors are expected to respect these options if they are present, and most standard cmdlets treat them as described in this section.

However, when starting to use a new or unfamiliar cmdlet, it is a good idea to check that the cmdlet author's definition of -WhatIf aligns with your own.

-WhatIf can be used safely in almost all cases, as it explicitly tells the cmdlet to report what it would do without making any real changes. It's often convenient to redirect the output of a -WhatIf test to a file for review before committing any changes to disk, the registry, or other persistent store.

-Verbose provides detailed information about the operation of a cmdlet and is useful for storing a log of the script's activity. By itself, this log cannot be used to undo changes, but it may be invaluable at a later date as an aid to data recovery or process auditing.

-Confirm allows a manual go/no-go decision for each step in the process. Of course, if a script is going to be processing tens of thousand of items, it may be more economical to inspect the output of -WhatIf and make any changes to the script or underlying store if the behavior isn't perfect. With that said, -Confirm can be useful in cases where a smaller set of items is being processed or in instances where accidental execution of a command can have severe consequences.

2.5.3. What About...

...Using multiple ubiquitous parameters on the same command? Although it is permissible to include both -WhatIf and -Confirm switches on the same command, it's not recommended. The switches are all interrelated in their purpose, so their combination results in one switch overriding another. For example, when both -WhatIf and -Verbose are used, -Verbose is effectively ignored because the -WhatIf switch generates equivalent output. Likewise, when -WhatIf and -Confirm are combined, the explicit yes/no questions of -Confirm will still be raised and an affirmative response will commit a change.

Can you apply this behavior across all cmdlets? Yes. The $WhatIfPreference and $ConfirmPreference variables can be used to change the default settings of the -WhatIf and -Confirm options for those cmdlets that support them.

...Are there any other ubiquitous parameters? MSH cmdlets often support a number of other parameters that all serve different purposes. The -? option is available universally and is equivalent to invoking get-help on the cmdlet name.