Download ScriptAnalyzer from PowerShellGallery
C# PowerShell Batchfile
Latest commit 260a573 Feb 23, 2017 @kapilmb kapilmb committed on GitHub Fix markdown headings in rule documentation (#716)
* Fix markdown headers in rule documentation

Most rule documentation markdown files had headers of the form '#header' or '##header'. This commit fixes those issues.

Some documentation markdown markdown files were in UTF8 and the rest in ASCII. This commit converts all markdown files to ASCII encoding.

* Add new line after heading, if not present
Permalink
Failed to load latest commit information.
DeprecatedRules Move AvoidUsingFilePaths and AvoidUnloadableModule to deprecated rule… Mar 21, 2016
Engine Add a constructor to CorrectionExtent class Feb 17, 2017
RuleDocumentation Fix markdown headings in rule documentation (#716) Feb 23, 2017
Rules Update method names of new line after close brace Feb 17, 2017
Tests Add correction tests to new line after close brace Feb 17, 2017
Utils Fix extracting hyperlink from markdown Nov 23, 2016
docs Add missing help to cmdlet help files Jun 14, 2016
.gitignore Added binplace location May 12, 2015
CHANGELOG.MD Update changelog for v1.10.0 Jan 19, 2017
LICENSE Rename LICENSE.md to LICENSE May 20, 2015
New-StronglyTypedCsFileForResx.ps1 Add function to create strongly typed resource file Aug 15, 2016
NuGet.Config Add nuget config file Sep 23, 2016
PSScriptAnalyzer.sln Revert solution and project files Aug 15, 2016
PowerShellBestPractices.md Update marked up documentation Aug 23, 2016
README.md Link ToC from each heading Feb 6, 2017
ScriptRuleDocumentation.md Fix README and rule documetation Aug 23, 2016
ThirdPartyNotices.txt Add third party notices Oct 8, 2016
appveyor.yml Add PSv4 build/test matrix to appveyor Dec 12, 2016
build.cmd Check Visual Studio 2015 for build Jun 15, 2016
build.ps1 Merge pull request #588 from PowerShell/ExternalRuleSuppression Aug 2, 2016
buildCoreClr.ps1 Add PSv3 build from buildCoreClr.ps1 Sep 27, 2016
global.json Add dotnet sdk version to global.json (#708) Feb 8, 2017

README.md

Join the chat at https://gitter.im/PowerShell/PSScriptAnalyzer

Master Development
Build status Build status

Table of Contents

Introduction

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.

Usage

Get-ScriptAnalyzerRule [-CustomizedRulePath <string[]>] [-Name <string[]>] [<CommonParameters>] [-Severity <string[]>]

Invoke-ScriptAnalyzer [-Path] <string> [-CustomizedRulePath <string[]>] [-ExcludeRule <string[]>] [-IncludeRule <string[]>] [-Severity <string[]>] [-Recurse] [<CommonParameters>]

Installation

From PowerShell Gallery

Install-Module -Name PSScriptAnalyzer

Note: For PowerShell version 5.1.14393.206 or newer, before installing PSScriptAnalyzer, please install the latest Nuget provider by running the following in an elevated PowerShell session.

Install-PackageProvider Nuget –force –verbose
Exit

Requirements

Windows
  • Windows PowerShell 3.0 or greater
  • PowerShell Core
Linux (Tested only on Ubuntu 14.04)
  • PowerShell Core

From Source

Requirements

Steps

  • Obtain the source
    git clone https://github.com/PowerShell/PSScriptAnalyzer
  • Navigate to the source directory powershell cd path/to/PSScriptAnalyzer
  • Restore packages powershell dotnet restore
  • Build for your platform
    • Windows PowerShell version 5.0 and greater
    .\buildCoreClr.ps1 -Framework net451 -Configuration Release -Build
    • Windows PowerShell version 3.0 and 4.0
    .\buildCoreClr.ps1 -Framework net451 -Configuration PSV3Release -Build
    • PowerShell Core
    .\buildCoreClr.ps1 -Framework netstandard1.6 -Configuration Release -Build
  • Build documenatation powershell .\build.ps1 -BuildDocs
  • Import the module
Import-Module /path/to/PSScriptAnalyzer/out/PSScriptAnalyzer

To confirm installation: run Get-ScriptAnalyzerRule in the PowerShell console to obtain the built-in rules

Tests

Pester-based ScriptAnalyzer Tests are located in path/to/PSScriptAnalyzer/Tests folder.

  • Ensure Pester is installed on the machine
  • Copy path/to/PSScriptAnalyzer/out/PSScriptAnalyzer to a folder in PSModulePath
  • Go the Tests folder in your local repository
  • Run Engine Tests:
cd /path/to/PSScriptAnalyzer/Tests/Engine
Invoke-Pester
  • Run Tests for Built-in rules:
cd /path/to/PSScriptAnalyzer/Tests/Rules
Invoke-Pester

Suppressing 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 violations on all classes within the attribute's scope:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "", Scope="Function")]
param(
)

function InternalFunction
{
    param()

    Write-Verbose -Message "I am invincible!"
}

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 or a glob pattern. Few examples are given below.

Suppress PSAvoidUsingWriteHost rule violation in start-bar and start-baz but not in start-foo and start-bam:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope='Function', Target='start-ba[rz]')]
param()
function start-foo {
    write-host "start-foo"
}

function start-bar {
    write-host "start-bar"
}

function start-baz {
    write-host "start-baz"
}

function start-bam {
    write-host "start-bam"
}

Suppress violations in all the functions:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", Scope="Function", Target="*")]
Param()

Suppress violation in start-bar, start-baz and start-bam but not in start-foo:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", Scope="Function", Target="start-b*")]
Param()

Note: Rule suppression is currently supported only for built-in rules.

Settings Support in ScriptAnalyzer

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. We support the following modes for specifying the settings file.

Explicit

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.

# PSScriptAnalyzerSettings.psd1
@{
    Severity=@('Error','Warning')
    ExcludeRules=@('PSAvoidUsingCmdletAliases',
                'PSAvoidUsingWriteHost')
}

Then invoke that settings file when using Invoke-ScriptAnalyzer:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1

The next example selects a few rules to execute instead of all the default rules.

# PSScriptAnalyzerSettings.psd1
@{
    IncludeRules=@('PSAvoidUsingPlainTextForPassword',
                'PSAvoidUsingConvertToSecureStringWithPlainText')
}

Then invoke that settings file when using:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1

Implicit

If you place a PSScriptAnayzer settings file named PSScriptAnalyzerSettings.psd1 in your project root, PSScriptAnalyzer will discover it if you pass the project root as the Path parameter.

Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse

Note that providing settings explicitly takes higher precedence over this implicit mode. Sample settings files are provided here.

ScriptAnalyzer as a .NET library

ScriptAnalyzer 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)

Violation Correction

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, that contains 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

Project Management Dashboard

You can track issues, pull requests, backlog items here:

Stories in progress

Stories in ready

Stories in backlog

Throughput Graph

Throughput Graph

Contributing to ScriptAnalyzer

You are welcome to contribute to this project. There are many ways to contribute:

  1. Submit a bug report via Issues. For a guide to submitting good bug reports, please read Painless Bug Tracking.
  2. Verify fixes for bugs.
  3. 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
  4. Submit a feature request.
  5. Help answer questions in the discussions list.
  6. Submit test cases.
  7. Tell others about the project.
  8. 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.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.