Made rule configurable (disabled) and updated documentation and tests accordingly. Increased number of information tests to 20 in Get-ScriptAnalyzerRule tests.

iRon7 · iRon7 · commit 3e546a4844b2 · 2026-05-13T14:42:40.000+02:00
diff --git a/Rules/AvoidDynamicallyCreatingVariableNames.cs b/Rules/AvoidDynamicallyCreatingVariableNames.cs
@@ -14,25 +14,32 @@
 
 namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
 {
-#if !CORECLR
-    [Export(typeof(IScriptRule))]
-#endif
-
     /// <summary>
     /// Rule that informs the user when they create variables with dynamic names in the general variable scope.
     /// This might lead to conflicts with other variables.
     /// </summary>
-    public class AvoidDynamicallyCreatingVariableNames : IScriptRule
+#if !CORECLR
+    [Export(typeof(IScriptRule))]
+#endif
+    public class AvoidDynamicallyCreatingVariableNames : ConfigurableRule
     {
+
         /// <summary>
-        /// Analyzes the PowerShell AST for uses of "New-Variable" command with a dynamic name argument.
+        /// Construct an object of AvoidDynamicallyCreatingVariableNames type.
         /// </summary>
-        /// <param name="ast">The PowerShell Abstract Syntax Tree to analyze.</param>
-        /// <param name="fileName">The name of the file being analyzed (for diagnostic reporting).</param>
-        /// <returns>A collection of diagnostic records for each violation.</returns>
+        public AvoidDynamicallyCreatingVariableNames() {
+            Enable = false;
+        }
 
         readonly HashSet<string> cmdList = new HashSet<string>(Helper.Instance.CmdletNameAndAliases("New-Variable"), StringComparer.OrdinalIgnoreCase);
-        public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
+
+        /// <summary>
+        /// Analyzes the given ast to find the [violation]
+        /// </summary>
+        /// <param name="ast">AST to be analyzed. This should be non-null</param>
+        /// <param name="fileName">Name of file that corresponds to the input AST.</param>
+        /// <returns>A an enumerable type containing the violations</returns>
+        public override IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
         {
             if (ast == null) throw new ArgumentNullException(Strings.NullAstErrorMessage);
 
@@ -70,20 +77,65 @@ testAst is CommandAst cmdAst &&
             }
         }
 
-        public string GetCommonName() => Strings.AvoidDynamicallyCreatingVariableNamesCommonName;
+        /// <summary>
+        /// Retrieves the common name of this rule.
+        /// </summary>
+        public override string GetCommonName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.AvoidDynamicallyCreatingVariableNamesCommonName);
+        }
 
-        public string GetDescription() => Strings.AvoidDynamicallyCreatingVariableNamesDescription;
+        /// <summary>
+        /// Retrieves the description of this rule.
+        /// </summary>
+        public override string GetDescription()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.AvoidDynamicallyCreatingVariableNamesDescription);
+        }
 
-        public string GetName() => string.Format(
+        /// <summary>
+        /// Retrieves the name of this rule.
+        /// </summary>
+        public override string GetName()
+        {
+            return string.Format(
                 CultureInfo.CurrentCulture,
                 Strings.NameSpaceFormat,
                 GetSourceName(),
                 Strings.AvoidDynamicallyCreatingVariableNamesName);
+        }
+
+        /// <summary>
+        /// Retrieves the severity of the rule: error, warning or information.
+        /// </summary>
+        public override RuleSeverity GetSeverity()
+        {
+            return RuleSeverity.Information;
+        }
 
-        public RuleSeverity GetSeverity() => RuleSeverity.Information;
+        /// <summary>
+        /// Gets the severity of the returned diagnostic record: error, warning, or information.
+        /// </summary>
+        /// <returns></returns>
+        public DiagnosticSeverity GetDiagnosticSeverity()
+        {
+            return DiagnosticSeverity.Information;
+        }
 
-        public string GetSourceName() => Strings.SourceName;
+        /// <summary>
+        /// Retrieves the name of the module/assembly the rule is from.
+        /// </summary>
+        public override string GetSourceName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.SourceName);
+        }
 
-        public SourceType GetSourceType() => SourceType.Builtin;
+        /// <summary>
+        /// Retrieves the type of the rule, Builtin, Managed or Module.
+        /// </summary>
+        public override SourceType GetSourceType()
+        {
+            return SourceType.Builtin;
+        }
     }
-}
+}
diff --git a/Tests/Engine/GetScriptAnalyzerRule.tests.ps1 b/Tests/Engine/GetScriptAnalyzerRule.tests.ps1
@@ -152,7 +152,7 @@ Describe "TestSeverity" {
 
     It "filters rules based on multiple severity inputs"{
         $rules = Get-ScriptAnalyzerRule -Severity Error,Information
-        $rules.Count | Should -Be 19
+        $rules.Count | Should -Be 20
     }
 
         It "takes lower case inputs" {
diff --git a/Tests/Rules/AvoidDynamicallyCreatingVariableNames.tests.ps1 b/Tests/Rules/AvoidDynamicallyCreatingVariableNames.tests.ps1
@@ -11,10 +11,18 @@ BeforeAll {
 }
 
 Describe "AvoidDynamicallyCreatingVariableNames" {
+
+    BeforeAll {
+        $Settings = @{
+            IncludeRules = @($ruleName)
+            Rules        = @{ $ruleName = @{ Enable = $true } }
+        }
+    }
+
     Context "Violates" {
         It "Basic dynamic variable name" {
             $scriptDefinition = { New-Variable -Name $Test }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {New-Variable -Name $Test}.ToString()
@@ -23,7 +31,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
 
         It "Using alias" {
             $scriptDefinition = { nv -Name $Test }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {nv -Name $Test}.ToString()
@@ -32,7 +40,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
 
         It "Using uppercase" {
             $scriptDefinition = { NEW-VARIABLE -Name $Test }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {NEW-VARIABLE -Name $Test}.ToString()
@@ -46,7 +54,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 }
                 $MyTwo # returns 2
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {New-Variable -Name "My$_" -Value ($i++)}.ToString()
@@ -58,7 +66,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 $myVarName = 'foo'
                 New-Variable $myVarName
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {New-Variable $myVarName}.ToString()
@@ -72,7 +80,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 }
                 $MyTwo # returns 2
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations.Count       | Should -Be 1
             $violations.Severity    | Should -Be Information
             $violations.Extent.Text | Should -Be {New-Variable "My$_" ($i++)}.ToString()
@@ -89,7 +97,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 }
                 $My.Two # returns 2
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations | Should -BeNullOrEmpty
         }
 
@@ -101,7 +109,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 }
                 $Script:My.Two # returns 2
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations | Should -BeNullOrEmpty
         }
 
@@ -110,7 +118,22 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 New-Variable -Name '$Sign1'
                 New-Variable -Name '$Sign2' -Value 'Dollar'
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
+            $violations | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Disabled" {
+        BeforeAll {
+            $Settings = @{
+                IncludeRules = @($ruleName)
+                Rules        = @{ $ruleName = @{ Enable = $false } }
+            }
+        }
+
+        It "ConvertFrom-SecureString -AsPlainText" {
+            $scriptDefinition = { New-Variable -Name $Test }.ToString()
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations | Should -BeNullOrEmpty
         }
     }
@@ -122,7 +145,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 Param()
                 New-Variable -Name $Test
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations | Should -BeNullOrEmpty
         }
         It "Common dynamic variable iteration" {
@@ -134,7 +157,7 @@ Describe "AvoidDynamicallyCreatingVariableNames" {
                 }
                 $MyTwo # returns 2
             }.ToString()
-            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule @($ruleName)
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $Settings
             $violations | Should -BeNullOrEmpty
         }
     }
diff --git a/docs/Rules/AvoidDynamicallyCreatingVariableNames.md b/docs/Rules/AvoidDynamicallyCreatingVariableNames.md
@@ -10,12 +10,19 @@ title: AvoidDynamicallyCreatingVariableNames
 
 ## Description
 
-Do not create variables with a dynamic name, this might introduce conflicts with
-other variables and is difficult to maintain.
+Don't create variables with dynamic names. It also makes the code difficult to understand and can
+lead to unexpected behavior if the variable names are not unique or if they collide with existing
+variables. A dynamic name is a name constructed using string concatenation or interpolation.
+This rule checks for the use of `New-Variable` with a dynamic name.
 
-## How
+> [!NOTE]
+> This rule is not enabled by default. The user needs to enable it through settings.
 
-Use a hash table or similar dictionary type to store values with dynamic keys.
+## How to Fix
+
+Use a hash table or similar dictionary type to store values with dynamic keys. When you require a
+specific scope, option, or visibility, put the dictionary (hashtable) in that scope and apply the
+appropriate option or visibility.
 
 ## Example
 
@@ -38,14 +45,33 @@ $My = @{}
 $My.Two # returns 2
 ```
 
-When a specific scope, option, or visibility is required, put the dictionary (hash table) in that
-scope and apply the appropriate option or visibility. For example, if the values should be read-only and
-available in the script scope, put the _hash table_ in the script scope and make it read-only.
+In this example, you want the values to be read-only and available in the script scope.
+Put the hashtable in the script scope and make it read-only.
 
 ```powershell
 New-Variable -Name My -Value @{} -Option ReadOnly -Scope Script
 'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process {
     $Script:My[$_] = $i++
 }
 $Script:My.Two # returns 2
-```
+```
+
+## Configuration
+
+```powershell
+Rules = @{
+    PSAvoidExclaimOperator  = @{
+        Enable = $true
+    }
+}
+```
+
+### Parameters
+
+- `Enable`: **bool** (Default value is `$false`)
+
+  Enable or disable the rule during ScriptAnalyzer invocation.
+
+## References
+- [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable)
+
diff --git a/docs/Rules/README.md b/docs/Rules/README.md
@@ -14,7 +14,7 @@ The PSScriptAnalyzer contains the following rule definitions.
 | [AvoidAssignmentToAutomaticVariable](./AvoidAssignmentToAutomaticVariable.md)                     | Warning     |        Yes         |                 |
 | [AvoidDefaultValueForMandatoryParameter](./AvoidDefaultValueForMandatoryParameter.md)             | Warning     |        Yes         |                 |
 | [AvoidDefaultValueSwitchParameter](./AvoidDefaultValueSwitchParameter.md)                         | Warning     |        Yes         |                 |
-| [AvoidDynamicallyCreatingVariableNames](./AvoidDynamicallyCreatingVariableNames.md)               | Information |        Yes         |                 |
+| [AvoidDynamicallyCreatingVariableNames](./AvoidDynamicallyCreatingVariableNames.md)               | Information |         No         |       Yes       |
 | [AvoidExclaimOperator](./AvoidExclaimOperator.md)                                                 | Warning     |         No         |                 |
 | [AvoidGlobalAliases<sup>1</sup>](./AvoidGlobalAliases.md)                                         | Warning     |        Yes         |                 |
 | [AvoidGlobalFunctions](./AvoidGlobalFunctions.md)                                                 | Warning     |        Yes         |                 |

Original file line number	Diff line number	Diff line change
`@@ -152,7 +152,7 @@ Describe "TestSeverity" {`
`152`	`152`
`153`	`153`	`It "filters rules based on multiple severity inputs"{`
`154`	`154`	`$rules = Get-ScriptAnalyzerRule -Severity Error,Information`
`155`		`- $rules.Count \| Should -Be 19`
	`155`	`+ $rules.Count \| Should -Be 20`
`156`	`156`	`}`
`157`	`157`
`158`	`158`	`It "takes lower case inputs" {`