This post will show you how you can use PSScriptAnalyzer to analyze whether your PowerShell scripts or functions confirm with industry best practices or not.
PSScriptAnalyzer (PSSA going forward) is a static code analyzer that checks your PowerShell scripts, modules, functions and gives a detailed report on any rule/rules that the scripts or modules are not conforming to.
PSSA is a tool developed by Microsoft that can be downloaded and installed from the PowerShell gallery using the
Install-Module -Name PSScriptAnalyzer
cmdlet. As of this writing, there are 51 rules that have been created as per the best practices being followed in the industry for PowerShell scripts. You can view these rules using the Get-ScriptAnalyzerRule cmdlet as shown below. You can use Out-GridView for seeing the rules more clearly. Note that, this cmdlet is available only after you install the PSScriptAnalyzer Module.
Get-ScriptAnalyzerRule | Out-GridView
You will see the output as shown below.
All these rules will be validated against the file(s) that you want to analyze.
To analyze a file or set of files, you can use the
Invoke-ScriptAnalyzer -Path [<Path(s)_to_Script>] | Out-GridView
cmdlet. I prefer to use the Out-GridView just for getting the output in a more clear way. You can choose to include or exclude it. You will see the output of a sample script as shown below.
As you can see, the analyzer gives out a clear report about all the violations currently present in my script with a detailed message about the issue and what I can do to resolve it. The report also shows the severity of the violation and line number in the script.
We can analyze multiple scripts at the same time by passing a folder path to the Invoke-ScriptAnalyzer cmdlet instead of the path of a single script.
Invoke-ScriptAnalyzer -Path "D:\" -Recurse
The -Recurse flag instructs the cmdlet to check and analyze scripts in sub-folders as well. You can see the complete output of all the scripts as shown below.
You can also check your scripts for a particular rule only by using the -IncludeRule parameter in the Invoke-ScriptAnalyzer cmdlet. Or you can exclude certain rules by using the -ExcludeRule parameter and passing the set of rule names to be excluded.
Invoke-ScriptAnalyzer -Path "D:\SampleScript.ps1" -IncludeRule "PSAvoidUsingWriteHost"
This would cause the script to be checked for only the PSAvoidUsingWriteHost rule. The -IncludeRule parameter accepts a string array so you can pass multiple rules to include. Separate multiple rules by a comma.
Similarly, you can pass one or more rules to exclude using the -ExcludeRule parameter which would cause the Invoke-ScriptAnalyzer cmdlet to ignore those rules.
You can also create your own Custom Rules module (it will be a .psm1 file) and specify the Invoke-ScriptAnalyzer cmdlet to use those.
You need to use the -CustomizedRulePath parameter which accepts a string array as value so you can pass one or more custom rule files. The structure of the custom rule file and how to create them is out of scope for this post. You can refer to this for details on creating custom rule file.
There are some more parameters to the Invoke-ScriptAnalyzer cmdlet like -Severity which lets us specify which severity specific rules to validate and -LoggerPath which can be used to specify paths to custom logger assemblies.
Hope this helps!