From a4cc15c2b729714b2d62692c4b872128331c65b8 Mon Sep 17 00:00:00 2001 From: Masaru Iritani <25241373+masaru-iritani@users.noreply.github.com> Date: Sun, 23 Jan 2022 15:42:07 +0900 Subject: [PATCH 1/6] Fix ShouldProcess examples --- docs/Rules/ShouldProcess.md | 61 ++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 013fd2e77..456c613b6 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -1,7 +1,7 @@ --- description: Should Process ms.custom: PSSA v1.20.0 -ms.date: 10/18/2021 +ms.date: 01/23/2022 ms.topic: reference title: ShouldProcess --- @@ -14,55 +14,52 @@ title: ShouldProcess If a cmdlet declares the `SupportsShouldProcess` attribute, then it should also call `ShouldProcess`. A violation is any function which either declares `SupportsShouldProcess` attribute but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not declare -`SupportsShouldProcess` +`SupportsShouldProcess`. For more information, please refer to `about_Functions_Advanced_Methods` and -`about_Functions_CmdletBindingAttribute` +`about_Functions_CmdletBindingAttribute`. ## How To fix a violation of this rule, please call `ShouldProcess` method when a cmdlet declares `SupportsShouldProcess` attribute. Or please add `SupportsShouldProcess` attribute argument when -calling `ShouldProcess` +calling `ShouldProcess`. ## Example ### Wrong ```powershell - function Set-File - { - [CmdletBinding(SupportsShouldProcess=$true)] - Param - ( - # Path to file - [Parameter(Mandatory=$true)] - $Path - ) - "String" | Out-File -FilePath $FilePath - } +function Set-File +{ + [CmdletBinding(SupportsShouldProcess=$true)] + Param + ( + # Path to file + [Parameter(Mandatory=$true)] + $Path + ) + + "String" | Out-File -FilePath $Path +} ``` ### Correct ```powershell - function Set-File - { - [CmdletBinding(SupportsShouldProcess=$true)] - Param - ( - # Path to file - [Parameter(Mandatory=$true)] - $Path - ) +function Set-File +{ + [CmdletBinding(SupportsShouldProcess=$true)] + Param + ( + # Path to file + [Parameter(Mandatory=$true)] + $Path + ) - if ($PSCmdlet.ShouldProcess("Target", "Operation")) - { - "String" | Out-File -FilePath $FilePath - } - else - { - Write-Host ('Write "String" to file {0}' -f $FilePath) - } + if ($PSCmdlet.ShouldProcess($Path, "Write")) + { + "String" | Out-File -FilePath $Path } +} ``` From 7bddbc953f0356cdf299de44dc330a84b1d385b0 Mon Sep 17 00:00:00 2001 From: Masaru Iritani <25241373+masaru-iritani@users.noreply.github.com> Date: Sun, 23 Jan 2022 15:47:02 +0900 Subject: [PATCH 2/6] Fix Severity of ShouldProcess to Warning --- docs/Rules/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Rules/README.md b/docs/Rules/README.md index e695e7039..aec9ff777 100644 --- a/docs/Rules/README.md +++ b/docs/Rules/README.md @@ -55,7 +55,7 @@ The PSScriptAnalyzer contains the following rule definitions. | [ReservedCmdletChar](./ReservedCmdletChar.md) | Error | Yes | | | [ReservedParams](./ReservedParams.md) | Error | Yes | | | [ReviewUnusedParameter](./ReviewUnusedParameter.md) | Warning | Yes | | -| [ShouldProcess](./ShouldProcess.md) | Error | Yes | | +| [ShouldProcess](./ShouldProcess.md) | Warning | Yes | | | [UseApprovedVerbs](./UseApprovedVerbs.md) | Warning | Yes | | | [UseBOMForUnicodeEncodedFile](./UseBOMForUnicodeEncodedFile.md) | Warning | Yes | | | [UseCmdletCorrectly](./UseCmdletCorrectly.md) | Warning | Yes | | From 4eea026a8b3cf3daee2062bdbc854bbd4cddd9a7 Mon Sep 17 00:00:00 2001 From: Masaru Iritani <25241373+masaru-iritani@users.noreply.github.com> Date: Sat, 29 Jan 2022 22:39:55 +0900 Subject: [PATCH 3/6] Add Get-Help --- docs/Rules/ShouldProcess.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 456c613b6..8a7e02dbf 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -16,8 +16,8 @@ If a cmdlet declares the `SupportsShouldProcess` attribute, then it should also but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not declare `SupportsShouldProcess`. -For more information, please refer to `about_Functions_Advanced_Methods` and -`about_Functions_CmdletBindingAttribute`. +For more information, see `Get-Help about_Functions_Advanced_Methods` and +`Get-Help about_Functions_CmdletBindingAttribute`. ## How From e2d69dda4fd3496c47cc4c6c6fc970d40caca920 Mon Sep 17 00:00:00 2001 From: Masaru Iritani <25241373+masaru-iritani@users.noreply.github.com> Date: Sun, 30 Jan 2022 09:20:13 +0900 Subject: [PATCH 4/6] Update links --- docs/Rules/ShouldProcess.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 8a7e02dbf..2330733fe 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -16,8 +16,11 @@ If a cmdlet declares the `SupportsShouldProcess` attribute, then it should also but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not declare `SupportsShouldProcess`. -For more information, see `Get-Help about_Functions_Advanced_Methods` and -`Get-Help about_Functions_CmdletBindingAttribute`. +For more information, please refer to [about_Functions_Advanced_Methods][1] and +[about_Functions_CmdletBindingAttribute][2]. + +[1]: /powershell/module/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods +[2]: /powershell/module/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute ## How From 36f32f0e0ee7c7174d7fca74c432f0e7508be259 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 29 Mar 2022 15:07:36 -0500 Subject: [PATCH 5/6] Copy example from Docs repo --- docs/Rules/ShouldProcess.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 2330733fe..09b266fb8 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -57,12 +57,20 @@ function Set-File ( # Path to file [Parameter(Mandatory=$true)] - $Path + $Path, + + [Parameter(Mandatory=$true)] + [string]$Content ) - if ($PSCmdlet.ShouldProcess($Path, "Write")) + if ($PSCmdlet.ShouldProcess($Path, ("Setting content to '{0}'" -f $Content))) + { + $Content | Out-File -FilePath $Path + } + else { - "String" | Out-File -FilePath $Path + # Code that should be processed if doing a WhatIf operation + # Must NOT change anything outside of the function / script } } ``` From f2a247be3808d06935ed84b43885a15f9dbcddf2 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 29 Mar 2022 15:25:30 -0500 Subject: [PATCH 6/6] Update ShouldProcess.md --- docs/Rules/ShouldProcess.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 09b266fb8..0e8c95b50 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -67,10 +67,5 @@ function Set-File { $Content | Out-File -FilePath $Path } - else - { - # Code that should be processed if doing a WhatIf operation - # Must NOT change anything outside of the function / script - } } ```