Download ScriptAnalyzer from PowerShellGallery
C# PowerShell
Clone or download
Permalink
Failed to load latest commit information.
.github Use multiple GitHub issue templates for bugs, feature requests and su… May 11, 2018
.vscode add powershell and c# extension as recommended extension for vscode Jun 3, 2018
DeprecatedRules Move AvoidUsingFilePaths and AvoidUnloadableModule to deprecated rule… Mar 21, 2016
Engine Merge pull request #1020 from bergmeister/OutputType Jul 19, 2018
RuleDocumentation Fix table to refer to existing md files, add col for Configurable (#988) Jun 5, 2018
Rules Update to 1.17.1 (Update changelog, ran New-Release and updated versi… Jun 5, 2018
Tests PR feedback: use Should better Jul 18, 2018
Utils 2 more PSPossibleIncorrectComparisonWithNull fix Jun 3, 2018
docs/markdown Add Outputs to Invoke-Formatter.md documentation Jun 8, 2018
tools Use TLS 1.2 for bootstrapping dotnet in CI (#1047) Jul 27, 2018
.gitignore Upgrade .Net Core SDK from '1.0 Preview 2' to '1.1.5' (this is the LT… Jan 21, 2018
CHANGELOG.MD Update to 1.17.1 (Update changelog, ran New-Release and updated versi… Jun 5, 2018
LICENSE Rename LICENSE.md to LICENSE May 20, 2015
New-StronglyTypedCsFileForResx.ps1 Fix PSAvoidUsingCmdletAliases warnings in root and Utils folder using… Feb 6, 2018
NuGet.Config Allow TypeNotFound parser errors (#957) May 11, 2018
PSScriptAnalyzer.sln Upgrade .Net Core SDK from '1.0 Preview 2' to '1.1.5' (this is the LT… Jan 21, 2018
PowerShellBestPractices.md Fix table to refer to existing md files, add col for Configurable (#988) Jun 5, 2018
README.md Merge 1.17.0 branch into development (#1015) Jun 5, 2018
ScriptRuleDocumentation.md Support SuggestedCorrections property on DiagnosticRecord for script … May 17, 2018
ThirdPartyNotices.txt Add third party notices Oct 8, 2016
appveyor.yml Do not cache dotnet cli. I turns out to be not a speedup Jun 6, 2018
build.ps1 another PSPossibleIncorrectComparisonWithNull fix Jun 3, 2018
buildCoreClr.ps1 tweak matching of illegal configuration combinations to cater for psv… Jun 3, 2018
global.json Update .Net Core SDK from 2.1.4 to 2.1.101 (#936) Mar 16, 2018

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.

Back to ToC

Usage

Get-ScriptAnalyzerRule [-CustomRulePath <String[]>] [-RecurseCustomRulePath] [-Name <String[]>] [-Severity <String[]>] [<CommonParameters>]

Invoke-ScriptAnalyzer [-Path] <String> [-CustomRulePath <String[]>] [-RecurseCustomRulePath] [-ExcludeRule <String[]>] [-IncludeDefaultRules] [-IncludeRule <String[]>] [-Severity <String[]>] [-Recurse] [-SuppressedOnly] [-Fix] [-EnableExit] [-ReportSummary] [-Settings <Object>] [-SaveDscDependency] [<CommonParameters>]

Invoke-ScriptAnalyzer [-ScriptDefinition] <String> [-CustomRulePath <String[]>] [-RecurseCustomRulePath] [-ExcludeRule <String[]>] [-IncludeDefaultRules] [-IncludeRule <String[]>] [-Severity <String[]>] [-Recurse] [-SuppressedOnly] [-EnableExit] [-ReportSummary] [-Settings <Object>] [-SaveDscDependency] [<CommonParameters>]

Invoke-Formatter [-ScriptDefinition] <String> [[-Settings] <Object>] [[-Range] <Int32[]>] [<CommonParameters>]

Back to ToC

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 -MinimumVersion 2.8.5.201 –Force
Exit

Supported PowerShell Versions and Platforms

  • Windows PowerShell 3.0 or greater
  • PowerShell Core on Windows/Linux/macOS
  • Docker (tested only using Docker CE on Windows 10 1803
    • PowerShell 6 Windows Image tags using from microsoft/powershell: nanoserver, 6.0.2-nanoserver, 6.0.2-nanoserver-1709, windowsservercore and 6.0.2-windowsservercore. Example (1 warning gets produced by Save-Module but can be ignored):

      docker run -it microsoft/powershell:nanoserver pwsh -command "Save-Module -Name PSScriptAnalyzer -Path .; Import-Module .\PSScriptAnalyzer; Invoke-ScriptAnalyzer -ScriptDefinition 'gci'"

    • PowerShell 5.1 (Windows): Only the microsoft/windowsservercore images work but not the microsoft/nanoserver images because they contain a Core version of it. Example:

      docker run -it microsoft/windowsservercore powershell -command "Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force; Install-Module PSScriptAnalyzer -Force; Invoke-ScriptAnalyzer -ScriptDefinition 'gci'"

    • Linux tags from microsoft/powershell: latest, ubuntu16.04, ubuntu14.04 and centos7. - Example:

      docker run -it microsoft/powershell:latest pwsh -c "Install-Module PSScriptAnalyzer -Force; Invoke-ScriptAnalyzer -ScriptDefinition 'gci'"

From Chocolatey

If you prefer to manage PSScriptAnalyzer as a Windows package, you can use Chocolatey to install it.

If you don't have Chocolatey, you can install it from the Chocolately Install page. With Chocolatey installed, execute the following command to install PSScriptAnalyzer:

choco install psscriptanalyzer

Note: the PSScriptAnalyzer Chocolatey package is provided and supported by the community.

From Source

Requirements

Steps

  • Obtain the source

    • Download the latest source code from the release page OR
    • Clone the repository (needs git)
    git clone https://github.com/PowerShell/PSScriptAnalyzer
  • Navigate to the source directory

    cd path/to/PSScriptAnalyzer
  • Building

    You can either build using the Visual Studio solution PSScriptAnalyzer.sln or build using PowerShell specifically for your platform as follows:

    • Windows PowerShell version 5.0 and greater
    .\buildCoreClr.ps1 -Framework net451 -Configuration Release -Build
    • Windows PowerShell version 4.0
    .\buildCoreClr.ps1 -Framework net451 -Configuration PSV4Release -Build
    • Windows PowerShell version 3.0
    .\buildCoreClr.ps1 -Framework net451 -Configuration PSV3Release -Build
    • PowerShell Core
    .\buildCoreClr.ps1 -Framework netstandard2.0 -Configuration Release -Build
  • Build documenatation

    .\build.ps1 -BuildDocs
  • Import the module

Import-Module .\out\PSScriptAnalyzer\PSScriptAnalyzer.psd1

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

  • Adding/Removing resource strings

For adding/removing resource strings in the *.resx files, it is recommended to use Visual Studio since it automatically updates the strongly typed *.Designer.cs files. The Visual Studio 2017 Community Edition is free to use but should you not have/want to use Visual Studio then you can either manually adapt the *.Designer.cs files or use the New-StronglyTypedCsFileForResx.ps1 script although the latter is discouraged since it leads to a bad diff of the *.Designer.cs files.

Tests

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

  • Ensure Pester 4.3.1 is installed
  • Copy path/to/PSScriptAnalyzer/out/PSScriptAnalyzer to a folder in PSModulePath
  • In the root folder of your local repository, run:
$testScripts = ".\Tests\Engine",".\Tests\Rules",".\Tests\Documentation"
Invoke-Pester -Script $testScripts

Back to ToC

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. You can optionally add a third named parameter with a justification for suppressing the message:

function SuppressMe()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "", Justification="Just an example")]
    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.

Back to ToC

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.

Built-in Presets

ScriptAnalyzer ships a set of built-in presets that can be used to analyze scripts. For example, if the user wants to run PowerShell Gallery rules on their module, then they use the following command.

PS> Invoke-ScriptAnalyzer -Path /path/to/module/ -Settings PSGallery -Recurse

Along with PSGallery there are a few other built-in presets, including, DSC and CodeFormatting, that can be used. These presets can be tab completed for the Settings parameter.

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 PSScriptAnalyzerSettings.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.

Back to ToC

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)

Back to ToC

Violation Correction

Some violations can be fixed by replacing the violation causing content with a suggested alternative. You can use the -Fix switch to automatically apply the suggestions. Since Invoke-ScriptAnalyzer implements SupportsShouldProcess, you can additionally use -WhatIf or -Confirm to find out which corrections would be applied. It goes without saying that you should use source control when applying those corrections since some some of them such as the one for AvoidUsingPlainTextForPassword might require additional script modifications that cannot be made automatically. Should your scripts be sensitive to encoding you should also check that because the initial encoding can not be preserved in all cases.

The initial motivation behind having the SuggestedCorrections property on the ErrorRecord (which is how the -Fix switch works under the hood) was 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

Back to ToC

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

Back to ToC

Contributions are welcome

There are many ways to contribute:

  1. Open a new bug report, feature request or just ask a question by opening a new issue here.
  2. Participate in the discussions of issues, pull requests and verify/test fixes or new features.
  3. Submit your own fixes or features as a pull request but please discuss it beforehand in an issue if the change is substantial.
  4. Submit test cases.

Back to ToC

Creating a Release

  • Update changelog (changelog.md) with the new version number and change set. When updating the changelog please follow the same pattern as that of previous change sets (otherwise this may break the next step).
  • Import the ReleaseMaker module and execute New-Release cmdlet to perform the following actions.
    • Update module manifest (engine/PSScriptAnalyzer.psd1) with the new version number and change set
    • Update the version number in Engine/Engine.csproj and Rules/Rules.csproj
    • Create a release build in out/
    PS> Import-Module .\Utils\ReleaseMaker.psm1
    PS> New-Release
  • Sign the binaries and PowerShell files in the release build and publish the module to PowerShell Gallery.
  • Create a PR on development branch, with all the changes made in the previous step.
  • Merge the changes to development and then merge development to master (Note that the development to master merge should be a fast-forward merge).
  • Draft a new release on github and tag master with the new version number.

Back to ToC

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.

Back to ToC