diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidLongLines.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidLongLines.md index 89474c8..74cb602 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidLongLines.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidLongLines.md @@ -1,6 +1,6 @@ --- description: Avoid long lines -ms.date: 03/20/2026 +ms.date: 06/01/2026 ms.topic: reference title: AvoidLongLines --- @@ -10,13 +10,25 @@ title: AvoidLongLines ## Description -The length of lines, including leading spaces (indentation), should be less than the configured -number of characters. The default length is 120 characters. +This rule flags lines that exceed the configured maximum length, including leading spaces +(indentation). The default maximum line length is 120 characters. This rule is **disabled** by +default and must be explicitly enabled through rule configuration settings. -> [!NOTE] -> This rule isn't enabled by default. The user needs to enable it through settings. +## Example 1 -## Configuration +``` +In this example of sample text, the maximum line length is using the default setting of not exceeding more than 120 +characters. +``` + +## Example 2 + +``` +In this example of sample text, the maximum line length is set to not exceed +more than 80 characters. +``` + +## Configure rule ```powershell Rules = @{ @@ -29,10 +41,15 @@ Rules = @{ ## Parameters -### `Enable`: bool (Default value is `$false`) +### Enable + +Enables (`$true`) the rule during ScriptAnalyzer invocation. + +### Disable -Enable or disable the rule during ScriptAnalyzer invocation. +Disables (`$false`) the rule during ScriptAnalyzer invocation. Default value is `$false`. -### `MaximumLineLength`: int (Default value is 120) +### MaximumLineLength -Optional parameter to override the default maximum line length. +This parameter is optional and is used to override the default maximum line length. This parameter +accepts an integer value. Default value is `120`. diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidMultipleTypeAttributes.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidMultipleTypeAttributes.md index 9ccd478..dc25ba7 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidMultipleTypeAttributes.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidMultipleTypeAttributes.md @@ -1,6 +1,6 @@ --- description: Avoid multiple type specifiers on parameters. -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidMultipleTypeAttributes --- @@ -10,16 +10,15 @@ title: AvoidMultipleTypeAttributes ## Description -Parameters should not have more than one type specifier. Multiple type specifiers on parameters -can cause runtime errors. +Parameters shouldn't have multiple type specifiers. When you apply more than one type attribute to a +parameter, it can lead to unexpected type coercion or runtime errors. -## How - -Ensure each parameter has only 1 type specifier. +Each parameter should have exactly one type specifier to ensure predictable behavior and type +safety. ## Example -### Wrong +### Noncompliant ```powershell function Test-Script @@ -34,7 +33,7 @@ function Test-Script } ``` -### Correct +### Compliant ```powershell function Test-Script diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md index 386c960..88b65e6 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md @@ -1,6 +1,6 @@ --- description: Avoid using null or empty HelpMessage parameter attribute. -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidNullOrEmptyHelpMessageAttribute --- @@ -10,16 +10,16 @@ title: AvoidNullOrEmptyHelpMessageAttribute ## Description -The value of the `HelpMessage` attribute should not be an empty string or a null value as this -causes PowerShell's interpreter to throw an error when executing the function or cmdlet. +The `HelpMessage` attribute must contain a meaningful, non-empty string value. Omitting the value +altogether causes a parse-time syntax error. Using an empty string or null value causes PowerShell +to raise an error at runtime. -## How - -Specify a value for the `HelpMessage` attribute. +Always provide a descriptive help message that explains the parameter's purpose and expected input +to users. ## Example -### Wrong +### Noncompliant ```powershell Function BadFuncEmptyHelpMessageEmpty @@ -56,7 +56,7 @@ Function BadFuncEmptyHelpMessageNoAssignment } ``` -### Correct +### Compliant ```powershell Function GoodFuncHelpMessage diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md index 10e1ad3..543645a 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md @@ -1,6 +1,6 @@ --- description: Avoid overwriting built in cmdlets -ms.date: 12/12/2024 +ms.date: 06/01/2026 ms.topic: reference title: AvoidOverwritingBuiltInCmdlets --- @@ -10,16 +10,44 @@ title: AvoidOverwritingBuiltInCmdlets ## Description -This rule flags cmdlets that are available in a given edition/version of PowerShell on a given -operating system which are overwritten by a function declaration. It works by comparing function -declarations against a set of allowlists that ship with PSScriptAnalyzer. These allowlist files are -used by other PSScriptAnalyzer rules. More information can be found in the documentation for the -[UseCompatibleCmdlets][01] rule. +This rule warns when a script defines a function that uses the name of a built-in cmdlet available +for a target PowerShell version and operating system. Overwriting built-in cmdlet names can cause +confusing behavior because callers might run your function when they expected the platform cmdlet. -## Configuration +The rule compares function declarations in your script against command allow lists that ship with +PSScriptAnalyzer. The allow lists are also used by other compatibility rules. To learn more, see +[UseCompatibleCmdlets][01]. -To enable the rule to check if your script is compatible on PowerShell Core on Windows, put the -following your settings file. +## Example + +### Noncompliant + +```powershell +function Get-ChildItem { + param( + [string]$Path = '.' + ) + + "Custom listing for: $Path" +} +``` + +### Compliant + +```powershell +function Get-CustomChildItem { + param( + [string]$Path = '.' + ) + + Get-ChildItem -Path $Path +} +``` + +## Configure rule + +To enable the rule to check if your script is compatible on PowerShell Core on Windows, add the +following lines in your settings file. ```powershell @{ @@ -31,23 +59,26 @@ following your settings file. } ``` -### Parameters - -#### PowerShellVersion +### PowerShellVersion -The parameter `PowerShellVersion` is a list of allowlists that ship with PSScriptAnalyzer. +The `PowerShellVersion` parameter accepts one or more command allow list names that ship with +PSScriptAnalyzer. Set this value to the PowerShell version and platform you want to validate +against. > [!NOTE] -> The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or -> later is installed, and `desktop-5.1.14393.206-windows` if it's not. +> The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or later is +installed, and `desktop-5.1.14393.206-windows` if it's not. -Usually, patched versions of PowerShell have the same cmdlet data, therefore only settings of major -and minor versions of PowerShell are supplied. One can also create a custom settings file as well -with the [New-CommandDataFile.ps1][02] script and use it by placing the created `JSON` into the -`Settings` folder of the `PSScriptAnalyzer` module installation folder, then the `PowerShellVersion` -parameter is just its filename (that can also be changed if desired). Note that the `core-6.0.2-*` -files were removed in PSScriptAnalyzer 1.18 since PowerShell 6.0 reached end of life. +Patched PowerShell releases usually share the same cmdlet metadata, so the built-in allow lists are +provided by major and minor version. You can also generate a custom allow list with +[New-CommandDataFile.ps1][02]. To use a custom allow list, place the generated JSON file in the +`Settings` folder of the PSScriptAnalyzer module installation path, then set `PowerShellVersion` to +that filename. + +The `core-6.0.2-*` files were removed in PSScriptAnalyzer 1.18 because PowerShell 6.0 reached end of +life. -[01]: ./UseCompatibleCmdlets.md + +[01]: UseCompatibleCmdlets.md [02]: https://github.com/PowerShell/PSScriptAnalyzer/blob/main/Utils/New-CommandDataFile.ps1 diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidReservedWordsAsFunctionNames.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidReservedWordsAsFunctionNames.md index 046a93b..b7a9d1f 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidReservedWordsAsFunctionNames.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidReservedWordsAsFunctionNames.md @@ -1,6 +1,6 @@ --- description: Avoid reserved words as function names -ms.date: 08/31/2025 +ms.date: 06/01/2026 ms.topic: reference title: AvoidReservedWordsAsFunctionNames --- @@ -10,19 +10,14 @@ title: AvoidReservedWordsAsFunctionNames ## Description -Avoid using reserved words as function names. Using reserved words as function names can cause -errors or unexpected behavior in scripts. - -## How to Fix - -Avoid using any of the reserved words as function names. Choose a different name that's not a -reserved word. +Using reserved words as function names causes errors or unexpected behavior in PowerShell scripts. +Choose function names that don't conflict with any PowerShell reserved words. See [about_Reserved_Words][01] for a list of reserved words in PowerShell. ## Example -### Wrong +### Noncompliant ```powershell # Function is a reserved word @@ -31,7 +26,7 @@ function function { } ``` -### Correct +### Compliant ```powershell # myFunction is not a reserved word @@ -41,4 +36,5 @@ function myFunction { ``` + [01]: /powershell/module/microsoft.powershell.core/about/about_reserved_words