From d7dcb5652867ffa3150e54b2e75207717953ef5c Mon Sep 17 00:00:00 2001 From: Xelu86 Date: Fri, 29 May 2026 18:16:27 -0400 Subject: [PATCH 1/4] Freshness --- .../PSScriptAnalyzer/Rules/AvoidLongLines.md | 37 +++++++--- .../Rules/AvoidMultipleTypeAttributes.md | 15 ++-- .../AvoidNullOrEmptyHelpMessageAttribute.md | 15 ++-- .../Rules/AvoidOverwritingBuiltInCmdlets.md | 72 +++++++++++++------ .../AvoidReservedWordsAsFunctionNames.md | 16 ++--- 5 files changed, 98 insertions(+), 57 deletions(-) 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..db2891e 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,15 @@ 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. Using an empty +string, null value, or omitting the value altogether 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 +55,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..f1d9c86 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. + +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]. + +## 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 +} +``` ## Configuration -To enable the rule to check if your script is compatible on PowerShell Core on Windows, put the -following your settings file. +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,25 @@ following your settings file. } ``` -### Parameters +### PowerShellVersion -#### PowerShellVersion +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. -The parameter `PowerShellVersion` is a list of allowlists that ship with PSScriptAnalyzer. +> [!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. -> [!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. +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. -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. +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 From ad97f1165b3d31d7d1e5e27a6b5242b5b445638b Mon Sep 17 00:00:00 2001 From: Xelu86 Date: Fri, 29 May 2026 18:30:25 -0400 Subject: [PATCH 2/4] Fix validation --- .../PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md index f1d9c86..4e13860 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md @@ -65,8 +65,9 @@ The `PowerShellVersion` parameter accepts one or more command allow list names t 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. +> [!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. 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 From 34c67157b776945af38a4ab711aea2457477dcc7 Mon Sep 17 00:00:00 2001 From: Xelu86 Date: Fri, 29 May 2026 18:35:20 -0400 Subject: [PATCH 3/4] Minor edit --- .../PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md index 4e13860..543645a 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md @@ -44,7 +44,7 @@ function Get-CustomChildItem { } ``` -## Configuration +## 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. From ecab4772d2181bf2ca89105e210fedc79d0cbda4 Mon Sep 17 00:00:00 2001 From: Xelu86 Date: Mon, 1 Jun 2026 10:26:14 -0400 Subject: [PATCH 4/4] Update description --- .../Rules/AvoidNullOrEmptyHelpMessageAttribute.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md index db2891e..88b65e6 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md @@ -10,8 +10,9 @@ title: AvoidNullOrEmptyHelpMessageAttribute ## Description -The `HelpMessage` attribute must contain a meaningful, non-empty string value. Using an empty -string, null value, or omitting the value altogether causes PowerShell to raise an error at runtime. +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. Always provide a descriptive help message that explains the parameter's purpose and expected input to users.