Skip to content

Commit e857fc3

Browse files
sdwheelersdwheeler
committed
Restore files for new rules
1 parent 09a0a68 commit e857fc3

5 files changed

Lines changed: 277 additions & 0 deletions

File tree

‎docs/Rules/AvoidDynamicallyCreatingVariableNames.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
description: Avoid dynamic variable names, instead use a hash table or similar dictionary type.
3+
ms.date: 07/21/2026
4+
ms.topic: reference
5+
title: AvoidDynamicallyCreatingVariableNames
6+
---
7+
# AvoidDynamicallyCreatingVariableNames
8+
9+
**Severity Level: Information**
10+
11+
**Default state: Disabled**
12+
13+
## Description
14+
15+
This rule checks for the use of `New-Variable` with a dynamic name. Don't create variables with
16+
dynamic names. A dynamic name is a name constructed using string concatenation or interpolation.
17+
Dynamic names make the code difficult to understand and can lead to unexpected behavior if the
18+
variable names aren't unique.
19+
20+
Use a hash table or similar dictionary type to store values with dynamic keys. If you require a
21+
specific scope, option, or visibility, put the dictionary (hashtable) in that scope and apply the
22+
appropriate option or visibility.
23+
24+
## Example
25+
26+
### Noncompliant
27+
28+
```powershell
29+
'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process {
30+
New-Variable -Name "My$_" -Value ($i++)
31+
}
32+
$MyTwo # returns 2
33+
```
34+
35+
### Compliant
36+
37+
```powershell
38+
$My = @{}
39+
'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process {
40+
$My[$_] = $i++
41+
}
42+
$My.Two # returns 2
43+
```
44+
45+
In this example, you want the values to be read-only and available in the script scope.
46+
Put the hashtable in the script scope and make it read-only.
47+
48+
```powershell
49+
New-Variable -Name My -Value @{} -Option ReadOnly -Scope Script
50+
'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process {
51+
$Script:My[$_] = $i++
52+
}
53+
$Script:My.Two # returns 2
54+
```
55+
56+
## Configure rule
57+
58+
```powershell
59+
Rules = @{
60+
PSAvoidDynamicallyCreatingVariableNames = @{
61+
Enable = $true
62+
}
63+
}
64+
```
65+
66+
### Parameters
67+
68+
- `Enable`: **bool** (Default value is `$false`)
69+
70+
Enable or disable the rule during ScriptAnalyzer invocation.
71+
72+
## References
73+
74+
- [New-Variable][02]
75+
- [about_Scopes][01]
76+
77+
<!-- link references -->
78+
[01]: /powershell/module/microsoft.powershell.core/about/about_scopes
79+
[02]: xref:Microsoft.PowerShell.Utility.New-Variable

‎docs/Rules/AvoidUsingArrayList.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
description: Avoid using ArrayList
3+
ms.date: 07/21/2026
4+
ms.topic: reference
5+
title: AvoidUsingArrayList
6+
---
7+
# AvoidUsingArrayList
8+
9+
**Severity Level: Warning**
10+
11+
**Default state: Disabled**
12+
13+
## Description
14+
15+
Avoid the **ArrayList** class for new development. The documentation for the [ArrayList class][01]
16+
recommends using the [System.Collections.Generic.List\<T\>][02] class instead.
17+
18+
The **ArrayList** class is a non-generic collection that can hold objects of any type. The generic
19+
**List\<T\>** class provides better performance, type safety, and the `List<T>.Add()` method doesn't
20+
have the output side-effects that `ArrayList.Add()` has.
21+
22+
In cases where only the `ArrayList.Add()` method is used, you could replace the **ArrayList** class
23+
with a generic `List[Object]` class or consider using the more idiomatic PowerShell pipeline syntax
24+
instead.
25+
26+
## Example
27+
28+
### Noncompliant
29+
30+
```powershell
31+
# Using an ArrayList
32+
$List = [System.Collections.ArrayList]::new()
33+
1..3 | ForEach-Object { $List.Add($_) } # Note that this will return the index of the added element
34+
```
35+
36+
### Compliant
37+
38+
```powershell
39+
# Using a generic List
40+
$List = [System.Collections.Generic.List[Object]]::new()
41+
1..3 | ForEach-Object { $List.Add($_) } # This will not return anything
42+
```
43+
44+
```powershell
45+
# Creating a fixed array by using the PowerShell pipeline
46+
$List = 1..3 | ForEach-Object { $_ }
47+
```
48+
49+
## Configure rule
50+
51+
```powershell
52+
Rules = @{
53+
PSAvoidUsingArrayList = @{
54+
Enable = $true
55+
}
56+
}
57+
```
58+
59+
### Parameters
60+
61+
- `Enable`: **bool** (Default value is `$false`)
62+
63+
Enable or disable the rule during ScriptAnalyzer invocation.
64+
65+
<!-- link references -->
66+
[01]: xref:System.Collections.ArrayList#remarks
67+
[02]: xref:System.Collections.Generic.List%601

‎docs/Rules/InvalidMultiDotValue.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
description: Invalid unquoted multi-dot value construction
3+
ms.date: 07/24/2026
4+
ms.topic: reference
5+
title: InvalidMultiDotValue
6+
---
7+
# InvalidMultiDotValue
8+
9+
**Severity Level: Warning**
10+
11+
**Default state: Disabled**
12+
13+
## Description
14+
15+
PowerShell doesn't support unquoted literal values with multiple dots (`.`). Any value with two or
16+
more dots results in `$null`, which can lead to unexpected behavior or errors in the code. This rule
17+
identifies instances where such values are used.
18+
19+
To create values with multiple dots you must enclose the value in quotes and use type-casting or use
20+
type constructor methods to create the appropriate object.
21+
22+
## Example
23+
24+
### Noncompliant
25+
26+
```powershell
27+
$version = 1.2.3
28+
```
29+
30+
or even:
31+
32+
```powershell
33+
$IP = [System.Net.IPAddress]127.0.0.1
34+
```
35+
36+
Where both examples result in `$null` instead of the expected value.
37+
38+
### Compliant
39+
40+
```powershell
41+
# Use type-casting with quoted value
42+
$IP = [System.Net.IPAddress]'127.0.0.1'
43+
$version = [Version]'1.2.3'
44+
45+
# Use type constructor method
46+
$version = [Version]::new(1, 2, 3)
47+
```
48+
49+
## Configure rule
50+
51+
```powershell
52+
Rules = @{
53+
PSInvalidMultiDotValue = @{
54+
Enable = $true
55+
}
56+
}
57+
```
58+
59+
### Parameters
60+
61+
- `Enable`: **bool** (Default value is `$false`)
62+
63+
Enable or disable the rule during ScriptAnalyzer invocation.

‎docs/Rules/MissingTryBlock.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
description: Missing Try Block
3+
ms.date: 07/21/2026
4+
ms.topic: reference
5+
title: MissingTryBlock
6+
---
7+
# MissingTryBlock
8+
9+
**Severity Level: Warning**
10+
11+
**Default state: Disabled**
12+
13+
## Description
14+
15+
This rule identifies instances where `catch` or `finally` blocks are present without an associated
16+
`try` block. Without a `try` block, the `catch` and `finally` are interpreted as commands and result
17+
in a runtime error, such as:
18+
19+
> "The term 'catch' is not recognized as a name of a cmdlet"
20+
21+
To prevent this error, add a `try` block before the `catch` and `finally` blocks.
22+
23+
> [!NOTE]
24+
> This rule is triggered by functions named `catch` or `finally`. However, creating functions with
25+
> those names violates the [AvoidReservedWordsAsFunctionNames][01] rule. If you have functions named
26+
> `catch` or `finally`, you can either rename the function or disable this rule.
27+
28+
## Example
29+
30+
### Noncompliant
31+
32+
```powershell
33+
catch { "An error occurred." }
34+
```
35+
36+
### Compliant
37+
38+
```powershell
39+
try { $a = 1 / $b }
40+
catch { "Attempted to divide by zero." }
41+
```
42+
43+
## Configuration
44+
45+
```powershell
46+
Rules = @{
47+
PSMissingTryBlock = @{
48+
Enable = $true
49+
}
50+
}
51+
```
52+
53+
### Parameters
54+
55+
- `Enable`: **bool** (Default value is `$false`)
56+
57+
Enable or disable the rule during ScriptAnalyzer invocation.
58+
59+
<!-- link references -->
60+
[01]: AvoidReservedWordsAsFunctionNames.md

‎docs/Rules/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ title: List of PSScriptAnalyzer rules
2323
| [AvoidAssignmentToAutomaticVariable][03] | Warning | Always enabled | |
2424
| [AvoidDefaultValueForMandatoryParameter][04] | Warning | Always enabled | |
2525
| [AvoidDefaultValueSwitchParameter][05] | Warning | Always enabled | |
26+
| [AvoidDynamicallyCreatingVariableNames][06] | Information | Disabled | Yes |
2627
| [AvoidExclaimOperator][07] | Warning | Disabled | Yes |
2728
| [AvoidGlobalAliases][08] | Warning | Always enabled | |
2829
| [AvoidGlobalFunctions][09] | Warning | Always enabled | |
@@ -37,6 +38,7 @@ title: List of PSScriptAnalyzer rules
3738
| [AvoidShouldContinueWithoutForce][18] | Warning | Always enabled | |
3839
| [AvoidTrailingWhitespace][19] | Information | Always enabled | |
3940
| [AvoidUsingAllowUnencryptedAuthentication][20] | Warning | Always enabled | |
41+
| [AvoidUsingArrayList][21] | Warning | Disabled | Yes |
4042
| [AvoidUsingBrokenHashAlgorithms][22] | Warning | Always enabled | |
4143
| [AvoidUsingCmdletAliases][23] | Warning | Always enabled | Yes |
4244
| [AvoidUsingComputerNameHardcoded][24] | Error | Always enabled | |
@@ -57,8 +59,10 @@ title: List of PSScriptAnalyzer rules
5759
| [DSCUseIdenticalMandatoryParametersForDSC][39] | Error | Always enabled | |
5860
| [DSCUseIdenticalParametersForDSC][40] | Error | Always enabled | |
5961
| [DSCUseVerboseMessageInDSCResource][41] | Information | Always enabled | |
62+
| [InvalidMultiDotValue][42] | Warning | Disabled | Yes |
6063
| [MisleadingBacktick][43] | Warning | Always enabled | |
6164
| [MissingModuleManifestField][44] | Warning | Always enabled | |
65+
| [MissingTryBlock][45] | Warning | Disabled | Yes |
6266
| [PlaceCloseBrace][46] | Warning | Disabled | Yes |
6367
| [PlaceOpenBrace][47] | Warning | Disabled | Yes |
6468
| [PossibleIncorrectComparisonWithNull][48] | Warning | Always enabled | |
@@ -101,6 +105,7 @@ title: List of PSScriptAnalyzer rules
101105
[03]: AvoidAssignmentToAutomaticVariable.md
102106
[04]: AvoidDefaultValueForMandatoryParameter.md
103107
[05]: AvoidDefaultValueSwitchParameter.md
108+
[06]: AvoidDynamicallyCreatingVariableNames.md
104109
[07]: AvoidExclaimOperator.md
105110
[08]: AvoidGlobalAliases.md
106111
[09]: AvoidGlobalFunctions.md
@@ -115,6 +120,7 @@ title: List of PSScriptAnalyzer rules
115120
[18]: AvoidShouldContinueWithoutForce.md
116121
[19]: AvoidTrailingWhitespace.md
117122
[20]: AvoidUsingAllowUnencryptedAuthentication.md
123+
[21]: AvoidUsingArrayList.md
118124
[22]: AvoidUsingBrokenHashAlgorithms.md
119125
[23]: AvoidUsingCmdletAliases.md
120126
[24]: AvoidUsingComputerNameHardcoded.md
@@ -135,8 +141,10 @@ title: List of PSScriptAnalyzer rules
135141
[39]: DSCUseIdenticalMandatoryParametersForDSC.md
136142
[40]: DSCUseIdenticalParametersForDSC.md
137143
[41]: DSCUseVerboseMessageInDSCResource.md
144+
[42]: InvalidMultiDotValue.md
138145
[43]: MisleadingBacktick.md
139146
[44]: MissingModuleManifestField.md
147+
[45]: MissingTryBlock.md
140148
[46]: PlaceCloseBrace.md
141149
[47]: PlaceOpenBrace.md
142150
[48]: PossibleIncorrectComparisonWithNull.md

0 commit comments

Comments
 (0)