- Introduction
- Documentation Notice
- Installation
- Contributions are welcome
- Creating a Release
- Code of Conduct
- Security Policy
PSScriptAnalyzer is a static code checker for PowerShell modules and scripts. PSScriptAnalyzer checks the quality of 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 ships with a collection of built-in rules that check various aspects of PowerShell code such as:
- The presence of uninitialized variables
- Use of PSCredential type
- Use of
Invoke-Expression - And many more
Conceptual user documentation has been moved out of the source code repository and into the documentation repository so that it can be published on learn.microsoft.com.
The goal of this migration is to have the user documentation on learn.microsoft.com. The source code repository should only contain documentation for the code base, such as how to build the code or how to contribute to the code.
User documentation that has been migrated:
- Most of the contents of this README can be found in the PSScriptAnalyzer overview
- For cmdlet reference, see PSScriptAnalyzer
- For rules, see Rules overview
- The
PowerShellBestPractices.mdcontent has been moved to PSScriptAnalyzer rules and recommendations - The
ScriptRuleDocumentation.mdcontent has been moved to Creating custom rules
There is one exception - the documentation for the rules and cmdlets will remain in the docs folder to facilitate build testing and to be archived as part of each release. Only the documentation for the latest release is published on on learn.microsoft.com.
To install PSScriptAnalyzer from the PowerShell Gallery, see Installing PSScriptAnalyzer.
To install PSScriptAnalyzer from source code:
- If building for Windows PowerShell versions, then the .NET Framework 4.6.2 targeting pack (also referred to as developer/targeting pack) need to be installed. This is only possible on Windows.
- Optionally but recommended for development: Visual Studio 2017/2019
- Pester v5 PowerShell module, available on PowerShell Gallery
- PlatyPS PowerShell module, available on PowerShell Gallery
- Optionally but recommended for development: Visual Studio
-
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 StudiosolutionPSScriptAnalyzer.slnor build usingPowerShellspecifically for your platform as follows:-
The default build is for the currently used version of PowerShell
.\build.ps1
-
Windows PowerShell version 5.0
.\build.ps1 -PSVersion 5
-
Windows PowerShell version 4.0
.\build.ps1 -PSVersion 4
-
Windows PowerShell version 3.0
.\build.ps1 -PSVersion 3
-
PowerShell 7
.\build.ps1 -PSVersion 7
-
-
Rebuild documentation since it gets built automatically only the first time
.\build.ps1 -Documentation -
Build all versions (PowerShell v3, v4, v5, and v6) and documentation
.\build.ps1 -All -
Import the module
Import-Module .\out\PSScriptAnalyzer\[version]\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
*.resxfiles, it is recommended to useVisual Studiosince it automatically updates the strongly typed*.Designer.csfiles. TheVisual Studio 2017 Community Editionis free to use but should you not have/want to useVisual Studiothen you can either manually adapt the*.Designer.csfiles or use theNew-StronglyTypedCsFileForResx.ps1script although the latter is discouraged since it leads to a bad diff of the*.Designer.csfiles.
Pester-based ScriptAnalyzer Tests are located in path/to/PSScriptAnalyzer/Tests folder.
- Ensure Pester of at least version 5.3 is installed
- In the root folder of your local repository, run:
./build -TestTo retrieve the results of the run, you can use the tools which are part of the build module (build.psm1)
Import-Module ./build.psm1
Get-TestResultsTo retrieve only the errors, you can use the following:
Import-Module ./build.psm1
Get-TestFailuresThe documentation in this section can be found in Using PSScriptAnalyzer.
There are many ways to contribute:
- Open a new bug report, feature request or just ask a question by opening a new issue.
- Participate in the discussions of issues, pull requests and test fixes or new features.
- Submit your own fixes or features as a pull request but please discuss it beforehand in an issue.
- Submit test cases.
- 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-Releasecmdlet 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.csprojandRules/Rules.csproj - Create a release build in
out/
Import-Module .\Utils\ReleaseMaker.psm1
New-Release- Sign the binaries and PowerShell files in the release build and publish the module to PowerShell Gallery.
- Draft a new release on github and tag
masterwith the new version number.
Please see our Code of Conduct before participating in this project.
For any security issues, please see our Security Policy.