#PowerShell Best Practices
The following guidelines come from a combined effort from both the PowerShell team and the community. We will use this guideline to define rules for PSScriptAnalyzer. Please feel free to propose additional guidelines and rules for PSScriptAnalyzer. **Note: The hyperlink next to each guidelines will redirect to documentation page for the rule that is already implemented.
##Cmdlet Design Rules ###Severity: Error
###Severity: Warning
- Use Only Approved Verbs UseApprovedVerbs
- Cmdlets Names: Characters that cannot be Used AvoidReservedCharInCmdlet
- Parameter Names that cannot be Used AvoidReservedParams
- Support Confirmation Requests UseShouldProcessCorrectly and UseShouldProcessForStateChangingFunctions
- Nouns should be singular UseSingularNouns
- Module Manifest Fields MissingModuleManifestField
- Version
- Author
- Description
- LicenseUri (for PowerShell Gallery)
- Must call ShouldProcess when ShouldProcess attribute is present and vice versa.UseShouldProcessCorrectly
- Switch parameters should not default to true AvoidDefaultTrueValueSwtichParameter
###Severity: Information
###Severity: TBD
- Support Force Parameter for Interactive Session
- If your cmdlet is used interactively, always provide a Force parameter to override the interactive actions, such as prompts or reading lines of input). This is important because it allows your cmdlet to be used in non-interactive scripts and hosts. The following methods can be implemented by an interactive host.
- Document Output Objects
- Module must be loadable
- No syntax errors
- Unresolved dependencies are an error
- Derive from the Cmdlet or PSCmdlet Classes
- Specify the Cmdlet Attribute
- Override an Input Processing Method
- Specify the OutputType Attribute
- Write Single Records to the Pipeline
- Make Cmdlets Case-Insensitive and Case-Preserving
##Script Functions ###Severity: Error
###Severity: Warning
- Avoid using alias AvoidAlias
- Avoid using deprecated WMI cmdlets AvoidUsingWMICmdlet
- Empty catch block should not be used AvoidEmptyCatchBlock
- Invoke existing cmdlet with correct parameters UseCmdletCorrectly
- Cmdlets should have ShouldProcess/ShouldContinue and Force param if certain system-modding verbs are present (Update, Set, Remove, New)UseShouldProcessForStateChangingFunctions
- Positional parameters should be avoided AvoidUsingPositionalParameters
- Non-global variables must be initialized. Those that are supposed to be global and not initialized must have “global:” (includes for loop initializations)AvoidUninitializedVariable
- Global variables should be avoided. AvoidGlobalVars
- Declared variables must be used in more than just their assignment. UseDeclaredVarsMoreThanAssignments
- No trap statments should be used AvoidTrapStatement
- No Invoke-Expression AvoidUsingInvokeExpression
###Severity: Information
###Severity: TBD
- Clear-Host should not be used
- File paths should not be used (UNC)
- Error Handling
- Use -ErrorAction Stop when calling cmdlets
- Use $ErrorActionPreference = 'Stop'/' Continue' when calling non-cmdlets
- Avoid using flags to handle errors
- Avoid using $?
- Avoid testing for a null variable as an error condition
- Copy $Error[0] to your own variable
- Avoid using pipelines in scripts
- If a return type is declared, the cmdlet must return that type. If a type is returned, a return type must be declared.
##Scripting Style ###Severity: Error
###Severity: Warning
- Don't use write-host unless writing to the host is all you want to do AvoidUsingWriteHost
###Severity: Information
- Write comment-based help ProvideCommentHelp
- Use write-verbose to give information to someone running your script ProvideVerboseMessage ###Severity: TBD
- Provide usage Examples
- Use the Notes section for detail on how the tool work
- Should have help on every exported command (including parameter documentation
- Document the version of PowerShell that script was written for
- Indent your code
- Avoid backticks
##Script Security ###Severity: Error
- Password should be secure string AvoidUsingPlainTextForPassword- Should never have both -Username and -Password parameters (should take credentials)UsePSCredentialType
- -ComputerName hardcoded should not be used (information disclosure)AvoidUsingComputerNameHardcoded
- ConvertTo-SecureString with plaintext should not be used (information disclosure) AvoidUsingConvertToSecureStringWithPlainText
###Severity: Warning
- Password = 'string' should not be used. (information disclosure) AvoidUsingUsernameAndPasswordParams
- Internal URLs should not be used (information disclosure)AvoidUsingFilePath
###Severity: Information
###Severity: TBD
- APIKey and Credentials variables that are initialized (information disclosure)
##DSC Related Rules ###Severity: Error
- Use standard DSC methods [UseStandardDSCFunctionsInResource](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseStandardDSC FunctionsInResource.md)
- Use identical mandatory parameters for all DSC methods UseIdenticalMandatoryParametersDSC
- Use identical parameters for Set and Test DSC methods UseIdenticalParametersDSC
###Severity: Warning
###Severity: Information
- All of the following three rule are grouped by: ReturnCorrectTypeDSCFunctions
- Avoid return any object from a Set-TargetResource or Set (Class Based) function
- Returning a Boolean object from a Test-TargetResource or Test (Class Based) function
- Returning an object from a Get-TargetResource or Get (Class Based) function
- DSC resources should have DSC tests DSCTestsPresent
- DSC resources should have DSC examples DSCExamplesPresent
###Severity: TBD
- For PowerShell V4: Resource module contains .psd1 file and schema.mof for every resource
- MOF has description for each element IssueOpened
- Resource module must contain .psd1 file (always) and schema.mof (for non-class resource). IssueOpened
- Use ShouldProcess for a Set DSC method
- Resource module contains DscResources folder which contains the resources IssueOpened
###Reference:
- Cmdlet Development Guidelines from MSDN site (Cmdlet Development Guidelines): https://msdn.microsoft.com/en-us/library/ms714657(v=vs.85).aspx
- The Community Book of PowerShell Practices (Compiled by Don Jones and Matt Penny and the Windows PowerShell Community): https://powershell.org/community-book-of-powershell-practices/
- PowerShell DSC Resource Design and Testing Checklist: https://blogs.msdn.com/b/powershell/archive/2014/11/18/powershell-dsc-resource-design-and-testing-checklist.aspx
- DSC Guidelines can also be found in the DSC Resources Repository: https://github.com/PowerShell/DscResources
- The Unofficial PowerShell Best Practices and Style Guide: https://github.com/PoshCode/PowerShellPracticeAndStyle