Home ISESteroids Documentation Code Compatibility

Code Compatibility

Here is one line of code. It searches for all files with extension *.log anywhere in your windows folder, and ignores errors like denied access.

Will this line run? Will it run on production machines? What do you think?

Get-⁠ChildItem -⁠Path $env:windir -⁠Filter *.log -⁠Recurse -⁠ErrorAction SilentlyContinue -⁠File

The answer is: you don’t know. It may run fine, but it could also break.  It depends on a variety of circumstances: what is the PowerShell version this command runs on? Which modules are installed?

Now this was just one line. Now consider a 1000+ lines production script. How do you know its requirements to safely deploy it?

ISESteroids automatically checks compatibility in the background, and adds adornments for issues found. The line from above may look like this in ISESteroids:

Compatibility Check

You immediately discover that the parameter -File was added in PowerShell 3, so if your script still targets PowerShell 2, you know that you need to find another way to filter files, and cannot use the parameter -File.

Setting Compatibility Target

Set the PowerShell version(s) you need to target: in the menu, choose “Compatibility / Set PowerShell Target”. ISESteroids reports only issues that violate your desired target range.

Select PowerShell Target(s)

Discovering Compatibility Issues

ISESteroids adds adornments to language elements, commands, and parameters if they are unavailable in one of the PowerShell versions you specified (see “Setting Compatibility Target”).

In the PSSharper Bar, you can also click on “Compats”. The PSSharper Addon opens and shows all compatibility-related issues:

List of Compatibility Issues

Creating Compatibility Reports

Choose the menu “Compatibility / Create Compatibility Report” to get a more comprehensive report, also including commands that depend on external modules not shipping with PowerShell:

Compatibility Report

This menu command actually just executes this line:

PS C:\> Get-⁠SteroidsCompatibilityReport -⁠MinimumPSVersion 1.0 -⁠MaximumPSVersion 5.1 -⁠IncludeDependencies Out-⁠GridView -⁠Title 'Compatibility Report'

You can use Get-SteroidsCompatibilityReport to output compatibility issues as objects, drill into them, and derive your own much more sophisticated reporting tools.

Adding/Updating #requires Statement

To better understand what the requirements for a script are, PowerShell uses the statement #requires which needs to be the first element in a script.

ISESteroids autogenerates and updates this statement for you. Just choose the menu “Compatibility / Add/Update #Requires Statement”, or press CTRL+ALT+R. The compatibility requirements are calculated, the required PowerShell version as well as all required modules and snapins are determined, and then ISESteroids adds a new (or updates an existing) #requires statement.

new requires statement

Always use #requires!

Professional scripts should always have a #requires statement. Not only will this let others quickly know what the requirements are.

In addition, PowerShell refuses to run the script if the requirements are not met. This is crucial so that your script does not start, perform changes, and in the middle of it runs into errors caused by missing commands or unsupported parameters.

It’s always better not to run a script at all than to have it stall in the middle of configurations, leaving you in an indetermined state.