From 03b655cc80599229d7b89e7e01e486daa9ced20c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 13 Mar 2024 12:58:40 -0500 Subject: [PATCH] Update format and grammar of AvoidUsingAllowUnencryptedAuthentication (#1974) * Update format and grammar of AvoidUsingAllowUnencryptedAuthentication * Syncing docs changes to all rules * Update rules to match docs and improve wording --- docs/Rules/AvoidExclaimOperator.md | 13 ++++++++----- ...voidUsingAllowUnencryptedAuthentication.md | 13 +++++++------ docs/Rules/AvoidUsingPositionalParameters.md | 2 +- docs/Rules/README.md | 2 +- docs/Rules/ReservedParams.md | 10 ++++++---- .../UseDeclaredVarsMoreThanAssignments.md | 19 +++++++++++++++---- docs/Rules/UseSingularNouns.md | 2 +- 7 files changed, 39 insertions(+), 22 deletions(-) diff --git a/docs/Rules/AvoidExclaimOperator.md b/docs/Rules/AvoidExclaimOperator.md index 5ef833fc0..0eb4ff625 100644 --- a/docs/Rules/AvoidExclaimOperator.md +++ b/docs/Rules/AvoidExclaimOperator.md @@ -1,7 +1,7 @@ --- description: Avoid exclaim operator ms.custom: PSSA v1.22.0 -ms.date: 06/14/2023 +ms.date: 02/13/2024 ms.topic: reference title: AvoidExclaimOperator --- @@ -10,20 +10,23 @@ title: AvoidExclaimOperator ## Description -The negation operator `!` should not be used for readability purposes. Use `-not` instead. +Avoid using the negation operator (`!`). Use `-not` for improved readability. -**Note**: This rule is not enabled by default. The user needs to enable it through settings. +> [!NOTE] +> This rule is not enabled by default. The user needs to enable it through settings. ## How to Fix ## Example + ### Wrong： -```PowerShell + +```powershell $MyVar = !$true ``` ### Correct: -```PowerShell +```powershell $MyVar = -not $true ``` diff --git a/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md b/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md index c30b69844..e8ba28167 100644 --- a/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md +++ b/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md @@ -1,7 +1,7 @@ --- description: Avoid sending credentials and secrets over unencrypted connections ms.custom: PSSA v1.22.0 -ms.date: 11/06/2022 +ms.date: 02/28/2024 ms.topic: reference title: AvoidUsingAllowUnencryptedAuthentication --- @@ -11,14 +11,15 @@ title: AvoidUsingAllowUnencryptedAuthentication ## Description -Avoid using the `AllowUnencryptedAuthentication` switch on `Invoke-WebRequest`, `Invoke-RestMethod`, and other webrequest cmdlets, which sends credentials and secrets over unencrypted connections. -This should be avoided except for compatability with legacy systems. +Avoid using the **AllowUnencryptedAuthentication** parameter of `Invoke-WebRequest` and +`Invoke-RestMethod`. When using this parameter, the cmdlets send credentials and secrets over +unencrypted connections. This should be avoided except for compatibility with legacy systems. -For more details, see the documentation warning [here](https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest#-allowunencryptedauthentication). +For more details, see [Invoke-RestMethod](xref:Microsoft.PowerShell.Utility.Invoke-RestMethod). ## How -Avoid using the `AllowUnencryptedAuthentication` switch. +Avoid using the **AllowUnencryptedAuthentication** parameter. ## Example 1 @@ -32,4 +33,4 @@ Invoke-WebRequest foo -AllowUnencryptedAuthentication ```powershell Invoke-WebRequest foo -``` \ No newline at end of file +``` diff --git a/docs/Rules/AvoidUsingPositionalParameters.md b/docs/Rules/AvoidUsingPositionalParameters.md index 0078ffd70..d968b9f6e 100644 --- a/docs/Rules/AvoidUsingPositionalParameters.md +++ b/docs/Rules/AvoidUsingPositionalParameters.md @@ -1,7 +1,7 @@ --- description: Avoid Using Positional Parameters ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 02/13/2024 ms.topic: reference title: AvoidUsingPositionalParameters --- diff --git a/docs/Rules/README.md b/docs/Rules/README.md index ded305e89..b5761acaf 100644 --- a/docs/Rules/README.md +++ b/docs/Rules/README.md @@ -1,7 +1,7 @@ --- description: List of PSScriptAnalyzer rules ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 02/13/2024 ms.topic: reference title: List of PSScriptAnalyzer rules --- diff --git a/docs/Rules/ReservedParams.md b/docs/Rules/ReservedParams.md index 2d38c1af2..6e5c36a18 100644 --- a/docs/Rules/ReservedParams.md +++ b/docs/Rules/ReservedParams.md @@ -1,7 +1,7 @@ --- description: Reserved Parameters ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 03/06/2024 ms.topic: reference title: ReservedParams --- @@ -11,9 +11,9 @@ title: ReservedParams ## Description -You cannot use [reserved common parameters][01] in an advanced function. - -[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters +You can't redefine [common parameters][01] in an advanced function. Using the `CmdletBinding` or +`Parameter` attributes creates an advanced function. The common parameters are are automatically +available in advanced functions, so you can't redefine them. ## How @@ -48,3 +48,5 @@ function Test ) } ``` + +[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters diff --git a/docs/Rules/UseDeclaredVarsMoreThanAssignments.md b/docs/Rules/UseDeclaredVarsMoreThanAssignments.md index 482105db4..0fb7796c2 100644 --- a/docs/Rules/UseDeclaredVarsMoreThanAssignments.md +++ b/docs/Rules/UseDeclaredVarsMoreThanAssignments.md @@ -1,7 +1,7 @@ --- description: Extra Variables ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 03/06/2024 ms.topic: reference title: UseDeclaredVarsMoreThanAssignments --- @@ -44,10 +44,13 @@ function Test } ``` -### Special case +### Special cases -The following example triggers the **PSUseDeclaredVarsMoreThanAssignments** warning because `$bar` -is not used within the scriptblock where it was defined. +The following examples trigger the **PSUseDeclaredVarsMoreThanAssignments** warning. This behavior +is a limitation of the rule. There is no way to avoid these false positive warnings. + +In this case, the warning is triggered because `$bar` is not used within the scriptblock where it +was defined. ```powershell $foo | ForEach-Object { @@ -60,3 +63,11 @@ if($bar){ Write-Host 'Collection contained a false case.' } ``` + +In the next example, the warning is triggered because `$errResult` isn't recognized as being used in +the `Write-Host` command. + +```powershell +$errResult = $null +Write-Host 'Ugh:' -ErrorVariable errResult +``` diff --git a/docs/Rules/UseSingularNouns.md b/docs/Rules/UseSingularNouns.md index 6d1379664..e8d91677b 100644 --- a/docs/Rules/UseSingularNouns.md +++ b/docs/Rules/UseSingularNouns.md @@ -1,7 +1,7 @@ --- description: Cmdlet Singular Noun ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 02/13/2024 ms.topic: reference title: UseSingularNouns ---