From 2d2d537214c3933124a834fb5a78e703414a0386 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 24 Aug 2026 09:44:00 -0500 Subject: [PATCH 1/2] Improve description of the Settings parameter --- .../PSScriptAnalyzer/using-scriptanalyzer.md | 69 +- .../Get-ScriptAnalyzerRule.md | 120 ++-- .../Get-ScriptAnalyzerRule.md.bak | 189 +++++ .../PSScriptAnalyzer/Invoke-Formatter.md | 103 ++- .../PSScriptAnalyzer/Invoke-Formatter.md.bak | 161 +++++ .../PSScriptAnalyzer/Invoke-ScriptAnalyzer.md | 572 +++++++++------ .../Invoke-ScriptAnalyzer.md.bak | 653 ++++++++++++++++++ 7 files changed, 1546 insertions(+), 321 deletions(-) create mode 100644 reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak create mode 100644 reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak create mode 100644 reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak diff --git a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md index 606335d8..e2c6d624 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md @@ -1,6 +1,6 @@ --- description: This article describes various features of PSScriptAnalyzer and how to use them. -ms.date: 01/28/2026 +ms.date: 08/24/2026 title: Using PSScriptAnalyzer --- # Using PSScriptAnalyzer @@ -158,54 +158,71 @@ You can create settings that describe the ScriptAnalyzer rules to include or exc The **Settings** parameter allows you to create a custom configuration for a specific environment. ScriptAnalyzer support the following modes for specifying the settings file: +This parameter accepts the +following types of objects: + +- A path to a `.psd1` file containing a user-defined profile +- A hashtable object containing settings +- The name of a built-in preset + ### Built-in Presets -ScriptAnalyzer ships a set of built-in presets that can be used to analyze scripts. For example, if -you want to run _PowerShell Gallery_ rules on your module, use the following command: +ScriptAnalyzer ships a set of built-in presets that can be used to analyze scripts. The +PSScriptAnalyzer module includes a set of built-in presets that you can use with the **Settings** +parameter. For example, if you want to run _PowerShell Gallery_ rules on your module, use the +following command: ```powershell Invoke-ScriptAnalyzer -Path /path/to/module/ -Settings PSGallery -Recurse ``` -Additionally, you can use other built-in presets, including **DSC** and **CodeFormatting**. -These presets can be tab completed for the **Settings** parameter. - -### Explicit - -The following example excludes two rules from the default set of rules and any rule with a -severity other than **Error** and **Warning**. +You can specify multiple presets by separating them with a comma. You can use tab completion to see +the available presets. The built-in presets are stored in the `Settings` folder of the +**PSScriptAnalyzer** module. You can list the built-in presets by running the following command: ```powershell -# PSScriptAnalyzerSettings.psd1 -@{ - Severity=@('Error','Warning') - ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost') -} +Get-ChildItem "$($(Get-Module PSScriptAnalyzer).ModuleBase)\Settings\*.psd1" ``` -You can then invoke that settings file with `Invoke-ScriptAnalyzer`: - -```powershell -Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1 +```Output + Directory: C:\Users\sewhee\Documents\PowerShell\Modules\psscriptAnalyzer\1.25.0\Settings + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 3/20/2026 6:41 PM 15025 CmdletDesign.psd1 +-a--- 3/20/2026 6:41 PM 16330 CodeFormatting.psd1 +-a--- 3/20/2026 6:41 PM 16331 CodeFormattingAllman.psd1 +-a--- 3/20/2026 6:41 PM 16331 CodeFormattingOTBS.psd1 +-a--- 3/20/2026 6:41 PM 16375 CodeFormattingStroustrup.psd1 +-a--- 3/20/2026 6:41 PM 14674 DSC.psd1 +-a--- 3/20/2026 6:41 PM 15735 PSGallery.psd1 +-a--- 3/20/2026 6:41 PM 15157 ScriptFunctions.psd1 +-a--- 3/20/2026 6:41 PM 14736 ScriptingStyle.psd1 +-a--- 3/20/2026 6:41 PM 14985 ScriptSecurity.psd1 ``` -The next example selects a few rules to execute instead of all the default rules. +To see the rules included in a preset, you can open the `.psd1` file in a text editor. + +### Explicit + +The following example shows how to invoke Script Analyzer with settings that exclude two rules from +the default set of rules and any rule with a severity other than **Error** and **Warning**. ```powershell -# PSScriptAnalyzerSettings.psd1 -@{ - IncludeRules=@('PSAvoidUsingPlainTextForPassword', - 'PSAvoidUsingConvertToSecureStringWithPlainText') +$pssaSettings = @{ + Severity=@('Error','Warning') + ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost') } +Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings $pssaSettings ``` -You can then invoke that settings file: +You could also save that hashtable to a `.psd1` file and then invoke Script Analyzer with that settings file. ```powershell Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1 ``` -### Implicit +### Implicit search If you place a settings file named `PSScriptAnalyzerSettings.psd1` in your project root, **PSScriptAnalyzer** discovers it when you pass the project root as the **Path** parameter. diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md index 3d815b2c..a2b03671 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md +++ b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md @@ -1,23 +1,29 @@ ---- +--- +document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp Module Name: PSScriptAnalyzer -ms.date: 12/12/2024 -online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp -schema: 2.0.0 +ms.date: 08/24/2026 +PlatyPS schema version: 2024-05-01 --- # Get-ScriptAnalyzerRule ## SYNOPSIS + Gets the script analyzer rules on the local computer. ## SYNTAX +### __AllParameterSets + ``` Get-ScriptAnalyzerRule [[-Name] ] [-CustomRulePath ] [-RecurseCustomRulePath] - [-Severity ] [] + [-Severity ] ``` +## ALIASES + ## DESCRIPTION Gets the script analyzer rules on the local computer. You can select rules by Name, Severity, @@ -96,15 +102,21 @@ You can create custom rules using a .NET assembly or a PowerShell module, such a in the GitHub repository. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: CustomizedRulePath - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: True +Type: System.String[] +DefaultValue: None +SupportsWildcards: true +Aliases: +- CustomizedRulePath +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Name @@ -113,15 +125,20 @@ Gets only rules with the specified names or name patterns. Wildcards are support multiple names or patterns, it gets all rules that match any of the name patterns. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules -Accept pipeline input: False -Accept wildcard characters: True +Type: System.String[] +DefaultValue: All rules +SupportsWildcards: true +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -RecurseCustomRulePath @@ -130,15 +147,20 @@ Searches the **CustomRulePath** location recursively to add rules defined in fil of the path. By default, `Get-ScriptAnalyzerRule` adds only the custom rules in the specified path. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Severity @@ -150,23 +172,28 @@ Gets only rules with the specified severity values. Valid values are: - Error ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String[] +DefaultValue: All rules +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### 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). +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -184,6 +211,5 @@ The **RuleInfo** object is a custom object created specifically for Script Analy ## RELATED LINKS -[Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md) - -[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) +- [Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md) +- [PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak new file mode 100644 index 00000000..3d815b2c --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak @@ -0,0 +1,189 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +Module Name: PSScriptAnalyzer +ms.date: 12/12/2024 +online version: https://learn.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 [[-Name] ] [-CustomRulePath ] [-RecurseCustomRulePath] + [-Severity ] [] +``` + +## 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. + +To get information about the rules, see the value of the Description property of each rule. + +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 - Get all Script Analyzer rules on the local computer + +```powershell +Get-ScriptAnalyzerRule +``` + +### EXAMPLE 2 - Gets only rules with the Error severity + +```powershell +Get-ScriptAnalyzerRule -Severity Error +``` + +### EXAMPLE 3 - Run only the DSC rules with the Error severity + +This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** +module. + +```powershell +$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC +$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*" +Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse +``` + +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. + +### EXAMPLE 4 - Get rules by name and severity + +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* +``` + +### EXAMPLE 5 - Get custom rules + +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 +``` + +## PARAMETERS + +### -CustomRulePath + +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. + +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 using a .NET assembly or a PowerShell module, such as the +[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/tree/main/Tests/Engine/CommunityAnalyzerRules) +in the GitHub repository. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: CustomizedRulePath + +Required: False +Position: Named +Default value: None +Accept pipeline input: 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 all rules that match any of the name patterns. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules +Accept pipeline input: 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. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Severity + +Gets only rules with the specified severity values. Valid values are: + +- Information +- Warning +- Error + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules +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 can't pipe input to this cmdlet. + +## OUTPUTS + +### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo + +The **RuleInfo** object is a custom object created specifically for Script Analyzer. + +## NOTES + +## RELATED LINKS + +[Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md) + +[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md index 80711b0b..98c1e486 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md @@ -1,9 +1,10 @@ ---- +--- +document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-formatter?view=ps-modules&wt.mc_id=ps-gethelp Module Name: PSScriptAnalyzer -ms.date: 10/07/2021 -online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-formatter?view=ps-modules&wt.mc_id=ps-gethelp -schema: 2.0.0 +ms.date: 08/24/2026 +PlatyPS schema version: 2024-05-01 --- # Invoke-Formatter @@ -14,11 +15,14 @@ Formats a script text based on the input settings or default settings. ## SYNTAX +### __AllParameterSets + ``` Invoke-Formatter [-ScriptDefinition] [[-Settings] ] [[-Range] ] - [] ``` +## ALIASES + ## DESCRIPTION The `Invoke-Formatter` cmdlet takes a string input and formats it according to defined settings. If @@ -97,15 +101,20 @@ values in this order: - ending column number ```yaml -Type: Int32[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: True -Accept wildcard characters: False +Type: System.Int32[] +DefaultValue: None +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -ScriptDefinition @@ -114,15 +123,20 @@ The text of the script to be formatted represented as a string. This is not a ** object. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Type: System.String +DefaultValue: None +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Settings @@ -130,26 +144,43 @@ Accept wildcard characters: False A settings hashtable or a path to a PowerShell data file (`.psd1`) that contains the settings. ```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: CodeFormatting -Accept pipeline input: True -Accept wildcard characters: False +Type: System.Object +DefaultValue: CodeFormatting +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### 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). +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS +### System.String + +The **ScriptDefinition** parameter accepts a string from the pipeline. + +### System.Object + +The **Settings** parameter accepts values from the pipeline. + +### System.Int32[] + +The **Range** parameter accepts input from the pipeline. + ## OUTPUTS ### System.String @@ -159,3 +190,5 @@ The formatted string result. ## NOTES ## RELATED LINKS + +- [Using PSScriptAnalyzer](/powershell/utility-modules/psscriptanalyzer/using-scriptanalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak new file mode 100644 index 00000000..80711b0b --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak @@ -0,0 +1,161 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +Module Name: PSScriptAnalyzer +ms.date: 10/07/2021 +online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-formatter?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Invoke-Formatter + +## SYNOPSIS + +Formats a script text based on the input settings or default settings. + +## SYNTAX + +``` +Invoke-Formatter [-ScriptDefinition] [[-Settings] ] [[-Range] ] + [] +``` + +## DESCRIPTION + +The `Invoke-Formatter` cmdlet takes a string input and formats it according to defined settings. If +no **Settings** parameter is provided, the cmdlet assumes the default code formatting settings as +defined in `Settings/CodeFormatting.psd1`. + +## EXAMPLES + +### EXAMPLE 1 - Format the input script text using the default settings + +```powershell +$scriptDefinition = @' +function foo { +"hello" + } +'@ + +Invoke-Formatter -ScriptDefinition $scriptDefinition +``` + +```Output +function foo { + "hello" +} +``` + +### EXAMPLE 2 - Format the input script using the settings defined in a hashtable + +```powershell +$scriptDefinition = @' +function foo { +"hello" +} +'@ + +$settings = @{ + IncludeRules = @("PSPlaceOpenBrace", "PSUseConsistentIndentation") + Rules = @{ + PSPlaceOpenBrace = @{ + Enable = $true + OnSameLine = $false + } + PSUseConsistentIndentation = @{ + Enable = $true + } + } +} + +Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings $settings +``` + +```Output +function foo +{ + "hello" +} +``` + +### EXAMPLE 3 - Format the input script text using the settings defined in a `.psd1` file + +```powershell +Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings /path/to/settings.psd1 +``` + +## PARAMETERS + +### -Range + +The range within which formatting should take place. The value of this parameter must be an array of +four integers. These numbers must be greater than 0. The four integers represent the following four +values in this order: + +- starting line number +- starting column number +- ending line number +- ending column number + +```yaml +Type: Int32[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: True +Accept wildcard characters: False +``` + +### -ScriptDefinition + +The text of the script to be formatted represented as a string. This is not a **ScriptBlock** +object. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Settings + +A settings hashtable or a path to a PowerShell data file (`.psd1`) that contains the settings. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: CodeFormatting +Accept pipeline input: True +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 + +## OUTPUTS + +### System.String + +The formatted string result. + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md index f1350a26..9a24e4cd 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md @@ -1,14 +1,16 @@ ---- +--- +document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp Module Name: PSScriptAnalyzer -ms.date: 07/23/2026 -online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp -schema: 2.0.0 +ms.date: 08/24/2026 +PlatyPS schema version: 2024-05-01 --- # Invoke-ScriptAnalyzer ## SYNOPSIS + Evaluates a script or module based on selected best practice rules ## SYNTAX @@ -26,31 +28,31 @@ Invoke-ScriptAnalyzer [-Path] [-CustomRulePath ] [-RecurseCus ``` Invoke-ScriptAnalyzer [-Path] -IncludeSuppressed [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-Fix] [-EnableExit] - [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] - [] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] [-IncludeRule ] + [-Severity ] [-Recurse] [-Fix] [-EnableExit] [-Settings ] [-SaveDscDependency] + [-ReportSummary] [-WhatIf] [-Confirm] ``` ### ScriptDefinition_IncludeSuppressed ``` Invoke-ScriptAnalyzer [-ScriptDefinition] -IncludeSuppressed [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-EnableExit] [-Settings ] - [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] [] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] [-IncludeRule ] + [-Severity ] [-Recurse] [-EnableExit] [-Settings ] [-SaveDscDependency] + [-ReportSummary] [-WhatIf] [-Confirm] ``` ### ScriptDefinition_SuppressedOnly ``` Invoke-ScriptAnalyzer [-ScriptDefinition] [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-SuppressedOnly] [-EnableExit] - [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] - [] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] [-IncludeRule ] + [-Severity ] [-Recurse] [-SuppressedOnly] [-EnableExit] [-Settings ] + [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] [] ``` +## ALIASES + ## DESCRIPTION `Invoke-ScriptAnalyzer` evaluates scripts or module files (`.ps1`, `.psm1`, and `.psd1` files) based @@ -234,6 +236,28 @@ When you use the **ScriptDefinition** parameter, the **FileName** property of th ## PARAMETERS +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + ### -CustomRulePath Enter the path to a file that defines rules or a directory that contains files that define rules. @@ -245,15 +269,21 @@ To add rules defined in subdirectories of the path, use the **RecurseCustomRuleP include the built-in rules, add the **IncludeDefaultRules** parameter. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: CustomizedRulePath - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: True +Type: System.String[] +DefaultValue: None +SupportsWildcards: true +Aliases: +- CustomizedRulePath +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -EnableExit @@ -262,15 +292,20 @@ On completion of the analysis, this parameter exits the PowerShell sessions and equal to the number of error records. This can be useful in continuous integration (CI) pipeline. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -ExcludeRule @@ -289,15 +324,20 @@ If a rule is specified in both the **ExcludeRule** and **IncludeRule** collectio excluded. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules are included. -Accept pipeline input: False -Accept wildcard characters: True +Type: System.String[] +DefaultValue: All rules are included. +SupportsWildcards: true +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Fix @@ -309,15 +349,26 @@ sure that you have a backup of your files when using this parameter. It tries to encoding but there are still some cases where the encoding can change. ```yaml -Type: SwitchParameter -Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Path_IncludeSuppressed + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Path_SuppressedOnly + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -IncludeDefaultRules @@ -325,15 +376,20 @@ Accept wildcard characters: False Invoke default rules along with Custom rules. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -IncludeRule @@ -355,15 +411,20 @@ The **Severity** parameter takes precedence over **IncludeRule**. For example, i `Error`, you cannot use **IncludeRule** to include a `Warning` rule. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules are included. -Accept pipeline input: False -Accept wildcard characters: True +Type: System.String[] +DefaultValue: All rules are included. +SupportsWildcards: true +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -IncludeSuppressed @@ -371,15 +432,26 @@ Accept wildcard characters: True Include suppressed diagnostics in output. ```yaml -Type: SwitchParameter -Parameter Sets: Path_IncludeSuppressed, ScriptDefinition_IncludeSuppressed -Aliases: - -Required: True -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Path_IncludeSuppressed + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: ScriptDefinition_IncludeSuppressed + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Path @@ -393,15 +465,27 @@ To analyze files that are not in the root directory of the specified path, use a (`C:\Modules\MyModule\*`) or the **Recurse** parameter. ```yaml -Type: String -Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed -Aliases: PSPath - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: True +Type: System.String +DefaultValue: None +SupportsWildcards: true +Aliases: +- PSPath +ParameterSets: +- Name: Path_IncludeSuppressed + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +- Name: Path_SuppressedOnly + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Recurse @@ -412,15 +496,20 @@ Recurse applies only to the Path parameter value. To search the **CustomRulePath the **RecurseCustomRulePath** parameter. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -RecurseCustomRulePath @@ -430,15 +519,20 @@ Adds rules defined in subdirectories of the **CustomRulePath** location. By defa include the built-in rules, use the **IncludeDefaultRules** parameter. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -ReportSummary @@ -446,15 +540,20 @@ Accept wildcard characters: False Write a summary of the violations found to the host. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -SaveDscDependency @@ -471,15 +570,20 @@ module to a temp path. The temp path is then added to `$env:PSModulePath` for du The temp location can be found in `$LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir`. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -ScriptDefinition @@ -488,53 +592,57 @@ Runs the analysis on commands, functions, or expressions in a string. You can us analyze statements, expressions, and functions, independent of their script context. ```yaml -Type: String -Parameter Sets: ScriptDefinition_IncludeSuppressed, ScriptDefinition_SuppressedOnly -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Type: System.String +DefaultValue: None +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: ScriptDefinition_IncludeSuppressed + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +- Name: ScriptDefinition_SuppressedOnly + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Settings -A path to a file containing a user-defined profile or a hashtable object containing settings for -ScriptAnalyzer. - -Runs `Invoke-ScriptAnalyzer` with the parameters and values specified in the file or hashtable. - -If the path or the content of the file or hashtable is invalid, it is ignored. The parameters and -values in the profile take precedence over the same parameter and values specified at the command -line. - -A Script Analyzer profile file is a text file that contains a hashtable with one or more of the -following keys: +Runs `Invoke-ScriptAnalyzer` with the parameters and values specified. This parameter accepts the +following types of objects: -- CustomRulePath -- ExcludeRules -- IncludeDefaultRules -- IncludeRules -- RecurseCustomRulePath -- Rules -- Severity +- A path to a `.psd1` file containing a user-defined profile +- A hashtable object containing settings +- The name of a built-in preset -The keys and values in the profile are interpreted as if they were standard parameters and values of -`Invoke-ScriptAnalyzer`, similar to splatting. For more information, see -[about_Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). +The parameters and values in the profile take precedence over the same parameter and values +specified at the command line. Invalid values are ignored. You can specify multiple presets by +separating them with a comma. You can use tab completion to see the available presets. ```yaml -Type: Object -Parameter Sets: (All) -Aliases: Profile - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Object +DefaultValue: None +SupportsWildcards: false +Aliases: +- Profile +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -Severity @@ -556,15 +664,20 @@ which rules are run. To filter rules efficiently, use `Get-ScriptAnalyzerRule` t you want to run. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rule violations -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String[] +DefaultValue: All rule violations +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -SuppressedOnly @@ -577,31 +690,26 @@ Returns a **SuppressedRecord** object To suppress a rule, use the **SuppressMessageAttribute**. For help, see the examples. ```yaml -Type: SwitchParameter -Parameter Sets: Path_SuppressedOnly, ScriptDefinition_SuppressedOnly -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Path_SuppressedOnly + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: ScriptDefinition_SuppressedOnly + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### -WhatIf @@ -609,29 +717,35 @@ Accept wildcard characters: False Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### 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). +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS -### None +### System.String -You cannot pipe input to this cmdlet. +The **Path** and **ScriptDefinition** parameters accept a string values from the pipeline. ## OUTPUTS @@ -646,8 +760,40 @@ If you use the **SuppressedOnly** parameter, `Invoke-ScriptAnalyzer` instead ret ## NOTES -## RELATED LINKS +A Script Analyzer profile file is a `.psd1` file that contains a hashtable with one or more of the +following keys: + +- CustomRulePath +- ExcludeRules +- IncludeDefaultRules +- IncludeRules +- RecurseCustomRulePath +- Rules +- Severity -[Get-ScriptAnalyzerRule](Get-ScriptAnalyzerRule.md) +The keys and values in the profile are interpreted as if they were standard parameters and values of +`Invoke-ScriptAnalyzer`, similar to splatting. For more information, see +[about_Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). + +The PSScriptAnalyzer module includes a set of built-in presets that you can use with the +**Settings** parameter. The built-in presets are: + +- CmdletDesign +- CodeFormatting +- CodeFormattingAllman +- CodeFormattingOTBS +- CodeFormattingStroustrup +- DSC +- PSGallery +- ScriptFunctions +- ScriptingStyle +- ScriptSecurity + +You can specify multiple presets by separating them with a comma. You can use tab completion to see +the available presets. + +## RELATED LINKS -[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) +- [Get-ScriptAnalyzerRule](Get-ScriptAnalyzerRule.md) +- [PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) +- [Using PSScriptAnalyzer](/powershell/utility-modules/psscriptanalyzer/using-scriptanalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak new file mode 100644 index 00000000..f1350a26 --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak @@ -0,0 +1,653 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +Module Name: PSScriptAnalyzer +ms.date: 07/23/2026 +online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Invoke-ScriptAnalyzer + +## SYNOPSIS +Evaluates a script or module based on selected best practice rules + +## SYNTAX + +### Path_SuppressedOnly (Default) + +``` +Invoke-ScriptAnalyzer [-Path] [-CustomRulePath ] [-RecurseCustomRulePath] + [-IncludeDefaultRules] [-ExcludeRule ] [-IncludeRule ] [-Severity ] + [-Recurse] [-SuppressedOnly] [-Fix] [-EnableExit] [-Settings ] [-SaveDscDependency] + [-ReportSummary] [-WhatIf] [-Confirm] [] +``` + +### Path_IncludeSuppressed + +``` +Invoke-ScriptAnalyzer [-Path] -IncludeSuppressed [-CustomRulePath ] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] + [-IncludeRule ] [-Severity ] [-Recurse] [-Fix] [-EnableExit] + [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] + [] +``` + +### ScriptDefinition_IncludeSuppressed + +``` +Invoke-ScriptAnalyzer [-ScriptDefinition] -IncludeSuppressed [-CustomRulePath ] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] + [-IncludeRule ] [-Severity ] [-Recurse] [-EnableExit] [-Settings ] + [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] [] +``` + +### ScriptDefinition_SuppressedOnly + +``` +Invoke-ScriptAnalyzer [-ScriptDefinition] [-CustomRulePath ] + [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] + [-IncludeRule ] [-Severity ] [-Recurse] [-SuppressedOnly] [-EnableExit] + [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +`Invoke-ScriptAnalyzer` evaluates scripts or module files (`.ps1`, `.psm1`, and `.psd1` files) based +on a collection of best practice rules and returns objects that represent rule violations. It also +includes special rules to analyze DSC resources. + +`Invoke-ScriptAnalyzer` comes with a set of built-in rules. By default, it uses all rules. You can +use the **IncludeRule** and **ExcludeRule** parameters to select the rules you want. You can use the +`Get-ScriptAnalyzerRule` cmdlet to examine and select the rules you want to include or exclude from +the evaluation. + +You can also use customized rules that you write in PowerShell scripts, or compile in assemblies +using C#. Custom rules can also be selected using the **IncludeRule** and **ExcludeRule** +parameters. + +You can also include a rule in the analysis, but suppress the output of that rule for selected +functions or scripts. This feature should be used only when necessary. To get rules that were +suppressed, run `Invoke-ScriptAnalyzer` with the **SuppressedOnly** parameter. + +For usage in CI systems, the **EnableExit** exits the shell with an exit code equal to the number of +error records. + +## EXAMPLES + +### EXAMPLE 1 - Run all Script Analyzer rules on a script + +```powershell +Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1 +``` + +### EXAMPLE 2 - Run all Script Analyzer rules on all files in the Modules directory + +This example runs all Script Analyzer rules on all `.ps1` and `.psm1` files in your user-based +`Modules` directory and its subdirectories. + +```powershell +Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse +``` + +### EXAMPLE 3 - Run a single rule on a module + +This example runs only the **PSAvoidUsingPositionalParameters** rule on the files in the +`PSDiagnostics` module folder. You can use a command like this to find all instances of a particular +rule violation. + +```powershell +Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters +``` + +### EXAMPLE 4 - Run all rules except two on your modules + +This example runs all rules except for **PSAvoidUsingCmdletAliases** and +**PSAvoidUsingInternalURLs** on the `.ps1` and `.psm1` files in the `MyModules` directory and in its +subdirectories. + +```powershell +$invokeScriptAnalyzerSplat = @{ + Path = 'C:\ps-test\MyModule' + Recurse = $true + ExcludeRule = 'PSAvoidUsingCmdletAliases', 'PSAvoidUsingInternalURLs' +} +Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat +``` + +### EXAMPLE 5 - Run Script Analyzer with custom rules + +This example runs Script Analyzer on `Test-Script.ps1` with the standard rules and rules in the +`C:\CommunityAnalyzerRules` path. + +```powershell +$invokeScriptAnalyzerSplat = @{ + Path = 'D:\test_scripts\Test-Script.ps1' + CustomRulePath = 'C:\CommunityAnalyzerRules' + IncludeDefaultRules = $true +} +Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat +``` + +### EXAMPLE 6 - Run only the rules that are Error severity and have the PSDSC source name + +```powershell +$DSCError = Get-ScriptAnalyzerRule -Severity Error | + Where-Object SourceName -eq PSDSC +$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule" +Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse +``` + +### EXAMPLE 7 - Suppressing rule violations + +This example shows how to suppress the reporting of rule violations in a function and how to +discover rule violations that are suppressed. + +The example uses the `SuppressMessageAttribute` attribute to suppress the **PSUseSingularNouns** and +**PSAvoidUsingCmdletAliases** rules for the `Get-Widgets` function in the `Get-Widgets.ps1` script. +You can use this attribute to suppress a rule for a module, script, class, function, parameter, or +line. + +The first command runs Script Analyzer on the script file containing the function. The output +reports a rule violation. Even though more rules are violated, neither suppressed rule is reported. + +```powershell +function Get-Widgets +{ + [CmdletBinding()] + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")] + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", + Justification="Resolution in progress.")] + Param() + + dir $PSHOME + ... +} + +Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 +``` + +```Output +RuleName Severity FileName Line Message +-------- -------- -------- ---- ------- +PSProvideCommentHelp Information ManageProfiles.psm1 14 The cmdlet 'Get-Widget' does not have a help comment. +``` + +```powershell +Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly +``` + +```Output +Rule Name Severity File Name Line Justification +--------- -------- --------- ---- ------------- +PSAvoidUsingCmdletAliases Warning ManageProfiles.psm1 21 Resolution in progress. +PSUseSingularNouns Warning ManageProfiles.psm1 14 +``` + +The second command uses the **SuppressedOnly** parameter to report violations of the rules that are +suppressed script file. + +### EXAMPLE 8 - Analyze script files using a profile definition + +In this example, we create a Script Analyzer profile and save it in the `ScriptAnalyzerProfile.txt` +file in the current directory. We run `Invoke-ScriptAnalyzer` on the **BitLocker** module files. The +value of the **Profile** parameter is the path to the Script Analyzer profile. + +```powershell +# In .\ScriptAnalyzerProfile.txt +@{ + Severity = @('Error', 'Warning') + IncludeRules = 'PSAvoid*' + ExcludeRules = '*WriteHost' +} + +Invoke-ScriptAnalyzer -Path $PSHOME\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt +``` + +If you include a conflicting parameter in the `Invoke-ScriptAnalyzer` command, such as +`-Severity Error`, the cmdlet uses the profile value and ignores the parameter. + +### EXAMPLE 9 - Analyze a script stored as a string + +This example uses the **ScriptDefinition** parameter to analyze a function at the command line. The +function string is enclosed in quotation marks. + +```powershell +Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}" +``` + +```Output +RuleName Severity FileName Line Message +-------- -------- -------- ---- ------- +PSAvoidUsingWriteHost Warning 1 Script definition uses Write-Host. Avoid using + Write-Host because it might not work in all hosts, + does not work when there is no host, and (prior + to PS 5.0) cannot be suppressed, captured, or + redirected. Instead, use Write-Output, Write-Verbose, + or Write-Information. +PSUseSingularNouns Warning 1 The cmdlet 'Get-Widgets' uses a plural noun. A + singular noun should be used instead. +``` + +When you use the **ScriptDefinition** parameter, the **FileName** property of the +**DiagnosticRecord** object is `$null`. + +## PARAMETERS + +### -CustomRulePath + +Enter the path to a file that defines rules or a directory that contains files that define rules. +Wildcard characters are supported. When **CustomRulePath** is specified, only the custom rules found +in the specified paths are used for the analysis. If `Invoke-ScriptAnalyzer` cannot find rules in +the , it runs the standard rules without notice. + +To add rules defined in subdirectories of the path, use the **RecurseCustomRulePath** parameter. To +include the built-in rules, add the **IncludeDefaultRules** parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: CustomizedRulePath + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -EnableExit + +On completion of the analysis, this parameter exits the PowerShell sessions and returns an exit code +equal to the number of error records. This can be useful in continuous integration (CI) pipeline. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExcludeRule + +Omits the specified rules from the Script Analyzer test. Wildcard characters are supported. + +Enter a comma-separated list of rule names, a variable that contains rule names, or a command that +gets rule names. You can also specify a list of excluded rules in a Script Analyzer profile file. +You can exclude standard rules and rules in a custom rule path. + +When you exclude a rule, the rule does not run on any of the files in the path. To exclude a rule on +a particular line, parameter, function, script, or class, adjust the Path parameter or suppress the +rule. For information about suppressing a rule, see the examples. + +If a rule is specified in both the **ExcludeRule** and **IncludeRule** collections, the rule is +excluded. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules are included. +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -Fix + +Fixes certain warnings that contain a fix in their **DiagnosticRecord**. + +When you used **Fix**, `Invoke-ScriptAnalyzer` applies the fixes before running the analysis. Make +sure that you have a backup of your files when using this parameter. It tries to preserve the file +encoding but there are still some cases where the encoding can change. + +```yaml +Type: SwitchParameter +Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeDefaultRules + +Invoke default rules along with Custom rules. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeRule + +Runs only the specified rules in the Script Analyzer test. By default, PSScriptAnalyzer runs all +rules. + +Enter a comma-separated list of rule names, a variable that contains rule names, or a command that +gets rule names. Wildcard characters are supported. You can also specify rule names in a Script +Analyzer profile file. + +When you use the **CustomizedRulePath** parameter, you can use this parameter to include standard +rules and rules in the custom rule paths. + +If a rule is specified in both the **ExcludeRule** and **IncludeRule** collections, the rule is +excluded. + +The **Severity** parameter takes precedence over **IncludeRule**. For example, if **Severity** is +`Error`, you cannot use **IncludeRule** to include a `Warning` rule. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules are included. +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -IncludeSuppressed + +Include suppressed diagnostics in output. + +```yaml +Type: SwitchParameter +Parameter Sets: Path_IncludeSuppressed, ScriptDefinition_IncludeSuppressed +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path + +Specifies the path to the scripts or module to be analyzed. Wildcard characters are supported. + +Enter the path to a script (`.ps1`) or module file (`.psm1`) or to a directory that contains scripts +or modules. If the directory contains other types of files, they are ignored. + +To analyze files that are not in the root directory of the specified path, use a wildcard character +(`C:\Modules\MyModule\*`) or the **Recurse** parameter. + +```yaml +Type: String +Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed +Aliases: PSPath + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: True +``` + +### -Recurse + +Runs Script Analyzer on the files in the **Path** directory and all subdirectories recursively. + +Recurse applies only to the Path parameter value. To search the **CustomRulePath** recursively, use +the **RecurseCustomRulePath** parameter. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RecurseCustomRulePath + +Adds rules defined in subdirectories of the **CustomRulePath** location. By default, +`Invoke-ScriptAnalyzer` uses only the custom rules defined in the specified file or directory. To +include the built-in rules, use the **IncludeDefaultRules** parameter. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ReportSummary + +Write a summary of the violations found to the host. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SaveDscDependency + +Resolve DSC resource dependencies. + +When `Invoke-ScriptAnalyzer` is run with this parameter, it looks for instances of +`Import-DSCResource -ModuleName `. If `` is cannot be found by searching the +`$env:PSModulePath`, `Invoke-ScriptAnalyzer` returns parse error. This error is caused by the +PowerShell parser not being able to find the symbol for ``. + +If `Invoke-ScriptAnalyzer` finds the module in the PowerShell Gallery, it downloads the missing +module to a temp path. The temp path is then added to `$env:PSModulePath` for duration of the scan. +The temp location can be found in `$LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir`. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ScriptDefinition + +Runs the analysis on commands, functions, or expressions in a string. You can use this feature to +analyze statements, expressions, and functions, independent of their script context. + +```yaml +Type: String +Parameter Sets: ScriptDefinition_IncludeSuppressed, ScriptDefinition_SuppressedOnly +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Settings + +A path to a file containing a user-defined profile or a hashtable object containing settings for +ScriptAnalyzer. + +Runs `Invoke-ScriptAnalyzer` with the parameters and values specified in the file or hashtable. + +If the path or the content of the file or hashtable is invalid, it is ignored. The parameters and +values in the profile take precedence over the same parameter and values specified at the command +line. + +A Script Analyzer profile file is a text file that contains a hashtable with one or more of the +following keys: + +- CustomRulePath +- ExcludeRules +- IncludeDefaultRules +- IncludeRules +- RecurseCustomRulePath +- Rules +- Severity + +The keys and values in the profile are interpreted as if they were standard parameters and values of +`Invoke-ScriptAnalyzer`, similar to splatting. For more information, see +[about_Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: Profile + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Severity + +After running Script Analyzer with all rules, this parameter selects rule violations with the +specified severity. + +Valid values are: + +- Error +- Warning +- Information +- ParseError + +You can specify one or more severity values. + +The parameter filters the rule violation output only after running all rules. It doesn't filter +which rules are run. To filter rules efficiently, use `Get-ScriptAnalyzerRule` to select the rules +you want to run. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rule violations +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SuppressedOnly + +Returns violations only for rules that are suppressed. + +Returns a **SuppressedRecord** object +(**Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord**). + +To suppress a rule, use the **SuppressMessageAttribute**. For help, see the examples. + +```yaml +Type: SwitchParameter +Parameter Sets: Path_SuppressedOnly, ScriptDefinition_SuppressedOnly +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +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.DiagnosticRecord + +By default, `Invoke-ScriptAnalyzer` returns one **DiagnosticRecord** object for each rule violation. + +### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord + +If you use the **SuppressedOnly** parameter, `Invoke-ScriptAnalyzer` instead returns a +**SuppressedRecord** objects. + +## NOTES + +## RELATED LINKS + +[Get-ScriptAnalyzerRule](Get-ScriptAnalyzerRule.md) + +[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) From 28cd14129e6895cd9c701761c485e5e7891b83e8 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 24 Aug 2026 10:18:54 -0500 Subject: [PATCH 2/2] Copilot feedback --- .../PSScriptAnalyzer/using-scriptanalyzer.md | 4 +- .../Get-ScriptAnalyzerRule.md | 2 +- .../Get-ScriptAnalyzerRule.md.bak | 189 ----- .../PSScriptAnalyzer/Invoke-Formatter.md | 2 +- .../PSScriptAnalyzer/Invoke-Formatter.md.bak | 161 ----- .../PSScriptAnalyzer/Invoke-ScriptAnalyzer.md | 2 +- .../Invoke-ScriptAnalyzer.md.bak | 653 ------------------ 7 files changed, 4 insertions(+), 1009 deletions(-) delete mode 100644 reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak delete mode 100644 reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak delete mode 100644 reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak diff --git a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md index e2c6d624..3814fc79 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md @@ -156,10 +156,8 @@ Param() You can create settings that describe the ScriptAnalyzer rules to include or exclude based on **Severity**. Use the **Settings** parameter of `Invoke-ScriptAnalyzer` to specify configuration. The **Settings** parameter allows you to create a custom configuration for a specific environment. -ScriptAnalyzer support the following modes for specifying the settings file: -This parameter accepts the -following types of objects: +This parameter accepts the following types of objects: - A path to a `.psd1` file containing a user-defined profile - A hashtable object containing settings diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md index a2b03671..0b8b46f4 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md +++ b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md @@ -1,4 +1,4 @@ ---- +--- document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/get-scriptanalyzerrule?view=ps-modules&wt.mc_id=ps-gethelp diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak deleted file mode 100644 index 3d815b2c..00000000 --- a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md.bak +++ /dev/null @@ -1,189 +0,0 @@ ---- -external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml -Module Name: PSScriptAnalyzer -ms.date: 12/12/2024 -online version: https://learn.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 [[-Name] ] [-CustomRulePath ] [-RecurseCustomRulePath] - [-Severity ] [] -``` - -## 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. - -To get information about the rules, see the value of the Description property of each rule. - -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 - Get all Script Analyzer rules on the local computer - -```powershell -Get-ScriptAnalyzerRule -``` - -### EXAMPLE 2 - Gets only rules with the Error severity - -```powershell -Get-ScriptAnalyzerRule -Severity Error -``` - -### EXAMPLE 3 - Run only the DSC rules with the Error severity - -This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** -module. - -```powershell -$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC -$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*" -Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse -``` - -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. - -### EXAMPLE 4 - Get rules by name and severity - -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* -``` - -### EXAMPLE 5 - Get custom rules - -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 -``` - -## PARAMETERS - -### -CustomRulePath - -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. - -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 using a .NET assembly or a PowerShell module, such as the -[Community Analyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/tree/main/Tests/Engine/CommunityAnalyzerRules) -in the GitHub repository. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: CustomizedRulePath - -Required: False -Position: Named -Default value: None -Accept pipeline input: 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 all rules that match any of the name patterns. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules -Accept pipeline input: 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. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Severity - -Gets only rules with the specified severity values. Valid values are: - -- Information -- Warning -- Error - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules -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 can't pipe input to this cmdlet. - -## OUTPUTS - -### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo - -The **RuleInfo** object is a custom object created specifically for Script Analyzer. - -## NOTES - -## RELATED LINKS - -[Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md) - -[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md index 98c1e486..028e6533 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md @@ -1,4 +1,4 @@ ---- +--- document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-formatter?view=ps-modules&wt.mc_id=ps-gethelp diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak deleted file mode 100644 index 80711b0b..00000000 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md.bak +++ /dev/null @@ -1,161 +0,0 @@ ---- -external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml -Module Name: PSScriptAnalyzer -ms.date: 10/07/2021 -online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-formatter?view=ps-modules&wt.mc_id=ps-gethelp -schema: 2.0.0 ---- - -# Invoke-Formatter - -## SYNOPSIS - -Formats a script text based on the input settings or default settings. - -## SYNTAX - -``` -Invoke-Formatter [-ScriptDefinition] [[-Settings] ] [[-Range] ] - [] -``` - -## DESCRIPTION - -The `Invoke-Formatter` cmdlet takes a string input and formats it according to defined settings. If -no **Settings** parameter is provided, the cmdlet assumes the default code formatting settings as -defined in `Settings/CodeFormatting.psd1`. - -## EXAMPLES - -### EXAMPLE 1 - Format the input script text using the default settings - -```powershell -$scriptDefinition = @' -function foo { -"hello" - } -'@ - -Invoke-Formatter -ScriptDefinition $scriptDefinition -``` - -```Output -function foo { - "hello" -} -``` - -### EXAMPLE 2 - Format the input script using the settings defined in a hashtable - -```powershell -$scriptDefinition = @' -function foo { -"hello" -} -'@ - -$settings = @{ - IncludeRules = @("PSPlaceOpenBrace", "PSUseConsistentIndentation") - Rules = @{ - PSPlaceOpenBrace = @{ - Enable = $true - OnSameLine = $false - } - PSUseConsistentIndentation = @{ - Enable = $true - } - } -} - -Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings $settings -``` - -```Output -function foo -{ - "hello" -} -``` - -### EXAMPLE 3 - Format the input script text using the settings defined in a `.psd1` file - -```powershell -Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings /path/to/settings.psd1 -``` - -## PARAMETERS - -### -Range - -The range within which formatting should take place. The value of this parameter must be an array of -four integers. These numbers must be greater than 0. The four integers represent the following four -values in this order: - -- starting line number -- starting column number -- ending line number -- ending column number - -```yaml -Type: Int32[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: True -Accept wildcard characters: False -``` - -### -ScriptDefinition - -The text of the script to be formatted represented as a string. This is not a **ScriptBlock** -object. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Settings - -A settings hashtable or a path to a PowerShell data file (`.psd1`) that contains the settings. - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: CodeFormatting -Accept pipeline input: True -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 - -## OUTPUTS - -### System.String - -The formatted string result. - -## NOTES - -## RELATED LINKS diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md index 9a24e4cd..e7b1788b 100644 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md @@ -1,4 +1,4 @@ ---- +--- document type: cmdlet external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml HelpUri: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak deleted file mode 100644 index f1350a26..00000000 --- a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md.bak +++ /dev/null @@ -1,653 +0,0 @@ ---- -external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml -Module Name: PSScriptAnalyzer -ms.date: 07/23/2026 -online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp -schema: 2.0.0 ---- - -# Invoke-ScriptAnalyzer - -## SYNOPSIS -Evaluates a script or module based on selected best practice rules - -## SYNTAX - -### Path_SuppressedOnly (Default) - -``` -Invoke-ScriptAnalyzer [-Path] [-CustomRulePath ] [-RecurseCustomRulePath] - [-IncludeDefaultRules] [-ExcludeRule ] [-IncludeRule ] [-Severity ] - [-Recurse] [-SuppressedOnly] [-Fix] [-EnableExit] [-Settings ] [-SaveDscDependency] - [-ReportSummary] [-WhatIf] [-Confirm] [] -``` - -### Path_IncludeSuppressed - -``` -Invoke-ScriptAnalyzer [-Path] -IncludeSuppressed [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-Fix] [-EnableExit] - [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] - [] -``` - -### ScriptDefinition_IncludeSuppressed - -``` -Invoke-ScriptAnalyzer [-ScriptDefinition] -IncludeSuppressed [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-EnableExit] [-Settings ] - [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] [] -``` - -### ScriptDefinition_SuppressedOnly - -``` -Invoke-ScriptAnalyzer [-ScriptDefinition] [-CustomRulePath ] - [-RecurseCustomRulePath] [-IncludeDefaultRules] [-ExcludeRule ] - [-IncludeRule ] [-Severity ] [-Recurse] [-SuppressedOnly] [-EnableExit] - [-Settings ] [-SaveDscDependency] [-ReportSummary] [-WhatIf] [-Confirm] - [] -``` - -## DESCRIPTION - -`Invoke-ScriptAnalyzer` evaluates scripts or module files (`.ps1`, `.psm1`, and `.psd1` files) based -on a collection of best practice rules and returns objects that represent rule violations. It also -includes special rules to analyze DSC resources. - -`Invoke-ScriptAnalyzer` comes with a set of built-in rules. By default, it uses all rules. You can -use the **IncludeRule** and **ExcludeRule** parameters to select the rules you want. You can use the -`Get-ScriptAnalyzerRule` cmdlet to examine and select the rules you want to include or exclude from -the evaluation. - -You can also use customized rules that you write in PowerShell scripts, or compile in assemblies -using C#. Custom rules can also be selected using the **IncludeRule** and **ExcludeRule** -parameters. - -You can also include a rule in the analysis, but suppress the output of that rule for selected -functions or scripts. This feature should be used only when necessary. To get rules that were -suppressed, run `Invoke-ScriptAnalyzer` with the **SuppressedOnly** parameter. - -For usage in CI systems, the **EnableExit** exits the shell with an exit code equal to the number of -error records. - -## EXAMPLES - -### EXAMPLE 1 - Run all Script Analyzer rules on a script - -```powershell -Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1 -``` - -### EXAMPLE 2 - Run all Script Analyzer rules on all files in the Modules directory - -This example runs all Script Analyzer rules on all `.ps1` and `.psm1` files in your user-based -`Modules` directory and its subdirectories. - -```powershell -Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse -``` - -### EXAMPLE 3 - Run a single rule on a module - -This example runs only the **PSAvoidUsingPositionalParameters** rule on the files in the -`PSDiagnostics` module folder. You can use a command like this to find all instances of a particular -rule violation. - -```powershell -Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters -``` - -### EXAMPLE 4 - Run all rules except two on your modules - -This example runs all rules except for **PSAvoidUsingCmdletAliases** and -**PSAvoidUsingInternalURLs** on the `.ps1` and `.psm1` files in the `MyModules` directory and in its -subdirectories. - -```powershell -$invokeScriptAnalyzerSplat = @{ - Path = 'C:\ps-test\MyModule' - Recurse = $true - ExcludeRule = 'PSAvoidUsingCmdletAliases', 'PSAvoidUsingInternalURLs' -} -Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat -``` - -### EXAMPLE 5 - Run Script Analyzer with custom rules - -This example runs Script Analyzer on `Test-Script.ps1` with the standard rules and rules in the -`C:\CommunityAnalyzerRules` path. - -```powershell -$invokeScriptAnalyzerSplat = @{ - Path = 'D:\test_scripts\Test-Script.ps1' - CustomRulePath = 'C:\CommunityAnalyzerRules' - IncludeDefaultRules = $true -} -Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat -``` - -### EXAMPLE 6 - Run only the rules that are Error severity and have the PSDSC source name - -```powershell -$DSCError = Get-ScriptAnalyzerRule -Severity Error | - Where-Object SourceName -eq PSDSC -$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule" -Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse -``` - -### EXAMPLE 7 - Suppressing rule violations - -This example shows how to suppress the reporting of rule violations in a function and how to -discover rule violations that are suppressed. - -The example uses the `SuppressMessageAttribute` attribute to suppress the **PSUseSingularNouns** and -**PSAvoidUsingCmdletAliases** rules for the `Get-Widgets` function in the `Get-Widgets.ps1` script. -You can use this attribute to suppress a rule for a module, script, class, function, parameter, or -line. - -The first command runs Script Analyzer on the script file containing the function. The output -reports a rule violation. Even though more rules are violated, neither suppressed rule is reported. - -```powershell -function Get-Widgets -{ - [CmdletBinding()] - [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")] - [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", - Justification="Resolution in progress.")] - Param() - - dir $PSHOME - ... -} - -Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -``` - -```Output -RuleName Severity FileName Line Message --------- -------- -------- ---- ------- -PSProvideCommentHelp Information ManageProfiles.psm1 14 The cmdlet 'Get-Widget' does not have a help comment. -``` - -```powershell -Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly -``` - -```Output -Rule Name Severity File Name Line Justification ---------- -------- --------- ---- ------------- -PSAvoidUsingCmdletAliases Warning ManageProfiles.psm1 21 Resolution in progress. -PSUseSingularNouns Warning ManageProfiles.psm1 14 -``` - -The second command uses the **SuppressedOnly** parameter to report violations of the rules that are -suppressed script file. - -### EXAMPLE 8 - Analyze script files using a profile definition - -In this example, we create a Script Analyzer profile and save it in the `ScriptAnalyzerProfile.txt` -file in the current directory. We run `Invoke-ScriptAnalyzer` on the **BitLocker** module files. The -value of the **Profile** parameter is the path to the Script Analyzer profile. - -```powershell -# In .\ScriptAnalyzerProfile.txt -@{ - Severity = @('Error', 'Warning') - IncludeRules = 'PSAvoid*' - ExcludeRules = '*WriteHost' -} - -Invoke-ScriptAnalyzer -Path $PSHOME\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt -``` - -If you include a conflicting parameter in the `Invoke-ScriptAnalyzer` command, such as -`-Severity Error`, the cmdlet uses the profile value and ignores the parameter. - -### EXAMPLE 9 - Analyze a script stored as a string - -This example uses the **ScriptDefinition** parameter to analyze a function at the command line. The -function string is enclosed in quotation marks. - -```powershell -Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}" -``` - -```Output -RuleName Severity FileName Line Message --------- -------- -------- ---- ------- -PSAvoidUsingWriteHost Warning 1 Script definition uses Write-Host. Avoid using - Write-Host because it might not work in all hosts, - does not work when there is no host, and (prior - to PS 5.0) cannot be suppressed, captured, or - redirected. Instead, use Write-Output, Write-Verbose, - or Write-Information. -PSUseSingularNouns Warning 1 The cmdlet 'Get-Widgets' uses a plural noun. A - singular noun should be used instead. -``` - -When you use the **ScriptDefinition** parameter, the **FileName** property of the -**DiagnosticRecord** object is `$null`. - -## PARAMETERS - -### -CustomRulePath - -Enter the path to a file that defines rules or a directory that contains files that define rules. -Wildcard characters are supported. When **CustomRulePath** is specified, only the custom rules found -in the specified paths are used for the analysis. If `Invoke-ScriptAnalyzer` cannot find rules in -the , it runs the standard rules without notice. - -To add rules defined in subdirectories of the path, use the **RecurseCustomRulePath** parameter. To -include the built-in rules, add the **IncludeDefaultRules** parameter. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: CustomizedRulePath - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: True -``` - -### -EnableExit - -On completion of the analysis, this parameter exits the PowerShell sessions and returns an exit code -equal to the number of error records. This can be useful in continuous integration (CI) pipeline. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ExcludeRule - -Omits the specified rules from the Script Analyzer test. Wildcard characters are supported. - -Enter a comma-separated list of rule names, a variable that contains rule names, or a command that -gets rule names. You can also specify a list of excluded rules in a Script Analyzer profile file. -You can exclude standard rules and rules in a custom rule path. - -When you exclude a rule, the rule does not run on any of the files in the path. To exclude a rule on -a particular line, parameter, function, script, or class, adjust the Path parameter or suppress the -rule. For information about suppressing a rule, see the examples. - -If a rule is specified in both the **ExcludeRule** and **IncludeRule** collections, the rule is -excluded. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules are included. -Accept pipeline input: False -Accept wildcard characters: True -``` - -### -Fix - -Fixes certain warnings that contain a fix in their **DiagnosticRecord**. - -When you used **Fix**, `Invoke-ScriptAnalyzer` applies the fixes before running the analysis. Make -sure that you have a backup of your files when using this parameter. It tries to preserve the file -encoding but there are still some cases where the encoding can change. - -```yaml -Type: SwitchParameter -Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -IncludeDefaultRules - -Invoke default rules along with Custom rules. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -IncludeRule - -Runs only the specified rules in the Script Analyzer test. By default, PSScriptAnalyzer runs all -rules. - -Enter a comma-separated list of rule names, a variable that contains rule names, or a command that -gets rule names. Wildcard characters are supported. You can also specify rule names in a Script -Analyzer profile file. - -When you use the **CustomizedRulePath** parameter, you can use this parameter to include standard -rules and rules in the custom rule paths. - -If a rule is specified in both the **ExcludeRule** and **IncludeRule** collections, the rule is -excluded. - -The **Severity** parameter takes precedence over **IncludeRule**. For example, if **Severity** is -`Error`, you cannot use **IncludeRule** to include a `Warning` rule. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rules are included. -Accept pipeline input: False -Accept wildcard characters: True -``` - -### -IncludeSuppressed - -Include suppressed diagnostics in output. - -```yaml -Type: SwitchParameter -Parameter Sets: Path_IncludeSuppressed, ScriptDefinition_IncludeSuppressed -Aliases: - -Required: True -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Path - -Specifies the path to the scripts or module to be analyzed. Wildcard characters are supported. - -Enter the path to a script (`.ps1`) or module file (`.psm1`) or to a directory that contains scripts -or modules. If the directory contains other types of files, they are ignored. - -To analyze files that are not in the root directory of the specified path, use a wildcard character -(`C:\Modules\MyModule\*`) or the **Recurse** parameter. - -```yaml -Type: String -Parameter Sets: Path_SuppressedOnly, Path_IncludeSuppressed -Aliases: PSPath - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: True -``` - -### -Recurse - -Runs Script Analyzer on the files in the **Path** directory and all subdirectories recursively. - -Recurse applies only to the Path parameter value. To search the **CustomRulePath** recursively, use -the **RecurseCustomRulePath** parameter. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -RecurseCustomRulePath - -Adds rules defined in subdirectories of the **CustomRulePath** location. By default, -`Invoke-ScriptAnalyzer` uses only the custom rules defined in the specified file or directory. To -include the built-in rules, use the **IncludeDefaultRules** parameter. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ReportSummary - -Write a summary of the violations found to the host. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SaveDscDependency - -Resolve DSC resource dependencies. - -When `Invoke-ScriptAnalyzer` is run with this parameter, it looks for instances of -`Import-DSCResource -ModuleName `. If `` is cannot be found by searching the -`$env:PSModulePath`, `Invoke-ScriptAnalyzer` returns parse error. This error is caused by the -PowerShell parser not being able to find the symbol for ``. - -If `Invoke-ScriptAnalyzer` finds the module in the PowerShell Gallery, it downloads the missing -module to a temp path. The temp path is then added to `$env:PSModulePath` for duration of the scan. -The temp location can be found in `$LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir`. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ScriptDefinition - -Runs the analysis on commands, functions, or expressions in a string. You can use this feature to -analyze statements, expressions, and functions, independent of their script context. - -```yaml -Type: String -Parameter Sets: ScriptDefinition_IncludeSuppressed, ScriptDefinition_SuppressedOnly -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Settings - -A path to a file containing a user-defined profile or a hashtable object containing settings for -ScriptAnalyzer. - -Runs `Invoke-ScriptAnalyzer` with the parameters and values specified in the file or hashtable. - -If the path or the content of the file or hashtable is invalid, it is ignored. The parameters and -values in the profile take precedence over the same parameter and values specified at the command -line. - -A Script Analyzer profile file is a text file that contains a hashtable with one or more of the -following keys: - -- CustomRulePath -- ExcludeRules -- IncludeDefaultRules -- IncludeRules -- RecurseCustomRulePath -- Rules -- Severity - -The keys and values in the profile are interpreted as if they were standard parameters and values of -`Invoke-ScriptAnalyzer`, similar to splatting. For more information, see -[about_Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: Profile - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Severity - -After running Script Analyzer with all rules, this parameter selects rule violations with the -specified severity. - -Valid values are: - -- Error -- Warning -- Information -- ParseError - -You can specify one or more severity values. - -The parameter filters the rule violation output only after running all rules. It doesn't filter -which rules are run. To filter rules efficiently, use `Get-ScriptAnalyzerRule` to select the rules -you want to run. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: All rule violations -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SuppressedOnly - -Returns violations only for rules that are suppressed. - -Returns a **SuppressedRecord** object -(**Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord**). - -To suppress a rule, use the **SuppressMessageAttribute**. For help, see the examples. - -```yaml -Type: SwitchParameter -Parameter Sets: Path_SuppressedOnly, ScriptDefinition_SuppressedOnly -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -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.DiagnosticRecord - -By default, `Invoke-ScriptAnalyzer` returns one **DiagnosticRecord** object for each rule violation. - -### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord - -If you use the **SuppressedOnly** parameter, `Invoke-ScriptAnalyzer` instead returns a -**SuppressedRecord** objects. - -## NOTES - -## RELATED LINKS - -[Get-ScriptAnalyzerRule](Get-ScriptAnalyzerRule.md) - -[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer)