PowerShell ScriptAnalyzer Version 1.18.0 Released

Jim Truher

PSScriptAnalyzer (PSSA) 1.18.0 is now available on the PSGallery and brings a lot of improvements in the following areas:

• Better compatibility analysis of commands, types and syntax across different platforms and versions of PowerShell
• Better formatting and customization. New capabilities are:
  • Multi-line pipeline indentation styles
  • Cmdlet casing for better consistency and readability
  • Consistent whitespace inside braces and pipes
• Custom rules can now be suppressed and preserve the RuleSuppressionID
• Better DSC support by being able to understand different syntaxes of Import-DscResource
• Better user experience by being able to pipe to Invoke-ScriptAnalyzer and added tab completion of the returned objects that are piped to the next pipeline
• Better handling of parsing errors by emitting them as a diagnostic record with a new Severity type
• Improved Performance: Expect it to be about twice as fast in most cases and even more when re-analyzing a file. More on this below
• Fixes and enhancements to the engine, rules, and documentation

There are some minor breaking changes such as e.g. requiring the minimum version of PowerShell Core to 6.1 as 6.0 has reached the end of its support lifecycle. With this, it was possible to update the used version of Newtonsoft.Json to 11.0.2. On Windows PowerShell, the minimum required runtime was upped from4.5.0 to4.5.2, which is the lowest version that is still supported by Microsoft but Windows update will have taken care of upgrading the to this patched version anyway, therefore no disruption is expected. We have also replaced old command data files of PowerShell 6.0 with a newer version for theUseCompatibleCmdletsrule.

Formatting

New rules and new features/customization of existing rules were added and in an upcoming release of the PowerShell vscode extension, those new features will also be configurable from within the extension in an upcoming update.

New PSUseConsistentWhitespace options

The PSUseConsistentWhitespace rule has 2 new configuration options that are both enabled by default:

• CheckInnerBrace: Checks if there is a space after the opening brace and a space before the closing brace. E.g. if ($true) { foo } instead of if ($true) {bar}.
• CheckPipe: Checks if a pipe is surrounded on both sides by a space. E.g. foo | bar instead offoo|bar.

In an upcoming update of the PowerShell vscode extension, this feature will be configurable in the editor via the settings powershell.WhitespaceInsideBrace and powershell.WhitespaceAroundPipe.

New PipelineIndentation option for PSUseConsistentIndentation

The PSUseConsistentIndentation rule was fixed to handle multi-line pipeline (before, the behavior was a bit ill-defined) and as part of that we decided to expose 3 options for a new configuration option calledPipelineIndentation. This allows PSSA to cater to different tastes of the user whether to increase indentation after a pipeline for multi-line statements. The settings are:

• IncreaseIndentationForFirstPipeline (default): Indent once after the first pipeline and keep this indentation. Example:

foo |
    bar |
    baz

• IncreaseIndentationAfterEveryPipeline: Indent more after the first pipeline and keep this indentation. Example:

foo |
    bar |
        baz

• NoIndentation: Do not increase indentation. Example:

foo |
bar |
baz

In an upcoming update of the PowerShell vscode extension, this feature will be configurable in the editor via the setting powershell.codeFormatting.

New PSUseConsistentCasing rule

By popular request, this rule can correct the casing of cmdlet names. This can correct e.g. get-azadapplicaTION to Get-AzADApplication. This not only makes code more consistent but can improve readability in most cases. In an upcoming update of the PowerShell vscode extension, this feature will be configurable in the editor via the settingpowershell.useCorrectCasingsettings.

Compatibility Analysis

The UseCompatibleCmdlets rule requires JSON files in the Settings folder of PSSA’s installation and their file name is mapped to directly the compatibility configuration. In the new version we have replaced the JSON files for PowerShell 6.0 with files for 6.1 and also added new files for e.g. ARM on Linux (Raspian) and also PowerShell 2.0 that is still being used by some despite it being deprecated. If desired, one can always add custom JSON files to the Settings folder and it will just work by using the filename without the need to re-compile. To generate your custom JSON file for your environment, you can use the New-CommandDataFile.ps1 script.

To further add more analysis, 3 more rules were being added:

• UseCompatibleSyntax
• UseCompatibleTypes
• UseCompatibleCommands

These rules do not follow the definition style of the UseCompatibleCmdlets rule. For usage and examples please refer to the rule documentation links of the 3 new rules above, there will be a more detailed blog post about them in the future.

Better DSC Support

Invoke-ScriptAnalyzer has a -SaveDscDependency switch that will download the required module from the PSGalleryto allow for parsing of the DSC files. In order to do that is has to parse calls to Import-DscResource correctly. Previously it could neither take the version into account or parse the hashtable syntax (Import-DscResource -ModuleName (@{ModuleName="SomeDscModule1";ModuleVersion="1.2.3.4"})). We added support for both of them. But because there could be different variations of the first one (different parameter name order or not using named paramters, etc.), please use it in the form Import-DscResource -ModuleName MyModuleName -ModuleVersion 1.2.3.4.

Custom Rules

We added the capability of being able to suppress violations from custom rules the same way how you can already suppress rules from the built-in rules. It is worth noting though that the rulename of custom rules has to be of the format CustomRuleModuleFileName\CustomRuleName, this is to uniquely identify the rule as it could be possible that 2 custom rule modules emit a rule of the same name.

When a custom rule emits a DiagnosticRecord, then the engine has to translate all properties of the object as it has to be re-created when emitting it via Invoke-ScriptAnalyzer. We added the translation of the SuggestedCorrectionsproperty already in the last release (1.17.1) to allow for auto-correction in the editor or via the -Fix switch. However, we also found that customers want to also use the RuleSuppressionID property in their custom rules, so we added translation for this as well.

Engine Improvements

PSScriptAnalyzer is highly multi-threaded by executing each rule (excluding custom or DSC rules) in parallel in each own thread. But there are some global resources such as e.g. a CommandInfo cache that needs to be accessed using a lock. Caching and lock granularity has been improved and are therefore reducing congestion which leads to much better performance. You can expect PSScriptAnalyzer to be about twice as fast for ‘cold runs’ (where Invoke-ScriptAnalyzerhas not been called before) and magnitudes faster when re-analyzing the same file. To you as a user, this will mean that you will see the squiggles faster when opening a new file in VS-Code and you will get faster updates when editing a file whilst reducing the CPU consumption in the background. We have more optimizations planned in this area, you can expect further improvements of similar scale in future versions and we hope to release future versions more frequent as well.

Miscellaneous Fixes

We received reports of some functionality not working when using Turkish culture and made a fix for and as part reviewed some culture critical points and made sure they work better across all cultures. The bug was very specific to Turkish culture, therefore we are confident that PSSA should work with any other cultures as well.

The Changelog has more details on the various fixes that were made to other rules.

On behalf of the Script Analyzer team,

Chris Bergmeister, Project Maintainer Jim Truher, Senior Software Engineer, Microsoft

Jim Truher Senior Software Engineer, PowerShell

Follow