> ## Documentation Index
> Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# powershell/PSShouldProcess

> Should Process

`powershell/PSShouldProcess` is a PSScriptAnalyzer diagnostic emitted by tally for PowerShell snippets embedded in Dockerfiles.

| Property | Value             |
| -------- | ----------------- |
| Severity | Warning           |
| Category | PSScriptAnalyzer  |
| Default  | Disabled in tally |
| Auto-fix | No                |

<Note>
  tally disables this rule by default for Dockerfile `RUN` snippets because a `RUN` executes
  statements inline rather than defining cmdlets, parameters, or modules with external callers. Re-enable it with
  `include = ["powershell/PSShouldProcess"]` or by setting
  `rules.powershell.PSShouldProcess.severity = "warning"` in `.tally.toml`.
</Note>

## Description

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`.

For more information, see the following articles:

* [about\_Functions\_Advanced\_Methods][01]
* [about\_Functions\_CmdletBindingAttribute][02]
* [Everything you wanted to know about ShouldProcess][03]

## 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`.

## Examples

### Problematic code

```powershell theme={null}
function Set-File
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    Param
    (
        # Path to file
        [Parameter(Mandatory=$true)]
        $Path
    )
    'String' | Out-File -FilePath $Path
}
```

### Correct code

```powershell theme={null}
function Set-File
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    Param
    (
        # Path to file
        [Parameter(Mandatory=$true)]
        $Path,

        [Parameter(Mandatory=$true)]
        [string]$Content
    )

    if ($PSCmdlet.ShouldProcess($Path, ("Setting content to '{0}'" -f $Content)))
    {
        $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
    }
}
```

[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods

[02]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute

[03]: https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess

## Source

This rule documentation is adapted from Microsoft's PSScriptAnalyzer documentation for
[ShouldProcess](https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/blob/main/reference/docs-conceptual/PSScriptAnalyzer/Rules/ShouldProcess.md),
licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).