ScriptAnalyzer now runs on platforms containing PSv3.0 and above - WMF 5.0 is no longer a prerequisite!
=============
- Next Meeting - May 24 2016 - 11am to 12pm PDT
- Notes and recordings from earlier meetings
=============
#####Builds
|Master | Development |
|:------:|:------:|:-------:|:-------:|
|
|
=============
Code Review Dashboard on reviewable.io
=============
PSScriptAnalyzer is a static code checker for Windows PowerShell modules and scripts. PSScriptAnalyzer checks the quality of Windows PowerShell code by running a set of rules. The rules are based on PowerShell best practices identified by PowerShell Team and the community. It generates DiagnosticResults (errors and warnings) to inform users about potential code defects and suggests possible solutions for improvements.
PSScriptAnalyzer is shipped with a collection of built-in rules that checks various aspects of PowerShell code such as presence of uninitialized variables, usage of PSCredential Type, usage of Invoke-Expression etc. Additional functionalities such as exclude/include specific rules are also supported.
Get-ScriptAnalyzerRule [-CustomizedRulePath <string[]>] [-Name <string[]>] [<CommonParameters>] [-Severity <string[]>]
Invoke-ScriptAnalyzer [-Path] <string> [-CustomizedRulePath <string[]>] [-ExcludeRule <string[]>] [-IncludeRule <string[]>] [-Severity <string[]>] [-Recurse] [<CommonParameters>]
WS2012R2 / Windows 8.1 / Windows OS running a minimum of PowerShell v3.0
A Windows OS with PowerShell v5.0 Windows Management Framework 5.0 Preview is also supported
-
Build the Code using Visual Studio [solution part of the repo] and navigate to the binplace location [
~/ProjectRoot/PSScriptAnalyzer] -
In PowerShell Console:
Import-Module PSScriptAnalyzerIf you have previous version of PSScriptAnalyzer installed on your machine, you may need to override old binaries by copying content of [~/ProjectRoot/PSScriptAnalyzer] to PSModulePath.
To confirm installation: run Get-ScriptAnalyzerRule in the PowerShell console to obtain the built-in rules
You can suppress a rule by decorating a script/function or script/function parameter with .NET's SuppressMessageAttribute. SuppressMessageAttribute's constructor takes two parameters: a category and a check ID. Set the categoryID parameter to the name of the rule you want to suppress and set the checkID parameter to a null or empty string:
function SuppressMe()
{
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "")]
param()
Write-Verbose -Message "I'm making a difference!"
}
All rule violations within the scope of the script/function/parameter you decorate will be suppressed.
To suppress a message on a specific parameter, set the SuppressMessageAttribute's CheckId parameter to the name of the parameter:
function SuppressTwoVariables()
{
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideDefaultParameterValue", "b")]
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideDefaultParameterValue", "a")]
param([string]$a, [int]$b)
{
}
}
Use the SuppressMessageAttribute's Scope property to limit rule suppression to functions or classes within the attribute's scope. Use the value Function to suppress violations on all functions within the attribute's scope. Use the value Class to suppress violoations on all classes within the attribute's scope:
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "", Scope="Function")]
param(
)
function InternalFunction
{
param()
Write-Verbose -Message "I am invincible!"
}
The above example demonstrates how to suppress rule violations for internal functions using the SuppressMessageAttribute's Scope property.
You can further restrict suppression based on a function/parameter/class/variable/object's name by setting the SuppressMessageAttribute's Target property to a regular expression. Any function/parameter/class/variable/object whose name matches the regular expression is skipped.
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="PositionalParametersAllowed")]
Param(
)
function PositionalParametersAllowed()
{
Param([string]$Parameter1)
{
Write-Verbose $Parameter1
}
}
function PositionalParametersNotAllowed()
{
param([string]$Parameter1)
{
Write-Verbose $Parameter1
}
}
# The script analyzer will skip this violation
PositionalParametersAllowed 'value1'
# The script analyzer will report this violation
PositionalParametersNotAllowed 'value1
To match all functions/variables/parameters/objects, use * as the value of the Target parameter:
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="*")]
Param(
)
Settings that describe ScriptAnalyzer rules to include/exclude based on Severity can be created and supplied to
Invoke-ScriptAnalyzer using the -Setting parameter. This enables a user to create a custom configuration for a specific environment.
Using Settings support:
The following example excludes two rules from the default set of rules and any rule that does not output an Error or Warning diagnostic record.
# ScriptAnalyzerSettings.psd1
@{
Severity=@('Error','Warning')
ExcludeRules=@('PSAvoidUsingCmdletAliases',
'PSAvoidUsingWriteHost')
}Then invoke that settings file when using Invoke-ScriptAnalyzer:
Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1The next example selects a few rules to execute instead of all the default rules.
# ScriptAnalyzerSettings.psd1
@{
IncludeRules=@('PSAvoidUsingPlainTextForPassword',
'PSAvoidUsingConvertToSecureStringWithPlainText')
}Then invoke that settings file when using Invoke-ScriptAnalyzer:
Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1ScriptAnalyzer engine and functionality can now be directly consumed as a library.
Here are the public interfaces:
using Microsoft.Windows.PowerShell.ScriptAnalyzer;
public void Initialize(System.Management.Automation.Runspaces.Runspace runspace,
Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter,
[string[] customizedRulePath = null],
[string[] includeRuleNames = null],
[string[] excludeRuleNames = null],
[string[] severity = null],
[bool suppressedOnly = false],
[string profile = null])
public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(string path,
[bool searchRecursively = false])
public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames,
string[] ruleNames)Most violations can be fixed by replacing the violation causing content with the correct alternative. In an attempt to provide the user with the ability to correct the violation we provide a property - SuggestedCorrections, in each DiagnosticRecord instance. This property contains the information needed to rectify the violation. For example, consider a script C:\tmp\test.ps1 with the following content.
PS> Get-Content C:\tmp\test.ps1
gci C:\Invoking PSScriptAnalyzer on the file gives the following output.
PS>$diagnosticRecord = Invoke-ScriptAnalyzer -Path C:\tmp\test.p1
PS>$diagnosticRecord | select SuggestedCorrections | Format-Custom
class DiagnosticRecord
{
SuggestedCorrections =
[
class CorrectionExtent
{
EndColumnNumber = 4
EndLineNumber = 1
File = C:\Users\kabawany\tmp\test3.ps1
StartColumnNumber = 1
StartLineNumber = 1
Text = Get-ChildItem
Description = Replace gci with Get-ChildItem
}
]
}The *LineNumber and *ColumnNumber properties give the region of the script that can be replaced by the contents of Text property, i.e., replace gci with Get-ChildItem.
The main motivation behind having SuggestedCorrections is to enable quick-fix like scenarios in editors like VSCode, Sublime, etc. At present, we provide valid SuggestedCorrection only for the following rules, while gradually adding this feature to more rules.
- AvoidAlias.cs
- AvoidUsingPlainTextForPassword.cs
- MisleadingBacktick.cs
- MissingModuleManifestField.cs
- UseToExportFieldsInManifest.cs
Use Visual Studio to build "PSScriptAnalyzer.sln". Use ~/PSScriptAnalyzer/ folder to load PSScriptAnalyzer.psd1
Note: If there are any build errors, please refer to Requirements section and make sure all dependencies are properly installed
Pester-based ScriptAnalyzer Tests are located in <branch>/PSScriptAnalyzer/Tests folder
- Ensure Pester is installed on the machine
- Go the Tests folder in your local repository
- Run Engine Tests: .\InvokeScriptAnalyzer.tests.ps1
- Run Tests for Built-in rules: .*.ps1 (Example - .\ AvoidConvertToSecureStringWithPlainText.ps1) *You can also run all tests under \Engine or \Rules by calling Invoke-Pester in the Engine/Rules directory.
You can track issues, pull requests, backlog items here:
Throughput Graph
You are welcome to contribute to this project. There are many ways to contribute:
- Submit a bug report via Issues. For a guide to submitting good bug reports, please read Painless Bug Tracking.
- Verify fixes for bugs.
- Submit your fixes for a bug. Before submitting, please make sure you have:
- Performed code reviews of your own
- Updated the test cases if needed
- Run the test cases to ensure no feature breaks or test breaks
- Added the test cases for new code
- Submit a feature request.
- Help answer questions in the discussions list.
- Submit test cases.
- Tell others about the project.
- Tell the developers how much you appreciate the product!
You might also read these two blog posts about contributing code: Open Source Contribution Etiquette by Miguel de Icaza, and Don’t “Push” Your Pull Requests by Ilya Grigorik.
Before submitting a feature or substantial code contribution, please discuss it with the Windows PowerShell team via Issues, and ensure it follows the product roadmap. Note that all code submissions will be rigorously reviewed by the Windows PowerShell Team. Only those that meet a high bar for both quality and roadmap fit will be merged into the source.