2.5. Find Out What a Command Will Do Before Running ItMSH 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.
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.
-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. |