> ## 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/PSUseShouldProcessForStateChangingFunctions

> Use ShouldProcess For State Changing Functions

`powershell/PSUseShouldProcessForStateChangingFunctions` 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/PSUseShouldProcessForStateChangingFunctions"]` or by setting
  `rules.powershell.PSUseShouldProcessForStateChangingFunctions.severity = "warning"` in `.tally.toml`.
</Note>

## Description

Functions whose verbs change system state should support `ShouldProcess`. To enable the
`ShouldProcess` feature, set the `SupportsShouldProcess` argument in the `CmdletBinding` attribute.
The `SupportsShouldProcess` argument adds **Confirm** and **WhatIf** parameters to the function. The
**Confirm** parameter prompts the user before it runs the command on each object in the pipeline.
The **WhatIf** parameter lists the changes that the command would make, instead of running the
command.

Verbs that should support `ShouldProcess`:

* `New`
* `Set`
* `Remove`
* `Start`
* `Stop`
* `Restart`
* `Reset`
* `Update`

## How

Include the `SupportsShouldProcess` argument in the `CmdletBinding` attribute.

## Examples

### Problematic code

```powershell theme={null}
function Set-ServiceObject
{
    [CmdletBinding()]
    param
    (
        [string]
        $Parameter1
    )
    ...
}
```

### Correct code

```powershell theme={null}
function Set-ServiceObject
{
    [CmdletBinding(SupportsShouldProcess = $true)]
    param
    (
        [string]
        $Parameter1
    )
    ...
}
```

## More information

* [about\_Functions\_CmdletBindingAttribute][01]
* [Everything you wanted to know about ShouldProcess][04]
* [Required Development Guidelines][03]
* [Requesting Confirmation from Cmdlets][02]

[01]: /powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute

[02]: /powershell/scripting/developer/cmdlet/requesting-confirmation-from-cmdlets

[03]: /powershell/scripting/developer/cmdlet/required-development-guidelines#support-confirmation-requests-rd04

[04]: /powershell/scripting/learn/deep-dives/everything-about-shouldprocess

## Source

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