Summary: A new version of PSScriptAnalyzer is now available with many new features, rules, fixes and improvements.
You might remember me from my previous cross-platform remoting blog post, but just to introduce myself: I am Christoph Bergmeister, a full stack .Net developer in the London area and since the start of this year I am now also an official PSScriptAnalyzer maintainer although I do not work at Microsoft.
On GitHub, you can find me as @bergmeister.
After half a year, a new version of PSScriptAnalyzer (also known as PSSA) has been published and is now available on the PSGallery.
Some of you might have been wondering what has happened.
First, the former maintainer has switched projects, therefore it took some time for finding and arranging a hand over.
PSScriptAnalyzer is now mainly being maintained by @JamesWTruher from the Microsoft side and myself as a community maintainer.
After having already contributed to the PowerShell Core project, I started doing development on PSScriptAnalyzer last autumn and since then have added a lot of new features.
New Parameters
Invoke-ScriptAnalyzer now has 3 new switch parameters:
- -Fix (only on the -Path parameter set)
- -ReportSummary
- -EnableExit
The -Fix switch was the first and probably most challenging feature that I added.
Similar to how one can already get fixes for a subset of warnings (e.g. for AvoidUsingCmdletAlias) in VSCode, this feature allows to auto-fix the analysed files, which can be useful to tidy up a big code base.
When using this switch, one must still inspect the result and possibly make adaptions.
The AvoidUsingConvertToSecureStringWithPlainText rule for example will change a String to a SecureString, which means that you must create or get it in the first place.
A small warning should be given about encoding: Due to the way how the engine works, it was not possible to always conserve the encoding, therefore before checking in the changes, it is also recommended to check for a change in that in case scripts are sensitive to that.
The -ReportSummary switch was implemented first by the community member @StingyJack, thanks for that.
The idea is to see a summary, like Pester but since it writes to host, we decided to not enable it by default but rather have a switch for it to start with.
It got refined a bit later to use the same colouring for warnings/errors as currently configured in the PowerShell host.
The -EnableExit was an idea being proposed by the community member @BatmanAMA as well and the idea is to have a simpler, faster to write CI integration.
The switch will return an exit code equivalent to the number of rule violations to signal success/failure to the CI system.
Of course, it is still best practice to have a Pester test (for each file and/or rule) for it due Pester’s ability to produce result files that can be interpreted by CI systems for more detailed analysis.
New Rules
AvoidAssignmentToAutomaticVariable
PowerShell has built-in variables, also known as automatic variables.
Some of them are read-only and PowerShell would throw an error at runtime.
Therefore, the rule warns against assignment of those variables.
Some of them, like e.g. $error are very easy to assign to by mistake, especially for new users who are not aware.
In the future more automatic variables will be added to the ‘naughty’ list but since some automatic variables can be assigned to (by design), the process of determining the ones to warn against is still in process and subject to future improvement.
PossibleIncorrectUsageOfRedirectionOperator and PossibleIncorrectUsageOfAssignmentOperator
I have written those rules mainly for myself because as a C# programmer, I have to switch between different languages quite often and it happened to me and my colleagues quite often that we forgot simple syntax and were using e.g. if ($a > $b) when in fact what we meant was if ($a -gt $b) and similar for the ambiguity of the assignment operator = that can easily be used by accident instead of the equality operator that was probably intended.
Since this only applies to if/elseif/while/do-while statements, I could limit the search scope for it.
To avoid false positives, a lot of intelligent logic went into it.
For example, the rule is clever enough to know that if ($a = Get-Something) is assignment by design as this is a common coding pattern and therefore excluded from this rule.
I received some interesting feedback from the community and because PSSA does not support suppression on a per line basis at the moment, the rule offers implicit suppression in CLANG style whereby wrapping the expression in extra parenthesis tells the rule that the assignment is by design.
Thanks for this idea, which came from the community by @imfrancisd
AvoidTrailingWhiteSpace
This rule was implemented by the well known community member @dlwyatt and really does what it says on the tin.
The idea behind this was especially to prevent problems that can be caused by whitespace after the backtick.
Personally, I have the following setting in my settings.json for VSCode file that trims trailing whitespace automatically upon saving the file.
"": {
"files.trimTrailingWhitespace": true
},
AvoidUsingCmdletAliases
This rule is not new but a new feature has been added:
If one types a command like e.g. ‘verb’ and PowerShell cannot find it, it will try to add a ‘Get-‘ to the beginning of it and search again.
This feature was already present in PowerShell v1 by the way.
However, although ‘service’ might work on Windows, but on Linux ‘service’ is a native binary that PowerShell would call.
Therefore it is not only the implicit aliasing that makes it dangerous to omit ‘Get-‘, but also the ambiguity on different operating systems that can cause undesired behavior.
The rule is intelligent enough to check if the native binary is present on the given OS and therefore warns when using ‘service’ on Windows only.
Miscellaneous engine improvements and fixes
A lot of fixes for thrown exception, false positives, false negatives, etc. are part of this release as well.
Some are notable:
- The PowerShell extension of VSCode uses PowerShellEditorServices, which in turn calls into PSScriptAnalyzer for displaying the warnings using squiggles and also uses its formatting capabilities (shortcut: Ctrl+K+F on the selection).
There was one bug whereby if a comment was at the end of e.g. an if statement and the statement got changed to have the brace on the same line, the formatter placed the comment before the brace, which resulted in invalid syntax.
This is fixed now.
The PSUseConsistentWhiteSpace was also tweaked to take unary operators into account to have formatting that naturally looks better to humans rather than having a strict rule. - The engine is now being built using the .Net Core SDK version 2 and targets .Net Standard 2.0 for PowerShell Core builds.
The used referenced for the PowerShell Parser also got updated to the latest version or the corresponding reference assemblies for Windows PowerShell, which highly improved the behaviour of PSScriptAnalyzer on PowerShell 3. - Various parsing issues existed with the -Settings parameter when it was not a string that was already resolved.
This got fixed and should now work in any scenario. - PSSA has a UseCompatibleCmdlet rule and command data files are now present for all versions of Windows PowerShell and even OS specific for PowerShell Core 6.0.2.
In effect the rule allows you to get warnings when calling cmdlets that are not present in the chosen PowerShell versions.
More improvements to analyse type usage as well is planned. - The PSUseDeclaredVarsMoreThanAssignments rule has been a pet peeve for many in the past due to its many false positves.
The rule received a few improvements.
Some of its limitations (it is e.g. not aware of the scriptblock scope) are still present but overall, there should be less false positives. - Lots of internal build and packaging improvements were made and PSScriptAnalyzer pushed the envelope as far as using AppVeyor’s Ubuntu builds, which are currently in private Beta.
Many thanks to @IlyaFinkelshteyn for allowing us to use it and the great support.
We are now testing against PowerShell 4, 5.1 and 6.0 (Windows and Ubuntu) in CI. - Many community members added documentation fixes, thank you all for that!
- Parser errors are now returned as diagnostic messages
- Using ScriptAnalyzer with PowerShell Core requires at least version 6.0.2
Enjoy the new release and let us know how you find it.
PSScriptAnalyzer is also open to PRs if you want to add features or fix something.
Let me know if there are other PSScriptAnalyzer topics that you would like me to write about, such as e.g. custom rules or PSScriptAnalyzer setting files and VSCode integration.
Christopher Bergmeister
PSScriptAnalyzer Maintainer