PWSH 7.5preview5: Breaking change in ConvertTo-Json??? Parameter '-EnumsAsStrings' must now be specified

[UselessGuru]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest released version
• Search the existing issues.
• Refer to the FAQ.
• Refer to Differences between Windows PowerShell 5.1 and PowerShell.

Steps to reproduce

Since 7.5preview5 enum values in objects are no longer returned as string by default.
Parameter '-EnumsAsStrings' must now be specified to get the same result as in previous releases.
7.5preview4 and 7.4.5 behave identitical and do not require '-EnumsAsStrings'.
I cannot see this change documented anywhere.

Note: I cannot find a way to produce 'copy-paste' examples.
Importing the XML-Data using ImportFrom-CliXML does not give the same results :-(

Expected behavior

Same as with older PWSH versions (incl. 7.5preview4)

$Object | ConvertTo-CliXML
<Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">
  <Obj RefId="0">
    <TN RefId="0">
      <T>OpenCl.DeviceType</T>
      <T>System.Enum</T>
      <T>System.ValueType</T>
      <T>System.Object</T>
    </TN>
    <ToString>Gpu</ToString>
    <U64>4</U64>
  </Obj>
</Objs>

$Object | ConvertTo-Json
"Gpu"

Actual behavior

$Object | ConvertTo-CliXML
<Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">
  <Obj RefId="0">
    <TN RefId="0">
      <T>OpenCl.DeviceType</T>
      <T>System.Enum</T>
      <T>System.ValueType</T>
      <T>System.Object</T>
    </TN>
    <ToString>Gpu</ToString>
    <U64>4</U64>
  </Obj>
</Objs>

$Object | ConvertTo-Json
"4"

$Object | ConvertTo-Json -EnumsAsStrings
"Gpu"

Error details

No response

Environment data

Name                           Value
----                           -----
PSVersion                      7.5.0-preview.5
PSEdition                      Core
GitCommitId                    7.5.0-preview.5
OS                             Microsoft Windows 10.0.22631
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

No response

[jborean93]

This change is from #20999 which treats an Int64 or UInt64 based enum (what you have here) the same way as any other enum integral type where the default JSON serialization is the integer value and -EnumsAsString will serialise the value as the enum label. The change was made to treat all enum types the same way and are all controlled by -EnumsAsString as right now any Int64/UInt64 based enums will always be a string regardless if -EnumsAsString is not present. The preview build always enables experimental features but in the final release users will have to opt into the experimental feature so it's not strictly a breaking change. In saying that if the experimental feature is ever made public then that will be a breaking change as it's no longer an opt-in change.

The documentation for this experimental feature is under PSSerializeJSONLongEnumAsNumber.

If you want to ensure the enum is always the string you should either specify -EnumsAsString or do ToString() on the value itself before serialization. This will ensure that the behaviour before and after this feature stays consistent and you won't be affected when/if the experimental feature ever becomes public.

[microsoft-github-policy-service]

📣 Hey @UselessGuru, how did we do? We would love to hear your feedback with the link below! 🗣️

🔗 https://aka.ms/PSRepoFeedback

Microsoft Forms