Analyze your PowerShell code with PSScriptAnalyzer

Table of Contents

I. Introduction
II. PSScriptAnalyzer rules
III. Analyzing a script with PSScriptAnalyzer
IV. Conclusion

I. Introduction

Do you want to check whether your PowerShell script complies with best practice? If so, you should take a look at the "PSScriptAnalyser" module, as its aim is to check whether your code complies with certain writing rules and best practices.

Before reading the rest of this chapter, please note that you can install this module with this command:

Install-Module -Name PSScriptAnalyzer

You should also be aware that PSScriptAnalyzer is included in the Visual Studio Code "PowerShell" extension, which means that every PowerShell script edited with this code editor will be analyzed by this module. Nevertheless, you can use it directly from a PowerShell console to ask it to analyze a script that is not necessarily running.

II. PSScriptAnalyzer rules

The PSScriptAnalyzer module performs a static verification of your code. It contains a set of rules for evaluating the quality of PowerShell code. These rules are defined by the Microsoft PowerShell team, but also by the PowerShell community.

If you wish to obtain an exhaustive list of the verification rules defined by default, execute this command:

Get-ScriptAnalyzerRule

This command returns a list of rules - 70 in all, to be precise. There are 63 rules defined for PowerShell itself, and 7 rules defined for PowerShell DSC, a PowerShell-based configuration management solution.

Here is an overview of the result:

Here are some sample rules:

PSAvoidUsingCmdletAliases: avoid using global aliases, in order to prioritize the use of full cmdlet names.
PSAvoidExclaimOperator : avoid using the "!" character for negation, in order to prioritize the use of "-not".
PSUseCmdletCorrectly: call PowerShell cmdlets, specifying mandatory parameter names.
PSUseApprovedVerbs : check that all cmdlets used have a name containing an approved verb.
PSProvideCommentHelp : add help within PowerShell scripts, as we saw in the chapter dedicated to writing comments.
PSAvoidUsingComputerNameHardcoded : the "ComputerName" parameter of a cmdlet must not be hardcoded, as it exposes sensitive system information.
PSUseConsistentIndentation : each declaration block must have consistent indentation.
PSPlaceCloseBrace : each closing brace must be placed on a new line.
Etc....

This module will also check your code's indentation and overall syntax.

In the image above, you can see that each rule is associated with a severity level (Information, Warning, Error). To display all the rules associated with the "Error" severity type, use this syntax :

Get-ScriptAnalyzerRule -Severity Error

You can follow the same logic for other severities.

III. Analyzing a script with PSScriptAnalyzer

In the rest of this chapter, we'll be analyzing a script with PSScriptAnalyzer. The script we're going to use deliberately contains a number of syntax errors, so it doesn't follow best practice for several reasons.

Here's the code we're going to analyze, contained in the file"C:PSScriptDemo.ps1".

# List the contents of the "C:Windows" directory
ls "C:\Windows"

# Test the existence of the "C:Windows" path
if(-not(Test-Path "C:\Windows")){
   Write-Output "Ce chemin n'existe pas"    
}

Note: we haven't yet studied some of the concepts used in this code snippet, but will do so later in the course.

We will now analyze this script with PSScriptAnalyzer :

Invoke-ScriptAnalyzer -Path "C:\PsScriptDemo.ps1"

The command returns two messages:

The use of an alias on line 2. I used "ls", which is an alias for "Get-ChildItem", which is not recommended.
The presence of spaces at the end of line 6. I've deliberately included spaces at the end of the "Write-Output" command.

Now you'll need to edit the script to make any changes following this analysis. Once the modifications have been made, simply run the previous command again. Be aware that there's a parameter called"Fix" that you can use with the"Invoke-ScriptAnalyzer" cmdlet to make corrections for you, but I wouldn't recommend it. Sometimes, it tends to "break" script formatting (particularly indentation).

To customize PSScriptAnalyzer's behavior, you can not only create your own rules, but also include or exclude rules using the "IncludeRule" and "ExcludeRule" parameters followed by the rule name(s).

Microsoft Learn - PSScriptAnalyzer - Creating custom rules

In addition to using the "ScriptDemo.ps1" script, you can run the "Invoke-ScriptAnalyzer" command on any script downloaded from the Internet.

As mentioned in the introduction, PSScriptAnalyzer is natively supported in Visual Studio Code. So, if we use an alias in a script, it's immediately highlighted and VSCode, via PSScriptAnalyzer, tells us that we shouldn't use an alias.

Analyzing a PowerShell script - Via VSCode

IV. Conclusion

PSScriptAnalyzer is a handy PowerShell module, and its integration with Visual Studio Code is a big plus. When you write a script, you can get into the habit of checking it with this module to see if it corresponds to the most widespread good practices.

If you'd like to read more examples, you can read this previous article available on IT-Connect :