Document PSSerializeJSONLongEnumAsNumber

Documents the new experiemental feature PSSerializeJSONLongEnumAsNumber
that aligns the serialization behaviour of enums based on long/ulong
with the other base types.

Author: jborean93

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