From ed2e99cc1ac13326dc7ccd39ef2ce636a4d7a3ab Mon Sep 17 00:00:00 2001
From: Jordan Borean <jborean93@gmail.com>
Date: Wed, 14 Feb 2024 10:42:30 +1000
Subject: [PATCH] Document PSSerializeJSONLongEnumAsNumber
Documents the new experiemental feature PSSerializeJSONLongEnumAsNumber
that aligns the serialization behaviour of enums based on long/ulong
with the other base types.
---
.../learn/experimental-features.md | 66 ++++++++++++++-----
1 file changed, 50 insertions(+), 16 deletions(-)
diff --git a/reference/docs-conceptual/learn/experimental-features.md b/reference/docs-conceptual/learn/experimental-features.md
index bc346ccc36f..bb79fbcb553 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" }
+```
+
<!-- link references -->
[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