PSScriptAnalyzer deep dive – Part 2 of 4

Doctor Scripto

Summary: Thomas Rayner, Microsoft Cloud and Datacenter Management MVP, shows how to suppress, include, and exclude PSScriptAnalyzer rules.

Hello! I’m Thomas Rayner, a Cloud and Datacenter Management Microsoft MVP, filling in for The Scripting Guy this week. You can find me on Twitter (@MrThomasRayner), or posting on my blog, workingsysadmin.com. This week, I’m presenting a four-part series about how to use PSScriptAnalyzer.

Part 1 – Getting started with PSScriptAnalyzer

Part 2 – Suppressing, including, excluding rules

Part 3 – Wrapping PSScriptAnalyzer with Pester to get formatted results

Part 4 – Writing custom rules

This is Part 2, so I’m going to show you how to specifically suppress, include, or exclude certain rules.

Suppressing a rule refers to using special code that’s intermingled with your PowerShell code to tell PSScriptAnalyzer (PSSA) that you don’t want it to check a portion of your code against a specific rule. Including or excluding rules refers to the set of rules that you want to check your entire module or script against.

The ReadMe.md file on the PSScriptAnalyzer GitHub page has a lot of great information about suppressing rules, so I’ll only explain it briefly before I show you how to include or exclude only certain rules.

Check out this code example:

param (

[Parameter()] [ValidateSet('Yes', 'No', 'Maybe')] [string]$UsePassword

)

Write-Output "Using a password: $UsePassword"

This script is clearly useless, but it’s an example where I have a parameter name that contains “Password”. Let’s see what PSSA says about that.

PSSA says that I shouldn’t have parameters that take passwords in plain text. The recommended practice for sending passwords to parameters is to either send them as part of a PSCredential object or, as recommended by PSSA, as a SecureString object. But, this script isn’t passing a password. Presumably, it’s telling another part of the script whether it’s using a password or not and, as far as we can tell from this context, it’s totally safe.

In this example, I know that I can safely ignore this warning. I can use the following code to tell PSSA to ignore that rule for that parameter.

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "")]

param (

[Parameter()] [ValidateSet('Yes', 'No', 'Maybe')] [string]$UsePassword

)

Write-Output "Using a password: $UsePassword"

Now, when I run Invoke-ScriptAnalyzer, I don’t get any output, which means that PSSA doesn’t have any rule violations to notify me about.

There is a ton more to know about suppressing rules, but it’s explained well on the PSSA GitHub page, and you should read about it there.

Excluding and including rules for an entire script is a different matter, though. Let’s change up our example code. Now we’re going to look at something that might be a controller script that you run to launch other tools and work with them.

#requires -Module ActiveDirectory,AzureRm,MyCustomModule $options = @" 1. New User 2. Delete User 3. New Azure VM 4. Some Line Of Business Thing "@

Write-Host $options

$choice = Read-Host "What do you want to do?"

Write-Host "You picked $choice"

if ($choice -eq "1") {

New-CustomUser

}

This script uses Write-Host, which, if you read yesterday’s post, you know is a rule violation. This is a controller script, though. This thing is only going to be run interactively as a user sits at a console and interacts with the script. In this limited scenario, it totally makes sense to use Write-Host. Because I know that, I can tell PSSA to ignore that rule for my entire script instead of suppressing it for specific lines and scenarios.

Invoke-ScriptAnalyzer -Path .\MyScript.ps1 -ExcludeRule PSAvoidUsingWriteHost

Running this against my example code will return nothing because PSSA has no violations to report since I told it to exclude the PSAvoidUsingWriteHost rule for my whole script.

The -IncludeRule parameter works a little bit differently. When you use it, you effectively tells PSSA to exclude all rules, except the one that you explicitly include. So, if I ran this…

Invoke-ScriptAnalyzer -Path .\MyScript.ps1 -IncludeRule PSAvoidUsingWriteHost

… I would have PSSA reporting violations only about the PSAvoidUsingWriteHost rule. You can pass an array of rules and have it check only a few.

Why would you ever want that? Well, maybe your script is longer than the 16-line example that I shared earlier. It can take some time for PSSA to evaluate large scripts and modules. Perhaps you want to quickly check if your teammate removed all the aliases from a 100,000-line script like he said he did. Using -IncludeRule, you don’t have to wait for PSSA to evaluate all the other rules, too. You can quickly find out if there are any aliases in the script by checking only that rule.

Join me tomorrow, and I’ll show you how to use Pester to get differently formatted results from PSScriptAnalyzer.

Thomas, that was some excellent reading! It’s amazing how much you can use this tool to verify your own scripts!

I invite you to follow the Scripting Guys on Twitter and Facebook. If you have any questions, send email to them at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow.

Until then, always remember that with Great PowerShell comes Great Responsibility.

Sean Kearney Honorary Scripting Guy Cloud and Datacenter Management MVP

Doctor Scripto Scripter, PowerShell, vbScript, BAT, CMD

Follow