diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingEmptyCatchBlock.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingEmptyCatchBlock.md index 1983417..faaa1a0 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingEmptyCatchBlock.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingEmptyCatchBlock.md @@ -1,6 +1,6 @@ --- description: Avoid Using Empty Catch Block -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingEmptyCatchBlock --- @@ -10,16 +10,13 @@ title: AvoidUsingEmptyCatchBlock ## Description -Empty catch blocks are considered a poor design choice because any errors occurring in a -`try` block cannot be handled. - -## How - -Use `Write-Error` or `throw` statements within the catch block. +Empty catch blocks aren't a good design choice because they can't handle errors that occur in a +`try` block. Add `Write-Error` or `throw` statements within the catch block to properly handle +exceptions. ## Example -### Wrong +### Noncompliant ```powershell try @@ -31,7 +28,7 @@ catch [DivideByZeroException] } ``` -### Correct +### Compliant ```powershell try diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingInvokeExpression.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingInvokeExpression.md index 7779008..74492d4 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingInvokeExpression.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingInvokeExpression.md @@ -1,6 +1,6 @@ --- description: Avoid Using Invoke-Expression -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingInvokeExpression --- @@ -10,25 +10,21 @@ title: AvoidUsingInvokeExpression ## Description -Care must be taken when using the `Invoke-Expression` command. The `Invoke-Expression` executes the -specified string and returns the results. +You must be careful when using the `Invoke-Expression` command. It executes the specified string and +returns the results. Don't use `Invoke-Expression`. -Code injection into your application or script can occur if the expression passed as a string -includes any data provided from the user. - -## How - -Remove the use of `Invoke-Expression`. +Code injection can occur in your application or script if the expression passed as a string includes +user-provided data. ## Example -### Wrong +### Noncompliant ```powershell Invoke-Expression 'Get-Process' ``` -### Correct +### Compliant ```powershell Get-Process diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPlainTextForPassword.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPlainTextForPassword.md index c25123e..267405a 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPlainTextForPassword.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPlainTextForPassword.md @@ -1,6 +1,6 @@ --- description: Avoid Using Plain Text For Password Parameter -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingPlainTextForPassword --- @@ -10,10 +10,11 @@ title: AvoidUsingPlainTextForPassword ## Description -Password parameters that take in plaintext will expose passwords and compromise the security of your -system. Passwords should be stored in the **SecureString** type. +Password parameters that accept plaintext instead of `-AsSecureString` expose passwords and can +compromise your system's security. You should store passwords in the [SecureString][01] type +instead. -The following parameters are considered password parameters (this is not case sensitive): +The following parameters are considered password parameters and aren't case sensitive: - Password - Pass @@ -22,16 +23,12 @@ The following parameters are considered password parameters (this is not case se - Passphrases - PasswordParam -If a parameter is defined with a name in the above list, it should be declared with type -**SecureString**. - -## How - -Change the type to **SecureString**. +If you define a parameter with a name from the provided list, declare it with the **SecureString** +type. ## Example -### Wrong +### Noncompliant ```powershell function Test-Script @@ -46,7 +43,7 @@ function Test-Script } ``` -### Correct +### Compliant ```powershell function Test-Script @@ -60,3 +57,7 @@ function Test-Script ... } ``` + + + +[01]: /dotnet/api/system.security.securestring diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPositionalParameters.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPositionalParameters.md index 1a1b77d..1fd7c5e 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPositionalParameters.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingPositionalParameters.md @@ -1,59 +1,60 @@ --- description: Avoid Using Positional Parameters -ms.date: 02/13/2024 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingPositionalParameters --- # AvoidUsingPositionalParameters -** Severity Level: Information ** +**Severity Level: Information** ## Description -Using positional parameters reduces the readability of code and can introduce errors. It is possible -that a future version of the cmdlet could change in a way that would break existing scripts if calls -to the cmdlet rely on the position of the parameters. +Using positional parameters reduces code readability and can introduce errors. It's possible +that a future version of the cmdlet could change in a way that'll break existing scripts if they +rely on parameter position. For simple cmdlets with only a few positional parameters, the risk is much smaller. To prevent this -rule from being too noisy, this rule gets only triggered when there are 3 or more parameters -supplied. A simple example where the risk of using positional parameters is negligible, is -`Test-Path $Path`. +rule from being too noisy, it's only triggered when there are 3 or more parameters supplied. A +simple example where the risk of using positional parameters is negligible, is `Test-Path $Path`. -## Configuration +Use full parameter names when calling commands. + +## Configure rule ```powershell Rules = @{ PSAvoidUsingPositionalParameters = @{ CommandAllowList = 'Join-Path', 'MyCmdletOrScript' - Enable = $true + Enable = $true } } ``` -### Parameters - -#### CommandAllowList: string[] (Default value is @()') - -Commands or scripts to be excluded from this rule. - -#### Enable: bool (Default value is `$true`) - -Enable or disable the rule during ScriptAnalyzer invocation. - -## How - -Use full parameter names when calling commands. - ## Example -### Wrong +### Noncompliant ```powershell Get-Command ChildItem Microsoft.PowerShell.Management ``` -### Correct +### Compliant ```powershell Get-Command -Noun ChildItem -Module Microsoft.PowerShell.Management ``` + +## Parameters + +### CommandAllowList: string[] (Default value is @()') + +Commands or scripts to be excluded from this rule as a string. Default value is `@()`. + +### Enable + +Enables (`$true`) the rule during ScriptAnalyzer invocation. Default value is `$true`. + +### Disable + +Disables (`$false`) the rule during ScriptAnalyzer invocation. diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingUsernameAndPasswordParams.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingUsernameAndPasswordParams.md index 32fbac3..4894291 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingUsernameAndPasswordParams.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingUsernameAndPasswordParams.md @@ -1,6 +1,6 @@ --- description: Avoid Using Username and Password Parameters -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingUsernameAndPasswordParams --- @@ -11,15 +11,12 @@ title: AvoidUsingUsernameAndPasswordParams ## Description To standardize command parameters, credentials should be accepted as objects of type -**PSCredential**. Functions should not make use of username or password parameters. - -## How - -Change the parameter to type **PSCredential**. +**PSCredential**. Functions shouldn't use separate username or password parameters. Instead, change +the parameters to accept a single **PSCredential** object. ## Example -### Wrong +### Noncompliant ```powershell function Test-Script @@ -36,7 +33,7 @@ function Test-Script } ``` -### Correct +### Compliant ```powershell function Test-Script