Auto Publish – main to live - 2026-06-15 22:07 UTC

reference/docs-conceptual/PSScriptAnalyzer/Rules/AlignAssignmentStatement.md

@@ -1,6 +1,6 @@
 ---
 description: Align assignment statement
-ms.date: 03/20/2026
+ms.date: 06/12/2026
 ms.topic: reference
 title: AlignAssignmentStatement
 ---
@@ -10,12 +10,20 @@ title: AlignAssignmentStatement
 
 ## Description
 
-Consecutive assignment statements are easier to scan when their `=` signs line up vertically.
+This rule detects misaligned assignment operators in hashtables and enum definitions. Consecutive
+assignment statements are easier to read and maintain when their assignment operators align
+vertically.
 
-This rule looks at the key-value pairs in hashtables. Use this rule to align assignment operators in
-multiline hashtables and enum definitions.
+This rule checks key-value pairs in hashtables and enum member definitions to ensure that the `=`
+signs line up. Use this rule to enforce consistent formatting in multiline hashtables and enum
+definitions.
 
-Consider the following example with a hashtable and enum that isn't aligned.
+The rule ignores assignments within hashtables and enums that appear on the same line as other
+assignments. For example, the rule ignores `$h = @{ a = 1; b = 2 }`.
+
+## Example
+
+### Noncompliant
 
 ```powershell
 $hashtable = @{
@@ -29,7 +37,7 @@ enum Enum {
 }
 ```
 
-Alignment in this case would look like the following.
+### Compliant
 
 ```powershell
 $hashtable = @{
@@ -43,9 +51,6 @@ enum Enum {
 }
 ```
 
-The rule ignores assignments within hashtables and enums that appear on the same line as other
-assignments. For example, the rule ignores `$h = @{ a = 1; b = 2 }`.
-
 ## Configuration
 
 ```powershell
@@ -61,126 +66,39 @@ Rules = @{
 }
 ```
 
-### Parameters
-
-#### Enable: bool (Default value is `$false`)
-
-Enable or disable the rule during ScriptAnalyzer invocation.
-
-#### CheckHashtable: bool (Default value is `$true`)
-
-Enforce alignment of assignment statements in a hashtable and in a DSC Configuration. There's only
-one setting for hashtable and DSC configuration because the property value pairs in a DSC
-configuration are parsed as key-value pairs of a hashtable.
-
-#### AlignHashtableKvpWithInterveningComment: bool (Default value is `$true`)
-
-Include key-value pairs in the alignment that have an intervening comment, such as a comment between
-the key name and the equals (`=`) sign.
-
-Consider this example:
-
-```powershell
-$hashtable = @{
-    property = 'value'
-    anotherProperty <#A Comment#> = 'another value'
-    anotherDifferentProperty = 'yet another value'
-}
-```
+## Parameters
 
-With this setting **disabled**, the line with the comment is ignored, and the block is aligned
-like so:
+### Enable
 
-```powershell
-$hashtable = @{
-    property                 = 'value'
-    anotherProperty <#A Comment#> = 'another value'
-    anotherDifferentProperty = 'yet another value'
-}
-```
+This parameter controls whether ScriptAnalyzer checks the code against this rule. It accepts a
+boolean value. To enable this rule, set this parameter to `$true`. The default value is `$false`.
 
-With it **enabled**, the line with the comment is included, and the block is aligned like so:
+### CheckHashtable
 
-```powershell
-$hashtable = @{
-    property                      = 'value'
-    anotherProperty <#A Comment#> = 'another value'
-    anotherDifferentProperty      = 'yet another value'
-}
-```
+This parameter controls whether ScriptAnalyzer checks assignment alignment in hashtables and Desired
+State Configuration (DSC) configurations. It accepts a boolean value. To disable this check, set
+this parameter to `$false`. The default value is `$true`.
 
-#### CheckEnum: bool (Default value is `$true`)
+### AlignHashtableKvpWithInterveningComment
 
-Enforce alignment of assignment statements of an Enum definition.
+This parameter controls whether ScriptAnalyzer includes hashtable key-value pairs that contain an
+intervening comment when determining alignment. It accepts a boolean value. To exclude these lines,
+set this parameter to `$false`. The default value is `$true`.
 
-#### AlignEnumMemberWithInterveningComment: bool (Default value is `$true`)
+### CheckEnum
 
-Include enum members in the alignment that have an intervening comment, such as a comment between
-the member name and the equals (`=`) sign.
+This parameter controls whether ScriptAnalyzer checks assignment alignment in enum member
+definitions. It accepts a boolean value. To disable this check, set this parameter to `$false`. The
+default value is `$true`.
 
-Consider this example:
+### AlignEnumMemberWithInterveningComment
 
-```powershell
-enum Enum {
-    member = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember = 3
-}
-```
+This parameter controls whether ScriptAnalyzer includes enum members that contain an intervening
+comment when determining alignment. It accepts a boolean value. To exclude these lines, set this
+parameter to `$false`. The default value is `$true`.
 
-With this setting **disabled**, the line with the comment is ignored, and the block is aligned
-like so:
+### IncludeValuelessEnumMembers
 
-```powershell
-enum Enum {
-    member                 = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember = 3
-}
-```
-
-With it **enabled**, the line with the comment is included, and the block is aligned like so:
-
-```powershell
-enum Enum {
-    member                      = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember      = 3
-}
-```
-
-#### IncludeValuelessEnumMembers: bool (Default value is `$true`)
-
-Include enum members in the alignment that don't have an explicitly assigned value. Enums don't need
-to be given a value when they're defined.
-
-Consider this example:
-
-```powershell
-enum Enum {
-    member = 1
-    anotherMember = 2
-    anotherDifferentMember
-}
-```
-
-With this setting **disabled**, the third line that has no value isn't considered when choosing
-where to align assignments. It would be aligned like so:
-
-```powershell
-enum Enum {
-    member        = 1
-    anotherMember = 2
-    anotherDifferentMember
-}
-```
-
-With it **enabled**, the valueless member is included in alignment as if it had a value:
-
-```powershell
-enum Enum {
-    member                 = 1
-    anotherMember          = 2
-    anotherDifferentMember
-}
-```
+This parameter controls whether ScriptAnalyzer includes enum members without explicitly assigned
+values when determining alignment. It accepts a boolean value. To exclude valueless members, set
+this parameter to `$false`. The default value is `$true`.

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidAssignmentToAutomaticVariable.md

@@ -1,6 +1,6 @@
 ---
 description: Changing automatic variables might have undesired side effects
-ms.date: 05/28/2026
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidAssignmentToAutomaticVariable
 ---
@@ -10,16 +10,15 @@ title: AvoidAssignmentToAutomaticVariable
 
 ## Description
 
-PowerShell automatically defines variables that store internal state information and manages them on
-its own. Even though you _can_ override many automatic variables, doing so can have unexpected
-effects for users. Assign automatic variables only in advanced, intentional scenarios.
+This rule detects assignments to automatic variables and parameter names that use automatic variable
+names. PowerShell automatically defines variables that store internal state information and manages
+them on its own. Even though you _can_ override many automatic variables, doing so can have
+unexpected effects for users and make your code harder to maintain and debug.
 
-This rule helps you avoid assignments to automatic variables, which reduces hard-to-diagnose bugs
-and keeps function behavior predictable.
+Avoid using automatic variable names in your functions and parameters. Reserve automatic variables
+for PowerShell's internal use only, and rely on them only to read state information.
 
-Also use variable names in functions or parameters that don't conflict with automatic variables.
-
-To learn more about automatic variables, see [about_Automatic_Variables][01].
+To learn more, see [about_Automatic_Variables][01].
 
 ## Example
 
@@ -36,7 +35,7 @@ function foo($Error){ }
 function Get-CustomErrorMessage($ErrorMessage){ $Error = "Error occurred: $ErrorMessage" }
 ```
 
-### Preferred
+### Compliant
 
 ```powershell
 function Get-CustomErrorMessage($ErrorMessage){ $FinalErrorMessage = "Error occurred: $ErrorMessage" }

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidDefaultValueForMandatoryParameter.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid Default Value For Mandatory Parameter
-ms.date: 05/28/2026
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidDefaultValueForMandatoryParameter
 ---
@@ -10,9 +10,10 @@ title: AvoidDefaultValueForMandatoryParameter
 
 ## Description
 
-Mandatory parameters shouldn't have default values because there isn't a scenario where the default
-can be used. PowerShell prompts for a value if the parameter value isn't specified when calling the
-function.
+This rule detects when mandatory parameters have default values assigned. Mandatory parameters
+shouldn't have default values because they can't be used. When a parameter is marked as mandatory,
+PowerShell always prompts the user for a value if one isn't supplied when calling the function. Any
+default value assigned to a mandatory parameter is unreachable and serves no purpose.
 
 ## Example
 
@@ -31,7 +32,7 @@ function Test
 }
 ```
 
-### Preferred
+### Compliant
 
 ```powershell
 function Test

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidDefaultValueSwitchParameter.md

@@ -1,6 +1,6 @@
 ---
-description: Switch Parameters Should Not Default To True
-ms.date: 05/28/2026
+description: Switch parameters should not default to $true
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidDefaultValueSwitchParameter
 ---
@@ -10,24 +10,20 @@ title: AvoidDefaultValueSwitchParameter
 
 ## Description
 
-If your parameter takes only `true` and `false`, define the parameter as type `[Switch]`. PowerShell
-treats a switch parameter as `true` when it's used with a command. If the parameter isn't included
-with the command, PowerShell considers the parameter to be false. Don't define `[Boolean]`
-parameters.
+This rule detects switch parameters that are assigned a default value of `$true`. Switch parameters
+shouldn't have default values. By design, a switch parameter is `$false` when not specified and
+`$true` when included in the command. Assigning a default value of `$true` to a switch parameter
+violates this design principle and can cause unexpected behavior.
 
-Don't define a switch parameter with a default value of `$true` because a switch parameter is
-already `$false` when it isn't specified. Leave the switch parameter without a default value so it
-behaves as designed.
+If your parameter needs to accept only `true` and `false` values, use the `[Switch]` type instead of
+`[Boolean]`. PowerShell automatically handles switch parameters correctly without requiring a
+default value.
 
-## How
+To fix this issue, remove the default value from the switch parameter declaration. The switch
+naturally defaults to `$false` when not specified, allowing your logic to respond appropriately to
+the caller's input.
 
-To fix this issue, don't assign a default value of `$true` to a `[switch]` parameter. Declare the
-switch without a default value and write your logic so the parameter is treated as `$false` when
-the caller doesn't supply it.
-
-## More information
-
-See [Strongly Encouraged Development Guidelines][01].
+To learn more, see [Strongly Encouraged Development Guidelines][01].
 
 ## Example
 
@@ -49,7 +45,7 @@ function Test-Script
 }
 ```
 
-### Preferred
+### Compliant
 
 ```powershell
 function Test-Script

reference/docs-conceptual/PSScriptAnalyzer/Rules/UseLiteralInitializerForHashtable.md

@@ -1,6 +1,6 @@
 ---
 description: Create hashtables with literal initializers
-ms.date: 06/28/2023
+ms.date: 06/11/2026
 ms.topic: reference
 title: UseLiteralInitializerForHashtable
 ---
@@ -10,33 +10,23 @@ title: UseLiteralInitializerForHashtable
 
 ## Description
 
-Creating a hashtable using `[hashtable]::new()` or `New-Object -TypeName hashtable` without passing
-a `IEqualityComparer` object to the constructor creates a hashtable where the keys are looked-up in
-a case-sensitive manner. However, PowerShell is case-insensitive in nature and it is best to create
-hashtables with case-insensitive key look-up.
+This rule detects hashtables created using the `[hashtable]::new()` method or the `New-Object
+-TypeName hashtable` cmdlet without passing an `IEqualityComparer` object. When you create a
+hashtable using `[hashtable]::new()` or `New-Object -TypeName hashtable`, the keys are looked up in
+a case-sensitive manner by default.
 
-This rule is intended to warn the author of the case-sensitive nature of the hashtable when created
-using the `new` method or the `New-Object` cmdlet.
-
-## How to Fix
-
-Create the hashtable using a literal hashtable expression.
+However, PowerShell is case-insensitive in nature, and hashtables should maintain this behavior. To
+ensure consistent case-insensitive key lookup, use literal hashtable expressions instead.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 $hashtable = [hashtable]::new()
 ```
 
-### Wrong
-
-```powershell
-$hashtable = New-Object -TypeName hashtable
-```
-
-### Correct
+### Compliant
 
 ```powershell
 $hashtable = @{}