diff --git a/reference/docs-conceptual/developer/cmdlet/users-requesting-confirmation.md b/reference/docs-conceptual/developer/cmdlet/users-requesting-confirmation.md index 4abb19bec940..85a46cd5e3d0 100644 --- a/reference/docs-conceptual/developer/cmdlet/users-requesting-confirmation.md +++ b/reference/docs-conceptual/developer/cmdlet/users-requesting-confirmation.md @@ -1,6 +1,6 @@ --- description: Users Requesting Confirmation -ms.date: 09/30/2021 +ms.date: 09/24/2024 ms.topic: reference title: Users Requesting Confirmation --- @@ -9,15 +9,14 @@ title: Users Requesting Confirmation When you specify a value of `true` for the `SupportsShouldProcess` parameter of the Cmdlet attribute declaration, the **Confirm** parameter is added to the parameters of the cmdlet. -In the default environment, users can specify the **Confirm** parameter or `"-Confirm:$true` so that -confirmation is requested when the `ShouldProcess()` method is called. This forces confirmation -regardless of the impact level setting. +In the default environment, users can specify the **Confirm** parameter so that confirmation is +requested when the `ShouldProcess()` method is called. This forces confirmation regardless of the +impact level setting. If **Confirm** parameter is not used, the `ShouldProcess()` call requests confirmation if the -`$ConfirmPreference` preference variable is equal to or greater than the `ConfirmImpact` setting of -the cmdlet or provider. The default setting of `$ConfirmPreference` is **High**. Therefore, in the -default environment, only cmdlets and providers that specify a high-impact action request -confirmation. +`ConfirmImpact` setting is equal to or greater than the `$ConfirmPreference` preference variable. +The default setting of `$ConfirmPreference` is **High**. Therefore, in the default environment, only +cmdlets and providers that specify a high-impact action request confirmation. If **Confirm** is explicitly set to false (`-Confirm:$false`), the cmdlet runs without prompting for confirmation and the `$ConfirmPreference` shell variable is ignored. @@ -25,7 +24,7 @@ confirmation and the `$ConfirmPreference` shell variable is ignored. ## Remarks - For cmdlets and providers that specify `SupportsShouldProcess`, but not `ConfirmImpact`, those - actions are handled as "medium impact" actions, and they will not prompt by default. Their impact + actions are handled as `Medium` impact actions, and they will not prompt by default. Their impact level is less than the default setting of the `$ConfirmPreference` preference variable. - If the user specifies the `Verbose` parameter, they will be notified of the operation even if they diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md b/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md index 7e4cb80080a7..1dcee0c89b5f 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md @@ -1,7 +1,7 @@ --- description: ShouldProcess is an important feature that is often overlooked is. The WhatIf and Confirm parameters make it easy to add to your functions. ms.custom: contributor-KevinMarquette -ms.date: 11/16/2022 +ms.date: 09/24/2024 title: Everything you wanted to know about ShouldProcess --- # Everything you wanted to know about ShouldProcess @@ -11,9 +11,9 @@ One important feature that is often overlooked is `-WhatIf` and `-Confirm` suppo add to your functions. In this article, we dive deep into how to implement this feature. > [!NOTE] -> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The -> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at -> [PowerShellExplained.com][PowerShellExplained.com]. +> The [original version][original version] of this article appeared on the blog written by +> [@KevinMarquette][@KevinMarquette]. The PowerShell team thanks Kevin for sharing this content with +> us. Please check out his blog at [PowerShellExplained.com][PowerShellExplained.com]. This is a simple feature you can enable in your functions to provide a safety net for the users that need it. There's nothing scarier than running a command that you know can be dangerous for the @@ -21,8 +21,8 @@ first time. The option to run it with `-WhatIf` can make a big difference. ## CommonParameters -Before we look at implementing these [common parameters][common parameters], I want to take a quick look at how -they're used. +Before we look at implementing these [common parameters][common parameters], I want to take a quick +look at how they're used. ## Using -WhatIf @@ -141,6 +141,11 @@ Notice that I did not create a parameter called `-WhatIf`. Specifying `SupportsS automatically creates it for us. When we specify the `-WhatIf` parameter on `Test-ShouldProcess`, some things we call also perform `-WhatIf` processing. +> [!NOTE] +> When you use `SupportsShouldProcess`, PowerShell doesn't add the `$WhatIf` variable to the +> function. You don't need to check the value of `$WhatIf` because the `ShouldProcess()` method +> takes care of that for you. + ### Trust but verify There's some danger here trusting that everything you call inherits `-WhatIf` values. For the rest @@ -513,55 +518,44 @@ function Test-ShouldProcess { ConfirmImpact = 'High' )] param( - [Switch]$Force + [switch]$Force ) - if ($Force -and -not $Confirm){ + if ($Force -and -not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = 'None' } - if ($PSCmdlet.ShouldProcess('TARGET')){ + if ($PSCmdlet.ShouldProcess('TARGET')) { Write-Output "Some Action" } } ``` -We add our own `-Force` switch as a parameter. The `-Confirm` parameter is automatically added -when using `SupportsShouldProcess` in the `CmdletBinding`. - -```powershell -[CmdletBinding( - SupportsShouldProcess, - ConfirmImpact = 'High' -)] -param( - [Switch]$Force -) -``` - -Focusing in on the `-Force` logic here: +We add our own `-Force` switch as a parameter. The `-Confirm` parameter is automatically added when +using `SupportsShouldProcess` in the `CmdletBinding`. However, when you use `SupportsShouldProcess`, +PowerShell doesn't add the `$Confirm` variable to the function. If you are running in Strict Mode +and try to use the `$Confirm` variable before it has been defined, you get an error. To avoid the +error you can use `$PSBoundParameters` to test if the parameter was passed by the user. ```powershell -if ($Force -and -not $Confirm){ +if ($Force -and -not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = 'None' } ``` -If the user specifies `-Force`, we want to suppress the confirm prompt unless they also specify -`-Confirm`. This allows a user to force a change but still confirm the change. Then we set -`$ConfirmPreference` in the local scope. Now, using the `-Force` parameter temporarily sets the -`$ConfirmPreference` to none, disabling prompt for confirmation. +If the user specifies `-Force` we set `$ConfirmPreference` to `None` in the local scope. If the user +also specifies `-Confirm` then `ShoudProcess()` honors the values of the `-Confirm` parameter. ```powershell if ($PSCmdlet.ShouldProcess('TARGET')){ - Write-Output "Some Action" - } + Write-Output "Some Action" +} ``` If someone specifies both `-Force` and `-WhatIf`, then `-WhatIf` needs to take priority. This approach preserves `-WhatIf` processing because `ShouldProcess` always gets executed. -Do not add a check for the `$Force` value inside the `if` statement with the `ShouldProcess`. That is +Don't add a test for the `$Force` value inside the `if` statement with the `ShouldProcess`. That is an anti-pattern for this specific scenario even though that's what I show you in the next section for `ShouldContinue`. diff --git a/reference/docs-conceptual/learn/experimental-features.md b/reference/docs-conceptual/learn/experimental-features.md index bc346ccc36f8..bb79fbcb5533 100644 --- a/reference/docs-conceptual/learn/experimental-features.md +++ b/reference/docs-conceptual/learn/experimental-features.md @@ -1,6 +1,6 @@ --- description: Lists the currently available experimental features and how to use them. -ms.date: 08/28/2024 +ms.date: 09/24/2024 title: Using Experimental Features in PowerShell --- # Using Experimental Features in PowerShell @@ -15,14 +15,14 @@ breaking changes. > [!CAUTION] > Experimental features aren't intended to be used in production since the changes are allowed to be > breaking. Experimental features aren't officially supported. However, we appreciate any feedback -> and bug reports. You can file issues in the [GitHub source repository][25]. +> and bug reports. You can file issues in the [GitHub source repository][26]. For more information about enabling or disabling these features, see [about_Experimental_Features][06]. ## Experimental feature lifecycle -The [Get-ExperimentalFeature][29] cmdlet returns all experimental features available to PowerShell. +The [Get-ExperimentalFeature][30] cmdlet returns all experimental features available to PowerShell. Experimental features can come from modules or the PowerShell engine. Module-based experimental features are only available after you import the module. In the following example, the **PSDesiredStateConfiguration** isn't loaded, so the `PSDesiredStateConfiguration.InvokeDscResource` @@ -40,10 +40,11 @@ PSCommandWithArgs False PSEngine Enable `-CommandWithArgs` para PSFeedbackProvider True PSEngine Replace the hard-coded suggestion framework with … PSLoadAssemblyFromNativeCode False PSEngine Expose an API to allow assembly loading from nati… PSModuleAutoLoadSkipOfflineFiles True PSEngine Module discovery will skip over files that are ma… +PSSerializeJSONLongEnumAsNumber True PSEngine Serialize enums based on long or ulong as an nume… PSSubsystemPluginModel True PSEngine A plugin model for registering and un-registering… ``` -Use the [Enable-ExperimentalFeature][28] and [Disable-ExperimentalFeature][27] cmdlets to enable or +Use the [Enable-ExperimentalFeature][29] and [Disable-ExperimentalFeature][28] cmdlets to enable or disable a feature. You must start a new PowerShell session for this change to be in effect. Run the following command to enable the `PSCommandNotFoundSuggestion` feature: @@ -96,6 +97,7 @@ Legend | [PSCommandWithArgs][11] | | ![Experimental][02] | ![Experimental][02] | | [PSNativeWindowsTildeExpansion][22] | | | ![Experimental][02] | | [PSRedirectToVariable][24] | | | ![Experimental][02] | +| [PSSerializeJSONLongEnumAsNumber][25] | | | ![Experimental][02] | ### PSAnsiRenderingFileInfo @@ -213,7 +215,7 @@ a native executable. > The new behavior is a **breaking change** from current behavior. This may break scripts and > automation that work around the various issues when invoking native applications. Historically, > quotes must be escaped and it isn't possible to provide empty arguments to a native application. -> Use the [stop-parsing token][08] (`--%`) or the [`Start-Process`][31] cmdlet to sidestep native +> Use the [stop-parsing token][08] (`--%`) or the [`Start-Process`][32] cmdlet to sidestep native > argument passing when needed. This feature adds a new `$PSNativeCommandArgumentPassing` preference variable that controls this @@ -245,7 +247,7 @@ and non-Windows platforms is `Standard`. > [!NOTE] > The following examples use the `TestExe.exe` tool. You can build `TestExe` from the source code. -> See [TestExe][26] in the PowerShell source repository. +> See [TestExe][27] in the PowerShell source repository. New behaviors made available by this change: @@ -272,7 +274,7 @@ New behaviors made available by this change: For more examples of the new behavior, see [about_Parsing][07]. PowerShell 7.3 also added the ability to trace parameter binding for native commands. For more -information, see [Trace-Command][32]. +information, see [Trace-Command][34]. ### PSNativeCommandErrorActionPreference @@ -365,7 +367,7 @@ the PSReadLine module to provide custom prediction plugins. In future, **Job**, **CommandCompleter**, **Remoting** and other components could be separated into subsystem assemblies outside of `System.Management.Automation.dll`. -The experimental feature includes a new cmdlet, [Get-PSSubsystem][30]. This cmdlet is only available +The experimental feature includes a new cmdlet, [Get-PSSubsystem][31]. This cmdlet is only available when the feature is enabled. This cmdlet returns information about the subsystems that are available on the system. @@ -392,6 +394,36 @@ This feature only applies to Windows. On non-Windows platforms, tilde expansion This feature was added in PowerShell 7.5-preview.2. +### PSSerializeJSONLongEnumAsNumber + +This feature enables the cmdlet [ConvertTo-Json][33] to serialize any enum values based on +`Int64/long` or `UInt64/ulong` as a numeric value rather than the string representation of that enum +value. This aligns the behavior of enum serialization with other enum base types where the cmdlet +serializes enums as their numeric value. Use the **EnumsAsStrings** parameter to serialize as the +string representation. + +For example: + +```powershell +# PSSerializeJSONLongEnumAsNumber disabled +@{ + Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets +} | ConvertTo-Json +# { "Key": "Cmdlets" } + +# PSSerializeJSONLongEnumAsNumber enabled +@{ + Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets +} | ConvertTo-Json +# { "Key": 32 } + +# -EnumsAsStrings to revert back to the old behaviour +@{ + Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets +} | ConvertTo-Json -EnumsAsStrings +# { "Key": "Cmdlets" } +``` + [01]: ../../media/shared/check-mark-button-2705.svg [02]: ../../media/shared/construction-sign-1f6a7.svg @@ -414,11 +446,13 @@ This feature was added in PowerShell 7.5-preview.2. [22]: #psnativewindowstildeexpansion [23]: #pssubsystempluginmodel [24]: #psredirecttovariable -[25]: https://github.com/PowerShell/PowerShell/issues/new/choose -[26]: https://github.com/PowerShell/PowerShell/tree/master/test/tools/TestExe -[27]: xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature -[28]: xref:Microsoft.PowerShell.Core.Enable-ExperimentalFeature -[29]: xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature -[30]: xref:Microsoft.PowerShell.Core.Get-PSSubsystem -[31]: xref:Microsoft.PowerShell.Management.Start-Process -[32]: xref:Microsoft.PowerShell.Utility.Trace-Command +[25]: #psserializejsonlongenumasnumber +[26]: https://github.com/PowerShell/PowerShell/issues/new/choose +[27]: https://github.com/PowerShell/PowerShell/tree/master/test/tools/TestExe +[28]: xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature +[29]: xref:Microsoft.PowerShell.Core.Enable-ExperimentalFeature +[30]: xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature +[31]: xref:Microsoft.PowerShell.Core.Get-PSSubsystem +[32]: xref:Microsoft.PowerShell.Management.Start-Process +[33]: xref:Microsoft.PowerShell.Utility.ConvertTo-Json +[34]: xref:Microsoft.PowerShell.Utility.Trace-Command diff --git a/reference/docs-conceptual/security/app-control/application-control.md b/reference/docs-conceptual/security/app-control/application-control.md index 56b473edf6f3..b784de2e52c5 100644 --- a/reference/docs-conceptual/security/app-control/application-control.md +++ b/reference/docs-conceptual/security/app-control/application-control.md @@ -31,8 +31,8 @@ For more information about AppLocker and WDAC, see [Application Controls for Win ## WDAC policy enforcement -When PowerShell runs under a WDAC policy, its behavior changes based on the defined security -policy. Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in +When PowerShell runs under a WDAC policy, its behavior changes based on the defined security policy. +Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in `FullLanguage` mode. All other scripts and script blocks are untrusted and run in `ConstrainedLanguage` mode. PowerShell throws errors when the untrusted scripts attempt to perform actions that aren't allowed in `ConstrainedLanguage` mode. It can be difficult to know why a script @@ -41,9 +41,9 @@ failed to run correctly in `ConstrainedLanguage` mode. ## WDAC policy auditing PowerShell 7.4 added a new feature to support WDAC policies in **Audit** mode. In audit mode, -PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs messages -to the event log instead. The log messages describe what restrictions would apply if the policy were -in **Enforce** mode. +PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs +messages to the event log instead. The log messages describe what restrictions would apply if the +policy were in **Enforce** mode. ## History of changes @@ -54,9 +54,10 @@ described in the later versions include those from earlier versions. ### Changes in PowerShell 7.4 -On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, its behavior changes based on the defined security policy. Under a WDAC policy, PowerShell runs -trusted scripts and modules allowed by the policy in `FullLanguage` mode. All other scripts and -script blocks are untrusted and run in `ConstrainedLanguage` mode. PowerShell throws errors when the +On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, its +behavior changes based on the defined security policy. Under a WDAC policy, PowerShell runs trusted +scripts and modules allowed by the policy in `FullLanguage` mode. All other scripts and script +blocks are untrusted and run in `ConstrainedLanguage` mode. PowerShell throws errors when the untrusted scripts attempt to perform disallowed actions. It's difficult to know why a script fails to run correctly in `ConstrainedLanguage` mode. @@ -67,7 +68,8 @@ throwing errors. The log messages describe what restrictions would apply if the ### Changes in PowerShell 7.3 -- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC API. +- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC + API. ### Changes in PowerShell 7.2 diff --git a/reference/docs-conceptual/security/app-control/how-to-use-wdac.md b/reference/docs-conceptual/security/app-control/how-to-use-wdac.md index 482139c24fb9..0e58f08e75e7 100644 --- a/reference/docs-conceptual/security/app-control/how-to-use-wdac.md +++ b/reference/docs-conceptual/security/app-control/how-to-use-wdac.md @@ -10,8 +10,8 @@ can configure the policy to enforce or audit the policy's rule. In audit mode, P doesn't change but it logs Event ID 16387 messages to the `PowerShellCore/Analytic` event log. In enforcement mode, PowerShell applies the policy's restrictions. -This article assumes you're using a test machine so that you can test PowerShell behavior -under a machine wide WDAC policy before you deploy the policy in your environment. +This article assumes you're using a test machine so that you can test PowerShell behavior under a +machine wide WDAC policy before you deploy the policy in your environment. ## Create a WDAC policy @@ -21,8 +21,8 @@ approved files are allowed to load and run. PowerShell either blocks unapproved running or runs them in `ConstrainedLanguage` mode, depending on policy options. You create and manipulate WDAC policy using the **ConfigCI** module, which is available on all -supported Windows versions. This Windows PowerShell module can be used in Windows PowerShell 5.1 -or in PowerShell 7 through the **Windows Compatibility** layer. It's easier to use this module in +supported Windows versions. This Windows PowerShell module can be used in Windows PowerShell 5.1 or +in PowerShell 7 through the **Windows Compatibility** layer. It's easier to use this module in Windows PowerShell. The policy you create can be applied to any version of PowerShell. ## Steps to create a WDAC policy @@ -44,8 +44,8 @@ For testing, you just need to create a default policy and a self signed code sig 1. Disable Audit Mode in default policy A new policy is always created in `Audit` mode. To test policy enforcement, you need to disable - Audit mode when you apply the policy. Edit the `SystemCIPolicy.xml` file using a text editor - like `notepad.exe` or Visual Studio Code (VS Code). Comment out the `Audit mode` option. + Audit mode when you apply the policy. Edit the `SystemCIPolicy.xml` file using a text editor like + `notepad.exe` or Visual Studio Code (VS Code). Comment out the `Audit mode` option. ```XML