Skip to content

Commit b063f90

Browse files
sdwheelersdwheeler
authored
Update cmdlet docs for 1.20.0 (#1726)
1 parent 359f98f commit b063f90

5 files changed

+469
-343
lines changed

‎Tests/Engine/ModuleHelp.Tests.ps1

-5
Original file line numberDiff line numberDiff line change
@@ -115,11 +115,6 @@ Describe "Cmdlet help" {
115115
It "gets example code from <CommandName>" -TestCases $testCases {
116116
($Help.Examples.Example | Select-Object -First 1).Code | Should -Not -BeNullOrEmpty
117117
}
118-
119-
# Should be at least one example description
120-
It "gets example help from $commandName" -TestCases $testCases {
121-
($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty
122-
}
123118
}
124119

125120
Describe 'Cmdlet parameter help' {

‎docs/Cmdlets/Get-ScriptAnalyzerRule.md

+82-61
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,99 @@
1-
---
1+
---
22
external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
3+
Module Name: PSScriptAnalyzer
4+
ms.date: 10/07/2021
5+
online version: https://docs.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp
36
schema: 2.0.0
47
---
58

69
# Get-ScriptAnalyzerRule
10+
711
## SYNOPSIS
812
Gets the script analyzer rules on the local computer.
913

1014
## SYNTAX
1115

1216
```
13-
Get-ScriptAnalyzerRule [-CustomRulePath <String>] [-RecurseCustomRulePath] [-Name <String[]>]
14-
[-Severity <String[]>]
17+
Get-ScriptAnalyzerRule [[-Name] <string[]>] [-CustomRulePath <string[]>] [-RecurseCustomRulePath]
18+
[-Severity <string[]>] [<CommonParameters>]
1519
```
1620

1721
## DESCRIPTION
18-
Gets the script analyzer rules on the local computer.
19-
You can select rules by Name, Severity, Source, or SourceType, or even particular words in the rule description.
2022

21-
Use this cmdlet to create collections of rules to include and exclude when running the Invoke-ScriptAnalyzer cmdlet.
23+
Gets the script analyzer rules on the local computer. You can select rules by Name, Severity,
24+
Source, or SourceType, or even particular words in the rule description.
2225

23-
To get information about the rules, see the value of the Description property of each rule.
26+
Use this cmdlet to create collections of rules to include and exclude when running the
27+
`Invoke-ScriptAnalyzer` cmdlet.
2428

25-
The PSScriptAnalyzer module tests the Windows PowerShell code in a script, module, or DSC resource to determine whether, and to what extent, it fulfils best practice standards.
29+
To get information about the rules, see the value of the Description property of each rule.
2630

27-
PSScriptAnalyzer is an open-source project.
28-
For more information about PSScriptAnalyzer, to contribute or file an issue, see GitHub.com\PowerShell\PSScriptAnalyzer.
31+
The PSScriptAnalyzer module tests the PowerShell code in a script, module, or DSC resource to
32+
determine if it fulfils best practice standards.
2933

3034
## EXAMPLES
3135

32-
### -------------------------- EXAMPLE 1 --------------------------
33-
```
36+
### EXAMPLE 1 - Get all Script Analyzer rules on the local computer
37+
38+
```powershell
3439
Get-ScriptAnalyzerRule
3540
```
3641

37-
This command gets all Script Analyzer rules on the local computer.
42+
### EXAMPLE 2 - Gets only rules with the Error severity
3843

39-
### -------------------------- EXAMPLE 2 --------------------------
40-
```
44+
```powershell
4145
Get-ScriptAnalyzerRule -Severity Error
4246
```
4347

44-
This command gets only rules with the Error severity.
45-
46-
### -------------------------- EXAMPLE 3 --------------------------
47-
```
48-
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
48+
### EXAMPLE 3 - Run only the DSC rules with the Error severity
4949

50-
PS C:\>$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
50+
This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule**
51+
module.
5152

52-
PS C:\> Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
53+
```powershell
54+
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
55+
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
56+
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
5357
```
5458

55-
This example runs only the DSC rules with the Error severity on the files in the MyDSCModule module.
59+
Using the **IncludeRule** parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its
60+
**Severity** parameter, which is applied only after using all rules to analyze all module files.
5661

57-
Using the IncludeRule parameter of Invoke-ScriptAnalyzerRule is much more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.
62+
### EXAMPLE 4 - Get rules by name and severity
5863

59-
### -------------------------- EXAMPLE 4 --------------------------
60-
```
64+
This example gets rules with "Parameter" or "Alias" in the name that generate an Error or Warning.
65+
You can use this set of rules to test the parameters of your script or module.
66+
67+
```powershell
6168
$TestParameters = Get-ScriptAnalyzerRule -Severity Error, Warning -Name *Parameter*, *Alias*
6269
```
6370

64-
This command gets rules with "Parameter" or "Alias" in the name that generate an Error or Warning.
65-
Use this set of rules to test the parameters of your script or module.
71+
### EXAMPLE 5 - Get custom rules
6672

67-
### -------------------------- EXAMPLE 5 --------------------------
68-
```
73+
This example gets the standard rules and the rules in the **VeryStrictRules** and
74+
**ExtremelyStrictRules** modules. The command uses the **RecurseCustomRulePath** parameter to get
75+
rules defined in subdirectories of the matching paths.
76+
77+
```powershell
6978
Get-ScriptAnalyzerRule -CustomRulePath $home\Documents\WindowsPowerShell\Modules\*StrictRules -RecurseCustomRulePath
7079
```
7180

72-
This command gets the standard rules and the rules in the VeryStrictRules and ExtremelyStrictRules modules.
73-
The command uses the RecurseCustomRulePath parameter to get rules defined in subdirectories of the matching paths.
74-
7581
## PARAMETERS
7682

7783
### -CustomRulePath
78-
Gets the Script Analyzer rules in the specified path in addition to the standard Script Analyzer rules.
79-
By default, PSScriptAnalyzer gets only the standard rules specified in the Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll file in the module.
8084

81-
Enter the path to a .NET assembly or module that contains Script Analyzer rules.
82-
You can enter only one value, but wildcards are supported.
83-
To get rules in subdirectories of the path, use the RecurseCustomRulePath parameter.
85+
By default, PSScriptAnalyzer gets only the standard rules specified in the
86+
`Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll` file in the module. Use this
87+
parameter to get the custom Script Analyzer rules in the specified path and the standard Script
88+
Analyzer rules.
8489

85-
You can create custom rules by using a custom .NET assembly or a Windows PowerShell module, such as the Community Analyzer Rules in
86-
https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1.
90+
Enter the path to a .NET assembly or module that contains Script Analyzer rules. You can enter only
91+
one value, but wildcards are supported. To get rules in subdirectories of the path, use the
92+
**RecurseCustomRulePath** parameter.
93+
94+
You can create custom rules by using a custom .NET assembly or a PowerShell module, such as the
95+
[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1)
96+
in the GitHub repository.
8797

8898
```yaml
8999
Type: String[]
@@ -92,50 +102,52 @@ Aliases: CustomizedRulePath
92102

93103
Required: False
94104
Position: Named
95-
Default value: The rules in Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll.
105+
Default value: None
96106
Accept pipeline input: False
97-
Accept wildcard characters: False
107+
Accept wildcard characters: True
98108
```
99109
100-
### -RecurseCustomRulePath
101-
Searches the CustomRulePath location recursively to add rules defined in files in subdirectories of the path.
102-
By default, Get-ScriptAnalyzerRule adds only the custom rules in the specified path.
110+
### -Name
111+
112+
Gets only rules with the specified names or name patterns. Wildcards are supported. If you list
113+
multiple names or patterns, it gets all rules that match any of the name patterns.
103114
104115
```yaml
105-
Type: SwitchParameter
116+
Type: String[]
106117
Parameter Sets: (All)
107118
Aliases:
108119

109120
Required: False
110121
Position: Named
111-
Default value:
122+
Default value: All rules
112123
Accept pipeline input: False
113-
Accept wildcard characters: False
124+
Accept wildcard characters: True
114125
```
115126
116-
### -Name
117-
Gets only rules with the specified names or name patterns.
118-
Wildcards are supported.
119-
If you list multiple names or patterns, it gets rules that match any of the name patterns, as though the name patterns were joined by an OR.
127+
### -RecurseCustomRulePath
120128
121-
By default, Get-ScriptAnalyzerRule gets all rules.
129+
Searches the **CustomRulePath** location recursively to add rules defined in files in subdirectories
130+
of the path. By default, `Get-ScriptAnalyzerRule` adds only the custom rules in the specified path.
122131

123132
```yaml
124-
Type: String[]
133+
Type: SwitchParameter
125134
Parameter Sets: (All)
126135
Aliases:
127136
128137
Required: False
129138
Position: Named
130-
Default value: All rules
139+
Default value: False
131140
Accept pipeline input: False
132-
Accept wildcard characters: True
141+
Accept wildcard characters: False
133142
```
134143

135144
### -Severity
136-
Gets only rules with the specified severity values.
137-
Valid values are Information, Warning, and Error.
138-
By default, Get-ScriptAnalyzerRule gets all rules.
145+
146+
Gets only rules with the specified severity values. Valid values are:
147+
148+
- Information
149+
- Warning
150+
- Error
139151

140152
```yaml
141153
Type: String[]
@@ -149,20 +161,29 @@ Accept pipeline input: False
149161
Accept wildcard characters: False
150162
```
151163

164+
### CommonParameters
165+
166+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
167+
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
168+
-WarningAction, and -WarningVariable. For more information, see
169+
[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
170+
152171
## INPUTS
153172

154173
### None
174+
155175
You cannot pipe input to this cmdlet.
156176

157177
## OUTPUTS
158178

159179
### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo
160-
The RuleInfo object is a custom object created especially for Script Analyzer. It is not documented on MSDN.
180+
181+
The **RuleInfo** object is a custom object created specifically for Script Analyzer.
161182

162183
## NOTES
163184

164185
## RELATED LINKS
165186

166-
[Invoke-ScriptAnalyzer]()
187+
[Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md)
167188

168189
[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer)

0 commit comments

Comments
 (0)