@@ -7,9 +7,9 @@ title: PSScriptAnalyzer rules and recommendations
7
7
8
8
The following guidelines come from a combined effort from both the PowerShell team and the
9
9
community. The guidelines are organized by type. Within each type there is a list of rules. The
10
- rules are grouped by the ** Severity** defined in the implementation of the ** PSScriptAnalyzer** rule.
11
- The severity level labeled as 'TBD' means "To be determined". These are recommendations that do not
12
- currently have rules defined.
10
+ rules are grouped by the ** Severity** defined in the implementation of the ** PSScriptAnalyzer**
11
+ rule. The severity level labeled as 'TBD' means "To be determined". These are recommendations that
12
+ do not currently have rules defined.
13
13
14
14
## Cmdlet Design Rules
15
15
@@ -19,25 +19,25 @@ No rules defined.
19
19
20
20
### Severity: Warning
21
21
22
- - Use Only Approved Verbs [ UseApprovedVerbs] ( Rules/UseApprovedVerbs.md )
23
- - Cmdlets Names: Characters that cannot be Used
22
+ - Use only Approved Verbs [ UseApprovedVerbs] ( Rules/UseApprovedVerbs.md )
23
+ - Cmdlets names with unusable characters
24
24
[ AvoidReservedCharInCmdlet] ( Rules/ReservedCmdletChar.md )
25
- - Parameter Names that cannot be Used
25
+ - Parameter names that cannot be used
26
26
[ AvoidReservedParams] ( Rules/ReservedParams.md )
27
- - Support Confirmation Requests
27
+ - Support confirmation requests
28
28
[ UseShouldProcessForStateChangingFunctions] ( Rules/UseShouldProcessForStateChangingFunctions.md )
29
29
and
30
30
[ UseShouldProcessForStateChangingFunctions] ( Rules/UseShouldProcessForStateChangingFunctions.md )
31
- - Must call ShouldProcess when ShouldProcess attribute is present and vice
32
- versa. [ UseShouldProcess] ( Rules/ShouldProcess.md )
31
+ - Must call ** ShouldProcess** when the ** ShouldProcess** attribute is present and vice
32
+ versa [ UseShouldProcess] ( Rules/ShouldProcess.md )
33
33
- Nouns should be singular
34
34
[ UseSingularNouns] ( Rules/UseSingularNouns.md )
35
- - Module Manifest Fields
35
+ - Missing module manifest fields
36
36
[ MissingModuleManifestField] ( Rules/MissingModuleManifestField.md )
37
- - Version
38
- - Author
39
- - Description
40
- - LicenseUri (for PowerShell Gallery)
37
+ - ** Version**
38
+ - ** Author**
39
+ - ** Description**
40
+ - ** LicenseUri** (for PowerShell Gallery)
41
41
- Switch parameters should not default to true
42
42
[ AvoidDefaultValueSwitchParameter] ( Rules/AvoidDefaultValueSwitchParameter.md )
43
43
@@ -70,24 +70,23 @@ No rules defined.
70
70
71
71
### Severity: Warning
72
72
73
- - Avoid using alias
73
+ - Avoid using aliases
74
74
[ AvoidUsingCmdletAliases] ( Rules/AvoidUsingCmdletAliases.md )
75
75
- Avoid using deprecated WMI cmdlets
76
76
[ AvoidUsingWMICmdlet] ( Rules/AvoidUsingWMICmdlet.md )
77
- - Empty catch block should not be used
78
- [ AvoidUsingEmptyCatchBlock] ( Rules/AvoidUsingEmptyCatchBlock.md )
79
- - Invoke existing cmdlet with correct parameters
77
+ - Avoid using empty ** catch** blocks [ AvoidUsingEmptyCatchBlock] ( Rules/AvoidUsingEmptyCatchBlock.md )
78
+ - Invoke existing cmdlets with correct parameters
80
79
[ UseCmdletCorrectly] ( Rules/UseCmdletCorrectly.md )
81
- - Cmdlets should have ShouldProcess/ ShouldContinue and Force param if certain system-modding verbs
82
- are present (Update, Set, Remove, New):
80
+ - Cmdlets should have ** ShouldProcess** / ** ShouldContinue** and ** Force** parameter if using certain
81
+ system-modifying verbs (Update, Set, Remove, New):
83
82
[ UseShouldProcessForStateChangingFunctions] ( Rules/UseShouldProcessForStateChangingFunctions.md )
84
- - Positional parameters should be avoided
83
+ - Avoid using positional parameters
85
84
[ AvoidUsingPositionalParameters] ( Rules/AvoidUsingPositionalParameters.md )
86
- - Global variables should be avoided.
85
+ - Avoid using global variables
87
86
[ AvoidGlobalVars] ( Rules/AvoidGlobalVars.md )
88
- - Declared variables must be used in more than just their assignment.
87
+ - Declared variables should be used after their assignment
89
88
[ UseDeclaredVarsMoreThanAssignments] ( Rules/UseDeclaredVarsMoreThanAssignments.md )
90
- - No Invoke-Expression
89
+ - Avoid using ` Invoke-Expression `
91
90
[ AvoidUsingInvokeExpression] ( Rules/AvoidUsingInvokeExpression.md )
92
91
93
92
### Severity: Information
@@ -96,11 +95,11 @@ No rules defined.
96
95
97
96
### Severity: TBD
98
97
99
- - ` Clear-Host ` should not be used
100
- - File paths should not be used (UNC)
98
+ - Avoid using ` Clear-Host `
99
+ - Avoid using UNC file paths
101
100
- Error Handling
102
101
- Use ` -ErrorAction Stop ` when calling cmdlets
103
- - Use $ErrorActionPreference = 'Stop'/' Continue' when calling non-cmdlets
102
+ - Use ` $ErrorActionPreference = 'Stop'/'Continue' ` when calling non-cmdlets
104
103
- Avoid using flags to handle errors
105
104
- Avoid using ` $? `
106
105
- Avoid testing for a null variable as an error condition
@@ -117,7 +116,7 @@ No rules defined.
117
116
118
117
### Severity: Warning
119
118
120
- - Don't use ` Write-Host ` unless writing to the host is all you want to do
119
+ - Avoid using ` Write-Host ` unless writing to the host is all you want to do
121
120
[ AvoidUsingWriteHost] ( Rules/AvoidUsingWriteHost.md )
122
121
123
122
### Severity: Information
@@ -129,7 +128,7 @@ No rules defined.
129
128
130
129
- Provide usage Examples
131
130
- Use the Notes section for details on how the tool works
132
- - Should have help on every exported command (including parameter documentation)
131
+ - Every exported command should have help (including parameter documentation)
133
132
- Document the version of PowerShell that the script was written for
134
133
- Indent your code
135
134
- Avoid backticks
@@ -138,18 +137,18 @@ No rules defined.
138
137
139
138
### Severity: Error
140
139
141
- - Password should be secure string
140
+ - Avoid using plain text passwords
142
141
[ AvoidUsingPlainTextForPassword] ( Rules/AvoidUsingPlainTextForPassword.md )
143
- - Should never have both ` -Username ` and ` -Password ` parameters (should take credentials ):
142
+ - Avoid ` -Username ` and ` -Password ` parameters (use ** PSCredential ** instead ):
144
143
[ UsePSCredentialType] ( Rules/UsePSCredentialType.md )
145
- - ` -ComputerName ` Parameter argument hardcoded should not be used (information disclosure):
144
+ - Avoid hardcoding a ` -ComputerName ` parameter argument (information disclosure):
146
145
[ AvoidUsingComputerNameHardcoded] ( Rules/AvoidUsingComputerNameHardcoded.md )
147
- - ConvertTo-SecureString with plaintext should not be used (information disclosure):
146
+ - Avoid using ` ConvertTo-SecureString ` with plaintext (information disclosure):
148
147
[ AvoidUsingConvertToSecureStringWithPlainText] ( Rules/AvoidUsingConvertToSecureStringWithPlainText.md )
149
148
150
149
### Severity: Warning
151
150
152
- - Information disclosure - ` $Password = 'string' ` should not be used .
151
+ - Avoid using ` $Password = 'string' ` (information disclosure) .
153
152
[ AvoidUsingUsernameAndPasswordParams] ( Rules/AvoidUsingUsernameAndPasswordParams.md )
154
153
155
154
### Severity: Information
@@ -158,7 +157,7 @@ No rules defined.
158
157
159
158
### Severity: TBD
160
159
161
- - APIKey and Credentials variables that are initialized (information disclosure)
160
+ - Avoid initializing APIKey and Credentials variables (information disclosure)
162
161
163
162
## DSC Related Rules
164
163
@@ -180,19 +179,20 @@ No rules defined.
180
179
- The following three recommendations are covered by the
181
180
[ ReturnCorrectTypesForDSCFunctions] ( Rules/DSCReturnCorrectTypesForDSCFunctions.md ) rule
182
181
- Avoid returning any object from a ` Set-TargetResource ` or Set (Class Based) function
183
- - Returning a Boolean object from a ` Test-TargetResource ` or Test (Class Based) function
184
- - Returning an object from a ` Get-TargetResource ` or Get (Class Based) function
182
+ - Return a Boolean value from a ` Test-TargetResource ` or Test (Class Based) function
183
+ - Return an object from a ` Get-TargetResource ` or Get (Class Based) function
185
184
- DSC resources should have DSC tests [ DSCTestsPresent] ( Rules/DSCDscTestsPresent.md )
186
185
- DSC resources should have DSC examples [ DSCExamplesPresent] ( Rules/DSCDscExamplesPresent.md )
187
186
188
187
### Severity: TBD
189
188
190
- - For PowerShell V4, Resource module contains ` .psd1 ` file and ` schema.mof ` for every resource
191
- - MOF has description for each element - see
189
+ - For Windows PowerShell v4, resource modules should have a ` .psd1 ` file and ` schema.mof ` for every
190
+ resource
191
+ - MOFs should have a description for each element - see
192
192
[ Issue #131 ] ( https://github.com/PowerShell/PSScriptAnalyzer/issues/131 )
193
- - Resource module must contain .psd1 file (always) and schema.mof (for non-class resource) - see
193
+ - Resource modules should have a ` .psd1 ` file (always) and ` schema.mof ` (for non-class resource) see
194
194
[ Issue #116 ] ( https://github.com/PowerShell/PSScriptAnalyzer/issues/116 )
195
- - Use ShouldProcess for a Set DSC method
195
+ - Use ** ShouldProcess** for a ** Set** DSC method
196
196
- Resource module contains DscResources folder which contains the resources - see
197
197
[ Issue #130 ] ( https://github.com/PowerShell/PSScriptAnalyzer/issues/130 )
198
198
0 commit comments