diff --git a/docs/Rules/AvoidAssignmentToAutomaticVariable.md b/docs/Rules/AvoidAssignmentToAutomaticVariable.md index a3cff6fba..13c8e6892 100644 --- a/docs/Rules/AvoidAssignmentToAutomaticVariable.md +++ b/docs/Rules/AvoidAssignmentToAutomaticVariable.md @@ -54,6 +54,30 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', '')] +``` + +To suppress the rule for a single automatic variable, pass the variable name without the leading +`$` as the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', 'Error')] + param( + [String]$ErrorMessage + ) + + $Error = "Error occurred: $ErrorMessage" +} +``` + [01]: /powershell/module/microsoft.powershell.core/about/about_automatic_variables -[02]: ../using-scriptanalyzer.md +[02]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidDefaultValueForMandatoryParameter.md b/docs/Rules/AvoidDefaultValueForMandatoryParameter.md index adbbae4d5..5476e718c 100644 --- a/docs/Rules/AvoidDefaultValueForMandatoryParameter.md +++ b/docs/Rules/AvoidDefaultValueForMandatoryParameter.md @@ -56,7 +56,30 @@ this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDefaultValueForMandatoryParameter', '')] +``` + +To suppress the rule for a single parameter, pass the parameter name without the leading `$` as +the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDefaultValueForMandatoryParameter', 'Parameter')] + param( + [Parameter(Mandatory)] + $Parameter = 'Default Value' + ) +} +``` -[02]: ../using-scriptanalyzer.md \ No newline at end of file +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidDynamicallyCreatingVariableNames.md b/docs/Rules/AvoidDynamicallyCreatingVariableNames.md index 6bad0952a..67b496274 100644 --- a/docs/Rules/AvoidDynamicallyCreatingVariableNames.md +++ b/docs/Rules/AvoidDynamicallyCreatingVariableNames.md @@ -69,6 +69,33 @@ Rules = @{ Enable or disable the rule during ScriptAnalyzer invocation. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDynamicallyCreatingVariableNames', '')] +``` + +To suppress the rule for a single `New-Variable` call, pass the value of its `Name` argument +exactly as it's written in the call, without any enclosing double quotes, as the second argument. +For example, use `'My$_'` for `New-Variable -Name "My$_"` and `'$name'` for +`New-Variable -Name $name`. Enclose the second argument in single quotes so that PowerShell +doesn't try to expand it. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDynamicallyCreatingVariableNames', 'My$_')] + param() + + 'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process { + New-Variable -Name "My$_" -Value ($i++) + } +} +``` + ## References - [New-Variable][02] diff --git a/docs/Rules/AvoidGlobalFunctions.md b/docs/Rules/AvoidGlobalFunctions.md index 83b9aec2f..84344259d 100644 --- a/docs/Rules/AvoidGlobalFunctions.md +++ b/docs/Rules/AvoidGlobalFunctions.md @@ -12,7 +12,7 @@ title: AvoidGlobalFunctions ## Description -This rule detects function definitions that use the `global:` scope modifier on the function name to +This rule detects function definitions that use the `Global:` scope modifier on the function name to define a function in the global scope. Global functions can unintentionally override existing functions in the session, leading to unexpected behavior and name collisions. Name collisions make it difficult for module consumers to diagnose issues and maintain code reliability. @@ -25,7 +25,7 @@ scope modifiers. To learn more, see [about_Scopes][01]. ### Noncompliant ```powershell -function global:functionName {} +function Global:functionName {} ``` ### Compliant @@ -44,6 +44,27 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalFunctions', '')] +``` + +To suppress the rule for a single function, pass the function name, including the `Global:` scope +modifier, as the second argument. The name isn't case sensitive. This is useful when the attribute +is applied at module scope and covers more than one function. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalFunctions', 'Global:Test-Script')] +param() + +function Global:Test-Script {} +``` + [01]: /powershell/module/microsoft.powershell.core/about/about_scopes -[02]: ../using-scriptanalyzer.md +[02]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidGlobalVars.md b/docs/Rules/AvoidGlobalVars.md index 0fa48512d..719c99cc8 100644 --- a/docs/Rules/AvoidGlobalVars.md +++ b/docs/Rules/AvoidGlobalVars.md @@ -26,7 +26,7 @@ variables include: This rule doesn't detect use of the `New-Variable` cmdlet to create variables in the global scope or the other `*-Variable` cmdlets to work with variables in the global scope. It only detects variable -expressions with the global scope modifier, like `$global:example`. +expressions with the global scope modifier, like `$Global:example`. This rule doesn't apply to variable expressions that use the global scope modifier where the variable name is for an [automatic variable][01] or a [preference variable][02]. @@ -68,8 +68,32 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][04]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] +``` + +To suppress the rule for a single variable, pass the variable name, including the `Global:` scope +modifier, as the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', 'Global:Variable')] + param( + [String]$Parameter + ) + + $Global:Variable = $Parameter +} +``` + [01]: /powershell/module/microsoft.powershell.core/about/about_automatic_variables [02]: /powershell/module/microsoft.powershell.core/about/about_preference_variables [03]: /powershell/module/microsoft.powershell.core/about/about_scopes -[04]: ../using-scriptanalyzer.md +[04]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md b/docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md index 7df620d86..3e15f6dcd 100644 --- a/docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md +++ b/docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md @@ -83,6 +83,29 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidNullOrEmptyHelpMessageAttribute', '')] +``` + +To suppress the rule for a single parameter, pass the parameter name without the leading `$` as +the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidNullOrEmptyHelpMessageAttribute', 'Parameter')] + param( + [Parameter(HelpMessage = '')] + [String]$Parameter + ) +} +``` + [01]: /powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters#helpmessage-argument -[02]: ../using-scriptanalyzer.md +[02]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md b/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md index 2fe1af79c..5cf169412 100644 --- a/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md +++ b/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md @@ -45,7 +45,30 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][03]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingAllowUnencryptedAuthentication', '')] +``` + +To suppress the rule for a single command, pass the command name as it appears in the call as the +second argument. The name isn't case sensitive, but it must match what's written in the script, so +a call made through an alias needs the alias name. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingAllowUnencryptedAuthentication', 'Invoke-WebRequest')] + param() + + Invoke-WebRequest foo -AllowUnencryptedAuthentication +} +``` + [01]: /powershell/module/microsoft.powershell.utility/invoke-webrequest [02]: /powershell/module/microsoft.powershell.utility/invoke-restmethod -[03]: ../using-scriptanalyzer.md +[03]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingBrokenHashAlgorithms.md b/docs/Rules/AvoidUsingBrokenHashAlgorithms.md index 0306aca68..7fc2a0b90 100644 --- a/docs/Rules/AvoidUsingBrokenHashAlgorithms.md +++ b/docs/Rules/AvoidUsingBrokenHashAlgorithms.md @@ -41,7 +41,30 @@ this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingBrokenHashAlgorithms', '')] +``` + +To suppress the rule for a single command, pass the command name as it appears in the call as the +second argument. The name isn't case sensitive, but it must match what's written in the script, so +a call made through an alias needs the alias name. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingBrokenHashAlgorithms', 'Get-FileHash')] + param() + + Get-FileHash foo.txt -Algorithm MD5 +} +``` -[02]: ../using-scriptanalyzer.md \ No newline at end of file +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingCmdletAliases.md b/docs/Rules/AvoidUsingCmdletAliases.md index 2204a2190..b4cfdc93c 100644 --- a/docs/Rules/AvoidUsingCmdletAliases.md +++ b/docs/Rules/AvoidUsingCmdletAliases.md @@ -65,7 +65,31 @@ using this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', '')] +``` + +To suppress the rule for a single alias, pass the alias as the second argument. For an implicit +alias, pass the command name as it's written without the `Get-` prefix, for example `'verb'` for +`verb`. The name isn't case sensitive. To allow an alias everywhere, use the `allowlist` setting +instead. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', 'gps')] + param() + + gps | Where-Object { $_.WorkingSet -gt 20000000 } +} +``` -[02]: ../using-scriptanalyzer.md \ No newline at end of file +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingComputerNameHardcoded.md b/docs/Rules/AvoidUsingComputerNameHardcoded.md index a58030096..ef9dce39b 100644 --- a/docs/Rules/AvoidUsingComputerNameHardcoded.md +++ b/docs/Rules/AvoidUsingComputerNameHardcoded.md @@ -48,7 +48,30 @@ this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingComputerNameHardcoded', '')] +``` + +To suppress the rule for a single command, pass the command name as it appears in the call as the +second argument. The name isn't case sensitive, but it must match what's written in the script, so +a call made through an alias needs the alias name. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingComputerNameHardcoded', 'Invoke-Command')] + param() + + Invoke-Command -ComputerName HardcodedHostname -Port 343 +} +``` -[02]: ../using-scriptanalyzer.md \ No newline at end of file +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md b/docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md index ac7ffb5c7..871d1b667 100644 --- a/docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md +++ b/docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md @@ -50,7 +50,31 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][03]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingConvertToSecureStringWithPlainText', '')] +``` + +To suppress the rule for a single command, pass the command name as it appears in the call as the +second argument. The name isn't case sensitive, but it must match what's written in the script, so +a call made through an alias needs the alias name. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingConvertToSecureStringWithPlainText', 'ConvertTo-SecureString')] + param() + + $UserInput = Read-Host 'Please enter your secure code' + ConvertTo-SecureString -String $UserInput -AsPlainText -Force +} +``` + [01]: /dotnet/api/system.security.securestring [02]: https://www.powershellgallery.com/packages/Microsoft.PowerShell.SecretStore -[03]: ../using-scriptanalyzer.md +[03]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingPlainTextForPassword.md b/docs/Rules/AvoidUsingPlainTextForPassword.md index d46a30eef..f16c82b46 100644 --- a/docs/Rules/AvoidUsingPlainTextForPassword.md +++ b/docs/Rules/AvoidUsingPlainTextForPassword.md @@ -71,6 +71,28 @@ this rule: - Add the appropriate rule suppression attributes to your code to suppress the rule for specific code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', '')] +``` + +To suppress the rule for a single parameter, pass the parameter name without the leading `$` as +the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', 'Password')] + param( + [String]$Password + ) +} +``` + [01]: /dotnet/api/system.security.securestring -[02]: ../using-scriptanalyzer.md +[02]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/AvoidUsingPositionalParameters.md b/docs/Rules/AvoidUsingPositionalParameters.md index 0bdb64e44..4e11b1c9a 100644 --- a/docs/Rules/AvoidUsingPositionalParameters.md +++ b/docs/Rules/AvoidUsingPositionalParameters.md @@ -59,3 +59,27 @@ array. The default value is `@()`. This parameter controls whether ScriptAnalyzer checks the code against this rule. It accepts a boolean value. To disable this rule, set this parameter to `$false`. The default value is `$true`. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPositionalParameters', '')] +``` + +To suppress the rule for a single command, pass the command name as it appears in the call as the +second argument. The name isn't case sensitive, but it must match what's written in the script, so +a call made through an alias needs the alias name. To exclude a command everywhere, use the +`CommandAllowList` setting instead. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPositionalParameters', 'Set-ItemProperty')] + param() + + Set-ItemProperty foo.txt IsReadOnly $true +} +``` diff --git a/docs/Rules/InvalidMultiDotValue.md b/docs/Rules/InvalidMultiDotValue.md index a5d48ae2e..7efb241fd 100644 --- a/docs/Rules/InvalidMultiDotValue.md +++ b/docs/Rules/InvalidMultiDotValue.md @@ -61,3 +61,26 @@ Rules = @{ - `Enable`: **bool** (Default value is `$false`) Enable or disable the rule during ScriptAnalyzer invocation. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSInvalidMultiDotValue', '')] +``` + +To suppress the rule for a single value, pass the value exactly as it's written in the script as +the second argument, for example `'1.2.3'` or `'127.0.0.1'`. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSInvalidMultiDotValue', '1.2.3')] + param() + + $Version = 1.2.3 + Write-Output $Version +} +``` diff --git a/docs/Rules/MissingTryBlock.md b/docs/Rules/MissingTryBlock.md index 295b0be9b..ad4a1a4b6 100644 --- a/docs/Rules/MissingTryBlock.md +++ b/docs/Rules/MissingTryBlock.md @@ -56,5 +56,27 @@ Rules = @{ Enable or disable the rule during ScriptAnalyzer invocation. +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSMissingTryBlock', '')] +``` + +To suppress the rule for only one of the two keywords, pass `catch` or `finally` as the second +argument. The value isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSMissingTryBlock', 'finally')] + param() + + finally { 'Cleaning up.' } +} +``` + -[01]: AvoidReservedWordsAsFunctionNames.md \ No newline at end of file +[01]: AvoidReservedWordsAsFunctionNames.md diff --git a/docs/Rules/ReviewUnusedParameter.md b/docs/Rules/ReviewUnusedParameter.md index d3bcdb099..e9ee6cbaa 100644 --- a/docs/Rules/ReviewUnusedParameter.md +++ b/docs/Rules/ReviewUnusedParameter.md @@ -74,7 +74,29 @@ using this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')] +``` + +To suppress the rule for a single parameter, pass the parameter name without the leading `$` as +the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'UnusedParameter')] + param( + [String]$UnusedParameter + ) +} +``` -[02]: ../using-scriptanalyzer.md +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/UseCompatibleTypes.md b/docs/Rules/UseCompatibleTypes.md index 658a5a351..aa881eafb 100644 --- a/docs/Rules/UseCompatibleTypes.md +++ b/docs/Rules/UseCompatibleTypes.md @@ -16,7 +16,7 @@ This rule detects types that aren't available by default on your targeted PowerS PowerShell platform names use the following format: -``` +```plain ______ ``` @@ -180,29 +180,28 @@ the `compatibility_profiles` directory in the PSScriptAnalyzer module. This parameter specifies the full names of types or type accelerators to exclude from compatibility checks. It accepts an array of type-name strings. The default value is `@()`. - -[01]: https://github.com/PowerShell/PSScriptAnalyzer/tree/main/PSCompatibilityCollector -[02]: https://github.com/PowerShell/PSScriptAnalyzer/tree/main/PSCompatibilityCollector/optional_profiles - ## Suppression As with other rules, you can suppress type compatibility diagnostics by adding a suppression -attribute to the `param` block of a scriptblock. +attribute to the `param` block of a scriptblock. An empty string as the second argument suppresses +every type compatibility diagnostic in that scope. ```powershell [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', '')] ``` -You can also suppress the rule for specific types: +You can also suppress diagnostics for a specific static member, whether a method, property, +field, or event, by passing the full type name and the member name, separated by `/`, as the +second argument: ```powershell -[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', - 'System.Management.Automation.Security.SystemPolicy')] +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', 'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')] ``` -You can also suppress it for specific type members: +Diagnostics for a type or type accelerator that isn't available on a target platform don't carry a +suppression ID, so they can only be suppressed with an empty second argument. To skip a type +everywhere, add it to the `IgnoreTypes` setting instead. -```powershell -[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', - 'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')] -``` + +[01]: https://github.com/PowerShell/PSScriptAnalyzer/tree/main/PSCompatibilityCollector +[02]: https://github.com/PowerShell/PSScriptAnalyzer/tree/main/PSCompatibilityCollector/optional_profiles diff --git a/docs/Rules/UseCorrectCasing.md b/docs/Rules/UseCorrectCasing.md index 7baa07bdb..c49d0b78c 100644 --- a/docs/Rules/UseCorrectCasing.md +++ b/docs/Rules/UseCorrectCasing.md @@ -82,3 +82,30 @@ accepts a boolean value. The default value is `$true`. This parameter controls whether ScriptAnalyzer checks that all operators are lowercase. For example, `-eq`, `-ne`, and `-gt`. It accepts a boolean value. The default value is `$true`. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCorrectCasing', '')] +``` + +To suppress the rule for a single command, parameter, keyword, or operator, pass its correctly +cased form as the second argument: the canonical command name, such as `Get-ChildItem`, the +canonical parameter name without the leading dash, such as `RunAsAdministrator`, or the lowercase +keyword or operator, such as `foreach` or `-eq`. If a command is written with a module qualifier, +include the qualifier, for example `Microsoft.PowerShell.Management\Get-ChildItem`. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCorrectCasing', 'Get-ChildItem')] + param() + + foreach ($File in Get-childitem -Recurse) { + $File.Extension -eq '.txt' + } +} +``` diff --git a/docs/Rules/UseDeclaredVarsMoreThanAssignments.md b/docs/Rules/UseDeclaredVarsMoreThanAssignments.md index a290689f3..4c7b48f7e 100644 --- a/docs/Rules/UseDeclaredVarsMoreThanAssignments.md +++ b/docs/Rules/UseDeclaredVarsMoreThanAssignments.md @@ -75,7 +75,32 @@ this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')] +``` + +To suppress the rule for a single variable, pass the variable name without the leading `$` as the +second argument. The name isn't case sensitive. This is useful for the false positives described +in the Special cases section. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'UnusedVariable')] + param() + + $UsedVariable = 'Used' + $UnusedVariable = 'Unused' + Write-Output $UsedVariable +} +``` -[02]: ../using-scriptanalyzer.md +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/UseProcessBlockForPipelineCommand.md b/docs/Rules/UseProcessBlockForPipelineCommand.md index 11672389c..7384e7286 100644 --- a/docs/Rules/UseProcessBlockForPipelineCommand.md +++ b/docs/Rules/UseProcessBlockForPipelineCommand.md @@ -63,7 +63,32 @@ this rule: - Create a custom rule configuration file to include only the rules you want or exclude the rules you don't want. - Add the appropriate rule suppression attributes to your code to suppress the rule for specific - code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02]. + code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01]. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', '')] +``` + +To suppress the rule for a single parameter, pass the parameter name without the leading `$` as +the second argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', 'InputObject')] + param( + [Parameter(ValueFromPipeline)] + [String]$InputObject + ) + + $InputObject +} +``` -[02]: ../using-scriptanalyzer.md +[01]: ../using-scriptanalyzer.md#suppressing-rules diff --git a/docs/Rules/UseSingleValueFromPipelineParameter.md b/docs/Rules/UseSingleValueFromPipelineParameter.md index f9321d194..c85d81846 100644 --- a/docs/Rules/UseSingleValueFromPipelineParameter.md +++ b/docs/Rules/UseSingleValueFromPipelineParameter.md @@ -78,30 +78,34 @@ boolean value. To enable this rule, set this parameter to `$true`. The default v ## Suppression -This rule is disabled by default. If you have enabled it in your configuration but want to suppress -it for a specific function, you can use the `SuppressMessage` attribute: +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. ```powershell -function Process-Data { - [Diagnostics.CodeAnalysis.SuppressMessage('PSUseSingleValueFromPipelineParameter', 'MyParameterSet')] - [CmdletBinding()] +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingleValueFromPipelineParameter', '')] +``` + +To suppress the rule for a single parameter set, pass the parameter set name as the second +argument. The name isn't case sensitive. + +```powershell +function Test-Script { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingleValueFromPipelineParameter', 'MyParameterSet')] param( - [Parameter(ValueFromPipeline, ParameterSetName='MyParameterSet')] - [string] $InputData, + [Parameter(ParameterSetName = 'MyParameterSet', ValueFromPipeline)] + [String]$InputObject, - [Parameter(ValueFromPipeline, ParameterSetName='MyParameterSet')] - [string] $ProcessingMode + [Parameter(ParameterSetName = 'MyParameterSet', ValueFromPipeline)] + [String]$ProcessingMode ) - process { - Write-Output "$ProcessingMode`: $InputData" - } } ``` -For the default parameter set, use `'default'` as the suppression target: +For parameters that don't declare a parameter set name, use `default` as the second argument: ```powershell -[Diagnostics.CodeAnalysis.SuppressMessage('PSUseSingleValueFromPipelineParameter', 'default')] +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingleValueFromPipelineParameter', 'default')] ``` ## Notes diff --git a/docs/Rules/UseSingularNouns.md b/docs/Rules/UseSingularNouns.md index 231dc4180..add33cc47 100644 --- a/docs/Rules/UseSingularNouns.md +++ b/docs/Rules/UseSingularNouns.md @@ -16,17 +16,8 @@ This rule detects cmdlet names that use plural nouns instead of singular nouns. PowerShell best practices require that cmdlets use singular nouns, not plurals. You can use the `NounAllowList` parameter to exclude specific nouns from this rule, or suppress the rule for -individual functions using `SuppressMessageAttribute`. If a violation is found, change the plural -noun to its singular form. - -For example: - -``` -function Get-Elements { - [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', 'Get-Elements')] - Param() -} -``` +individual functions as described in the Suppression section. If a violation is found, change +the plural noun to its singular form. ## Example @@ -71,3 +62,24 @@ boolean value. To disable this rule, set this parameter to `$false`. The default This parameter specifies which command nouns to exclude from this rule. It accepts a string array. Both `Data` and `Windows` are common false positives and excluded by default. Default values are `'Data'` and `'Windows'`. + +## Suppression + +As with other rules, you can suppress this rule by adding a suppression attribute to the `param` +block of a function or script. An empty string as the second argument suppresses every violation +of the rule in that scope. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '')] +``` + +To suppress the rule for a single function, pass the function name as the second argument. The +name isn't case sensitive. This is useful when the attribute is applied at script or module scope +and covers more than one function. + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', 'Test-Scripts')] +param() + +function Test-Scripts {} +```