Skip to content

Commit 666596f

Browse files
jborean93jborean93
committed
Document PSSerializeJSONLongEnumAsNumber
Documents the new experiemental feature PSSerializeJSONLongEnumAsNumber that aligns the serialization behaviour of enums based on long/ulong with the other base types.
1 parent 4303089 commit 666596f

File tree

1 file changed

+66
-32
lines changed

1 file changed

+66
-32
lines changed

‎reference/docs-conceptual/learn/experimental-features.md‎

Lines changed: 66 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,14 @@ breaking changes.
1515
> [!CAUTION]
1616
> Experimental features aren't intended to be used in production since the changes are allowed to be
1717
> breaking. Experimental features aren't officially supported. However, we appreciate any feedback
18-
> and bug reports. You can file issues in the [GitHub source repository][24].
18+
> and bug reports. You can file issues in the [GitHub source repository][25].
1919
2020
For more information about enabling or disabling these features, see
2121
[about_Experimental_Features][06].
2222

2323
## Experimental feature lifecycle
2424

25-
The [Get-ExperimentalFeature][28] cmdlet returns all experimental features available to PowerShell.
25+
The [Get-ExperimentalFeature][29] cmdlet returns all experimental features available to PowerShell.
2626
Experimental features can come from modules or the PowerShell engine. Module-based experimental
2727
features are only available after you import the module. In the following example, the
2828
**PSDesiredStateConfiguration** isn't loaded, so the `PSDesiredStateConfiguration.InvokeDscResource`
@@ -40,10 +40,11 @@ PSCommandWithArgs False PSEngine Enable `-CommandWithArgs` para
4040
PSFeedbackProvider True PSEngine Replace the hard-coded suggestion framework with …
4141
PSLoadAssemblyFromNativeCode False PSEngine Expose an API to allow assembly loading from nati…
4242
PSModuleAutoLoadSkipOfflineFiles True PSEngine Module discovery will skip over files that are ma…
43+
PSSerializeJSONLongEnumAsNumber True PSEngine Serialize enums based on long or ulong as an nume…
4344
PSSubsystemPluginModel True PSEngine A plugin model for registering and un-registering…
4445
```
4546

46-
Use the [Enable-ExperimentalFeature][27] and [Disable-ExperimentalFeature][26] cmdlets to enable or
47+
Use the [Enable-ExperimentalFeature][28] and [Disable-ExperimentalFeature][27] cmdlets to enable or
4748
disable a feature. You must start a new PowerShell session for this change to be in effect. Run the
4849
following command to enable the `PSCommandNotFoundSuggestion` feature:
4950

@@ -81,23 +82,24 @@ Legend
8182
- The ![Discontinued][03] icon indicates the version of PowerShell where the experimental feature
8283
was removed
8384

84-
| Name | 7.2 | 7.3 | 7.4 |
85-
| --------------------------------------------------- | :-----------------: | :-----------------: | :-----------------: |
86-
| [PSCommandNotFoundSuggestion][10] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
87-
| [PSDesiredStateConfiguration.InvokeDscResource][14] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
88-
| [PSNativePSPathResolution][21] | ![Experimental][02] | ![Discontinued][03] | |
89-
| [PSSubsystemPluginModel][22] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
90-
| [PSNativeCommandArgumentPassing][18] | ![Experimental][02] | ![Mainstream][01] | |
91-
| [PSAnsiRenderingFileInfo][09] | ![Experimental][02] | ![Mainstream][01] | |
92-
| [PSLoadAssemblyFromNativeCode][16] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
93-
| [PSNativeCommandErrorActionPreference][19] | | ![Experimental][02] | ![Mainstream][01] |
94-
| [PSCustomTableHeaderLabelDecoration][13] | | | ![Mainstream][01] |
95-
| [PSFeedbackProvider][15] | | | ![Experimental][02] |
96-
| [PSModuleAutoLoadSkipOfflineFiles][17] | | | ![Experimental][02] |
97-
| [PSCommandWithArgs][11] | | | ![Experimental][02] |
98-
| [PSConstrainedAuditLogging][12] | | | ![Mainstream][01] |
99-
| [PSNativeCommandPreserveBytePipe][20] | | | ![Mainstream][01] |
100-
| [PSWindowsNativeCommandArgPassing][23] | | | ![Mainstream][01] |
85+
| Name | 7.2 | 7.3 | 7.4 | 7.5 |
86+
| --------------------------------------------------- | :-----------------: | :-----------------: | :-----------------: | :-----------------: |
87+
| [PSCommandNotFoundSuggestion][10] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
88+
| [PSDesiredStateConfiguration.InvokeDscResource][14] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
89+
| [PSNativePSPathResolution][21] | ![Experimental][02] | ![Discontinued][03] | | |
90+
| [PSSubsystemPluginModel][22] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
91+
| [PSNativeCommandArgumentPassing][18] | ![Experimental][02] | ![Mainstream][01] | | |
92+
| [PSAnsiRenderingFileInfo][09] | ![Experimental][02] | ![Mainstream][01] | | |
93+
| [PSLoadAssemblyFromNativeCode][16] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
94+
| [PSNativeCommandErrorActionPreference][19] | | ![Experimental][02] | ![Mainstream][01] | |
95+
| [PSCustomTableHeaderLabelDecoration][13] | | | ![Mainstream][01] | |
96+
| [PSFeedbackProvider][15] | | | ![Experimental][02] | ![Experimental][02] |
97+
| [PSModuleAutoLoadSkipOfflineFiles][17] | | | ![Experimental][02] | ![Experimental][02] |
98+
| [PSCommandWithArgs][11] | | | ![Experimental][02] | ![Experimental][02] |
99+
| [PSConstrainedAuditLogging][12] | | | ![Mainstream][01] | |
100+
| [PSNativeCommandPreserveBytePipe][20] | | | ![Mainstream][01] | |
101+
| [PSWindowsNativeCommandArgPassing][23] | | | ![Mainstream][01] | |
102+
| [PSSerializeJSONLongEnumAsNumber][24] | | | | ![Experimental][02] |
101103

102104
### PSAnsiRenderingFileInfo
103105

@@ -266,7 +268,7 @@ a native executable.
266268
> The new behavior is a **breaking change** from current behavior. This may break scripts and
267269
> automation that work around the various issues when invoking native applications. Historically,
268270
> quotes must be escaped and it isn't possible to provide empty arguments to a native application.
269-
> Use the [stop-parsing token][08] (`--%`) or the [`Start-Process`][30] cmdlet to sidestep native
271+
> Use the [stop-parsing token][08] (`--%`) or the [`Start-Process`][31] cmdlet to sidestep native
270272
> argument passing when needed.
271273
272274
This feature adds a new `$PSNativeCommandArgumentPassing` preference variable that controls this
@@ -298,7 +300,7 @@ and non-Windows platforms is `Standard`.
298300

299301
> [!NOTE]
300302
> The following examples use the `TestExe.exe` tool. You can build `TestExe` from the source code.
301-
> See [TestExe][25] in the PowerShell source repository.
303+
> See [TestExe][26] in the PowerShell source repository.
302304
303305
New behaviors made available by this change:
304306

@@ -325,7 +327,7 @@ New behaviors made available by this change:
325327
For more examples of the new behavior, see [about_Parsing][07].
326328

327329
PowerShell 7.3 also added the ability to trace parameter binding for native commands. For more
328-
information, see [Trace-Command][31].
330+
information, see [Trace-Command][32].
329331

330332
### PSNativeCommandErrorActionPreference
331333

@@ -436,7 +438,7 @@ the PSReadLine module to provide custom prediction plugins. In future, **Job**,
436438
**CommandCompleter**, **Remoting** and other components could be separated into subsystem assemblies
437439
outside of `System.Management.Automation.dll`.
438440

439-
The experimental feature includes a new cmdlet, [Get-PSSubsystem][29]. This cmdlet is only available
441+
The experimental feature includes a new cmdlet, [Get-PSSubsystem][30]. This cmdlet is only available
440442
when the feature is enabled. This cmdlet returns information about the subsystems that are available
441443
on the system.
442444

@@ -458,6 +460,36 @@ The feature changes the default values of the `$PSNativeCommandArgumentPassing`
458460

459461
Also, this feature adds new telemetry metrics to inform us how the feature is being used.
460462

463+
### PSSerializeJSONLongEnumAsNumber
464+
465+
This feature enables the cmdlet [ConvertTo-Json][33] to serialize any enum values based on
466+
`Int64/long` or `UInt64/ulong` as a numeric value rather than the string representation of that
467+
enum value. This aligns the behaviour of enum serialization with other enum base types where the
468+
cmdlet serializes enums as their numeric value. The `-EnumsAsStrings` parameter can use the previous
469+
behaviour to serialize as the string representation.
470+
471+
For example:
472+
473+
```powershell
474+
# PSSerializeJSONLongEnumAsNumber disabled
475+
@{
476+
Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets
477+
} | ConvertTo-Json
478+
# { "Key": "Cmdlets" }
479+
480+
# PSSerializeJSONLongEnumAsNumber enabled
481+
@{
482+
Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets
483+
} | ConvertTo-Json
484+
# { "Key": 32 }
485+
486+
# -EnumsAsStrings to revert back to the old behaviour
487+
@{
488+
Key = [System.Management.Automation.Tracing.PowerShellTraceKeywords]::Cmdlets
489+
} | ConvertTo-Json -EnumsAsStrings
490+
# { "Key": "Cmdlets" }
491+
```
492+
461493
<!-- link references -->
462494
[01]: ../../media/shared/check-mark-button-2705.svg
463495
[02]: ../../media/shared/construction-sign-1f6a7.svg
@@ -482,11 +514,13 @@ Also, this feature adds new telemetry metrics to inform us how the feature is be
482514
[21]: #psnativepspathresolution
483515
[22]: #pssubsystempluginmodel
484516
[23]: #pswindowsnativecommandargpassing
485-
[24]: https://github.com/PowerShell/PowerShell/issues/new/choose
486-
[25]: https://github.com/PowerShell/PowerShell/tree/master/test/tools/TestExe
487-
[26]: xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature
488-
[27]: xref:Microsoft.PowerShell.Core.Enable-ExperimentalFeature
489-
[28]: xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature
490-
[29]: xref:Microsoft.PowerShell.Core.Get-PSSubsystem
491-
[30]: xref:Microsoft.PowerShell.Management.Start-Process
492-
[31]: xref:Microsoft.PowerShell.Utility.Trace-Command
517+
[24]: #psserializejsonlongenumasnumber
518+
[25]: https://github.com/PowerShell/PowerShell/issues/new/choose
519+
[26]: https://github.com/PowerShell/PowerShell/tree/master/test/tools/TestExe
520+
[27]: xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature
521+
[28]: xref:Microsoft.PowerShell.Core.Enable-ExperimentalFeature
522+
[29]: xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature
523+
[30]: xref:Microsoft.PowerShell.Core.Get-PSSubsystem
524+
[31]: xref:Microsoft.PowerShell.Management.Start-Process
525+
[32]: xref:Microsoft.PowerShell.Utility.Trace-Command
526+
[33]: xref:Microsoft.PowerShell.Utility.ConvertTo-Json

0 commit comments

Comments
 (0)