Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes #1722 - Update cmdlet docs for 1.20.0 #1726

Merged
merged 3 commits into from
Oct 12, 2021
Merged

Fixes #1722 - Update cmdlet docs for 1.20.0 #1726

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
25ca70e
Update cmdlet docs for 1.20.0
sdwheeler Oct 7, 2021
775b14e
Removed the test for Remarks
sdwheeler Oct 7, 2021
be3e887
Fix typos
sdwheeler Oct 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions Tests/Engine/ModuleHelp.Tests.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,11 +115,6 @@ Describe "Cmdlet help" {
It "gets example code from <CommandName>" -TestCases $testCases {
($Help.Examples.Example | Select-Object -First 1).Code | Should -Not -BeNullOrEmpty
}

# Should be at least one example description
It "gets example help from $commandName" -TestCases $testCases {
($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty
}
Comment on lines -118 to -122
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're better off not removing tests like this if we can avoid it — it's a nice bar on doc quality that we require examples.

If docs are just being updated, what caused this to fail?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, I wouldn't normally want to remove a test but the Remarks are optional.

The test broke because the Remarks were moved. In some cases, the Remark was incorporated into the Example title. In others it was move before the code block as an intro.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For higher quality, we should be testing the following:

  • every parameter of a cmdlet exists in the markdown
  • each parameter has description
  • the markdown does not contain any parameters that the cmdlet doesn't have

}

Describe 'Cmdlet parameter help' {
Expand Down
143 changes: 82 additions & 61 deletions docs/Cmdlets/Get-ScriptAnalyzerRule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,99 @@
---
---
external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
Module Name: PSScriptAnalyzer
ms.date: 10/07/2021
online version: https://docs.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp
schema: 2.0.0
---

# Get-ScriptAnalyzerRule

## SYNOPSIS
Gets the script analyzer rules on the local computer.

## SYNTAX

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

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

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

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

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.
To get information about the rules, see the value of the Description property of each rule.

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

## EXAMPLES

### -------------------------- EXAMPLE 1 --------------------------
```
### EXAMPLE 1 - Get all Script Analyzer rules on the local computer

```powershell
Get-ScriptAnalyzerRule
```

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

### -------------------------- EXAMPLE 2 --------------------------
```
```powershell
Get-ScriptAnalyzerRule -Severity Error
```

This command gets only rules with the Error severity.

### -------------------------- EXAMPLE 3 --------------------------
```
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
### EXAMPLE 3 - Run only the DSC rules with the Error severity

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

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

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

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.
### EXAMPLE 4 - Get rules by name and severity

### -------------------------- EXAMPLE 4 --------------------------
```
This example gets rules with "Parameter" or "Alias" in the name that generate an Error or Warning.
You can use this set of rules to test the parameters of your script or module.

```powershell
$TestParameters = Get-ScriptAnalyzerRule -Severity Error, Warning -Name *Parameter*, *Alias*
```

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

### -------------------------- EXAMPLE 5 --------------------------
```
This example gets the standard rules and the rules in the **VeryStrictRules** and
**ExtremelyStrictRules** modules. The command uses the **RecurseCustomRulePath** parameter to get
rules defined in subdirectories of the matching paths.

```powershell
Get-ScriptAnalyzerRule -CustomRulePath $home\Documents\WindowsPowerShell\Modules\*StrictRules -RecurseCustomRulePath
```

This command gets the standard rules and the rules in the VeryStrictRules and ExtremelyStrictRules modules.
The command uses the RecurseCustomRulePath parameter to get rules defined in subdirectories of the matching paths.

## PARAMETERS

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

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

You can create custom rules by using a custom .NET assembly or a Windows PowerShell module, such as the Community Analyzer Rules in
https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1.
Enter the path to a .NET assembly or module that contains Script Analyzer rules. You can enter only
one value, but wildcards are supported. To get rules in subdirectories of the path, use the
**RecurseCustomRulePath** parameter.

You can create custom rules by using a custom .NET assembly or a PowerShell module, such as the
[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1)
in the GitHub repository.

```yaml
Type: String[]
Expand All @@ -92,50 +102,52 @@ Aliases: CustomizedRulePath

Required: False
Position: Named
Default value: The rules in Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll.
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Accept wildcard characters: True
```

### -RecurseCustomRulePath
Searches the CustomRulePath location recursively to add rules defined in files in subdirectories of the path.
By default, Get-ScriptAnalyzerRule adds only the custom rules in the specified path.
### -Name

Gets only rules with the specified names or name patterns. Wildcards are supported. If you list
multiple names or patterns, it gets all rules that match any of the name patterns.

```yaml
Type: SwitchParameter
Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value:
Default value: All rules
Accept pipeline input: False
Accept wildcard characters: False
Accept wildcard characters: True
```

### -Name
Gets only rules with the specified names or name patterns.
Wildcards are supported.
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.
### -RecurseCustomRulePath

By default, Get-ScriptAnalyzerRule gets all rules.
Searches the **CustomRulePath** location recursively to add rules defined in files in subdirectories
of the path. By default, `Get-ScriptAnalyzerRule` adds only the custom rules in the specified path.

```yaml
Type: String[]
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: All rules
Default value: False
Accept pipeline input: False
Accept wildcard characters: True
Accept wildcard characters: False
```

### -Severity
Gets only rules with the specified severity values.
Valid values are Information, Warning, and Error.
By default, Get-ScriptAnalyzerRule gets all rules.

Gets only rules with the specified severity values. Valid values are:

- Information
- Warning
- Error

```yaml
Type: String[]
Expand All @@ -149,20 +161,29 @@ Accept pipeline input: False
Accept wildcard characters: False
```

### CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
-WarningAction, and -WarningVariable. For more information, see
[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

### None

You cannot pipe input to this cmdlet.

## OUTPUTS

### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo
The RuleInfo object is a custom object created especially for Script Analyzer. It is not documented on MSDN.

The **RuleInfo** object is a custom object created specifically for Script Analyzer.

## NOTES

## RELATED LINKS

[Invoke-ScriptAnalyzer]()
[Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md)

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