Skip to content

Commit

Permalink
Document PSSerializeJSONLongEnumAsNumber
Browse files Browse the repository at this point in the history 
Documents the new experiemental feature PSSerializeJSONLongEnumAsNumber
that aligns the serialization behaviour of enums based on long/ulong
with the other base types.
  • Loading branch information
@jborean93
jborean93 committed Feb 14, 2024
1 parent 4303089 commit 666596f
Showing 1 changed file with 66 additions and 32 deletions.
98 changes: 66 additions & 32 deletions reference/docs-conceptual/learn/experimental-features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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][24].
> and bug reports. You can file issues in the [GitHub source repository][25].
For more information about enabling or disabling these features, see
[about_Experimental_Features][06].

## Experimental feature lifecycle

The [Get-ExperimentalFeature][28] cmdlet returns all experimental features available to PowerShell.
The [Get-ExperimentalFeature][29] 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`
Expand All @@ -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][27] and [Disable-ExperimentalFeature][26] cmdlets to enable or
Use the [Enable-ExperimentalFeature][28] and [Disable-ExperimentalFeature][27] 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:

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

| Name | 7.2 | 7.3 | 7.4 |
| --------------------------------------------------- | :-----------------: | :-----------------: | :-----------------: |
| [PSCommandNotFoundSuggestion][10] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSDesiredStateConfiguration.InvokeDscResource][14] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativePSPathResolution][21] | ![Experimental][02] | ![Discontinued][03] | |
| [PSSubsystemPluginModel][22] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativeCommandArgumentPassing][18] | ![Experimental][02] | ![Mainstream][01] | |
| [PSAnsiRenderingFileInfo][09] | ![Experimental][02] | ![Mainstream][01] | |
| [PSLoadAssemblyFromNativeCode][16] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativeCommandErrorActionPreference][19] | | ![Experimental][02] | ![Mainstream][01] |
| [PSCustomTableHeaderLabelDecoration][13] | | | ![Mainstream][01] |
| [PSFeedbackProvider][15] | | | ![Experimental][02] |
| [PSModuleAutoLoadSkipOfflineFiles][17] | | | ![Experimental][02] |
| [PSCommandWithArgs][11] | | | ![Experimental][02] |
| [PSConstrainedAuditLogging][12] | | | ![Mainstream][01] |
| [PSNativeCommandPreserveBytePipe][20] | | | ![Mainstream][01] |
| [PSWindowsNativeCommandArgPassing][23] | | | ![Mainstream][01] |
| Name | 7.2 | 7.3 | 7.4 | 7.5 |
| --------------------------------------------------- | :-----------------: | :-----------------: | :-----------------: | :-----------------: |
| [PSCommandNotFoundSuggestion][10] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSDesiredStateConfiguration.InvokeDscResource][14] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativePSPathResolution][21] | ![Experimental][02] | ![Discontinued][03] | | |
| [PSSubsystemPluginModel][22] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativeCommandArgumentPassing][18] | ![Experimental][02] | ![Mainstream][01] | | |
| [PSAnsiRenderingFileInfo][09] | ![Experimental][02] | ![Mainstream][01] | | |
| [PSLoadAssemblyFromNativeCode][16] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] |
| [PSNativeCommandErrorActionPreference][19] | | ![Experimental][02] | ![Mainstream][01] | |
| [PSCustomTableHeaderLabelDecoration][13] | | | ![Mainstream][01] | |
| [PSFeedbackProvider][15] | | | ![Experimental][02] | ![Experimental][02] |
| [PSModuleAutoLoadSkipOfflineFiles][17] | | | ![Experimental][02] | ![Experimental][02] |
| [PSCommandWithArgs][11] | | | ![Experimental][02] | ![Experimental][02] |
| [PSConstrainedAuditLogging][12] | | | ![Mainstream][01] | |
| [PSNativeCommandPreserveBytePipe][20] | | | ![Mainstream][01] | |
| [PSWindowsNativeCommandArgPassing][23] | | | ![Mainstream][01] | |
| [PSSerializeJSONLongEnumAsNumber][24] | | | | ![Experimental][02] |

### PSAnsiRenderingFileInfo

Expand Down Expand Up @@ -266,7 +268,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`][30] cmdlet to sidestep native
> Use the [stop-parsing token][08] (`--%`) or the [`Start-Process`][31] cmdlet to sidestep native
> argument passing when needed.
This feature adds a new `$PSNativeCommandArgumentPassing` preference variable that controls this
Expand Down Expand Up @@ -298,7 +300,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][25] in the PowerShell source repository.
> See [TestExe][26] in the PowerShell source repository.
New behaviors made available by this change:

Expand All @@ -325,7 +327,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][31].
information, see [Trace-Command][32].

### PSNativeCommandErrorActionPreference

Expand Down Expand Up @@ -436,7 +438,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][29]. This cmdlet is only available
The experimental feature includes a new cmdlet, [Get-PSSubsystem][30]. This cmdlet is only available
when the feature is enabled. This cmdlet returns information about the subsystems that are available
on the system.

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

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

### 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 behaviour of enum serialization with other enum base types where the
cmdlet serializes enums as their numeric value. The `-EnumsAsStrings` parameter can use the previous
behaviour 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
Expand All @@ -482,11 +514,13 @@ Also, this feature adds new telemetry metrics to inform us how the feature is be
[21]: #psnativepspathresolution
[22]: #pssubsystempluginmodel
[23]: #pswindowsnativecommandargpassing
[24]: https://github.com/PowerShell/PowerShell/issues/new/choose
[25]: https://github.com/PowerShell/PowerShell/tree/master/test/tools/TestExe
[26]: xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature
[27]: xref:Microsoft.PowerShell.Core.Enable-ExperimentalFeature
[28]: xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature
[29]: xref:Microsoft.PowerShell.Core.Get-PSSubsystem
[30]: xref:Microsoft.PowerShell.Management.Start-Process
[31]: xref:Microsoft.PowerShell.Utility.Trace-Command
[24]: #psserializejsonlongenumasnumber
[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
[33]: xref:Microsoft.PowerShell.Utility.ConvertTo-Json

0 comments on commit 666596f

Please sign in to comment.