Add PSJsonSerializerV2 for ConvertTo-Json using TruncatingConverterFactory #26654

yotsuda · 2026-01-03T00:03:27Z

PR Summary

Implements TruncatingConverterFactory pattern for ConvertTo-Json V2 as discussed with @iSazonov in PR #26637.

This PR is an alternative implementation approach based on the Factory pattern, branched from feature-convertto-json-isazonov-approach.

Fixes #5749

PR Context

Background

In PR #26637, @iSazonov suggested implementing the Factory approach in a new PR to evaluate whether it provides a better architecture than the current implementation.

"I can't say for sure which approach will be the best for us in the end. Therefore, it is better to implement the factory approach with a new PR."

Thanks to @iSazonov's guidance on the technical considerations, this implementation now works correctly.

Solution

This implementation uses a TruncatingConverterFactory that dispatches to type-specific converters:

Type	Converter
PSObject	`JsonConverterPSObject` (Extended/Adapted properties)
IDictionary	`JsonConverterDictionary<T>` (Base properties only)
IEnumerable	`JsonConverterEnumerable<T>`
Composite objects	`JsonConverterComposite<T>` (Base properties only)
Primitives	STJ default converters

Architecture Benefits

Type-level dispatch - STJ caches converters per type, improving performance
Clear separation - Each converter handles one concern
Extensibility - Easy to add new type-specific converters

Key Differences from PR #26637

Aspect	PR #26637	This PR (Factory)
Raw object handling	`RawObjectWrapper` class	`TruncatingConverterFactory` dispatch
Type dispatch	Manual in `WriteValue`	Factory pattern with generic converters
Converter structure	Single `JsonConverterPSObject` with `_basePropertiesOnly` flag	Separate converters per type category

PR Checklist

PR has a meaningful title
Summarized changes
Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
This PR is ready to merge
Breaking changes: Experimental feature needed
- Experimental feature name: PSJsonSerializerV2
User-facing changes: Documentation needed
Testing: New tests added

Changes Made

Modified Files

`ConvertToJsonCommandV2.cs`

Added TruncatingConverterFactory - dispatches to appropriate converters based on type
Added JsonConverterDictionary<T> - handles IDictionary types
Added JsonConverterEnumerable<T> - handles IEnumerable types
Added JsonConverterComposite<T> - handles composite objects with Base properties only
Removed RawObjectWrapper class
Removed _basePropertiesOnly field and filterToPropertyOnly parameter from JsonConverterPSObject
Added WriteValue helper to JsonSerializerHelper

`ConvertTo-Json.PSJsonSerializerV2.Tests.ps1`

Removed array element test that now matches V1 behavior

Testing

Existing Tests (ConvertTo-Json.Tests.ps1)

36 passed, 1 failed, 1 pending
The single failure is a DateTime test with timezone-dependent expectations (unrelated to this change)

V2 Specific Tests (ConvertTo-Json.PSJsonSerializerV2.Tests.ps1)

4 passed, 0 failed

Related Work

PR/Issue	Description
#26637	Original implementation (this PR is an alternative approach)
#5749	Dictionary with non-string keys handling

Branch Structure

gitGraph
    commit id: "master"
    branch system-text-json
    commit id: "77d8a1b0c"
    commit id: "159b76387"
    branch isazonov-approach
    commit id: "e7dfff962"
    commit id: "da0c8cbfb"
    branch factory-test
    commit id: "test" type: REVERSE
    checkout isazonov-approach
    commit id: "6913cb119"
    commit id: "2ecc51e05"
    commit id: "2c549207a" tag: "PR #26637"
    branch factory-v2
    commit id: "af393269b" tag: "HEAD"
    checkout system-text-json
    commit id: "07cea1dc5" tag: "PR #26624"

Branch	Base	PR	Status
`system-text-json`	master	#26624	Superseded
`isazonov-approach`	system-text-json	#26637	Open
`factory-test`	isazonov-approach	-	Experiment (failed)
`factory-v2`	isazonov-approach	This PR	✅ Success

…ctory

iSazonov

@yotsuda Thanks for starting the approach!

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

…Cmdlet/ConvertToJsonCommandV2.cs Co-authored-by: Ilya <darpa@yandex.ru>

iSazonov · 2026-01-04T05:40:26Z

@yotsuda It seems you lost last commits - I don't see updates.

yotsuda · 2026-01-04T06:17:43Z

@iSazonov Sorry, I missed the same pattern in WriteValue. Fixed in 165ed2e.
See: https://github.com/PowerShell/PowerShell/blob/165ed2ef9/src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs#L1012-L1016

GitHub
PowerShell/src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs at 165ed2ef970cb4ffa2feb237fac8e019f62d2002 · PowerShell/PowerShell
PowerShell for every system! Contribute to PowerShell/PowerShell development by creating an account on GitHub.

iSazonov

@yotsuda Great progress! Thanks!

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

iSazonov · 2026-01-04T16:00:28Z

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

+
+            // Convert to string when depth exceeded
+            string stringValue = LanguagePrimitives.ConvertTo<string>(pso.ImmediateBaseObjectIsEmpty ? pso : obj);
+            writer.WriteStringValue(stringValue);


It seems you don't understand my request. I mean if max depth is reached, V1 convert base object to string and process extended/adapted properties too. In V2 we only convert base object to string but don't process extended/adapted properties.

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

…e write-only check to WriteProperty

iSazonov · 2026-01-05T07:24:23Z

Please see failed tests.
For "AddMember on JsonObject" I see:

$jstr
{
  "Major": 2,
  "Minor": 3,
  "Build": 4,
  "Revision": 14,
  "MajorRevision": 0,
  "MinorRevision": 14,
  "Note": "a version object",
  "Rev": 14,
  "IsOld": true
}

What is $jstr in V2?

As for 127 serialization I think we can select expected result based on the experimental feature status.

…actory

…lization

…ory state

…aching

iSazonov

@yotsuda Thanks for your efforts! I didn't expect that there would be so many difficulties, but it seems that we have already overcome most of them.

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

iSazonov · 2026-01-05T18:05:43Z

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

+
+            // GetTypeInfo() has internal caching, no need for additional cache
+            var typeInfo = JsonSerializerOptions.Default.GetTypeInfo(type);
+            return typeInfo.Kind == JsonTypeInfoKind.None;


How do we process type(object) in V1 and V2?
See https://source.dot.net/#System.Text.Json/System/Text/Json/Serialization/Metadata/JsonTypeInfo.cs,1337

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

iSazonov · 2026-01-05T18:19:43Z

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

+        public static bool ShouldSkipProperty(PSPropertyInfo prop)
+        {
+            // Check for Hidden attribute
+            if (prop.IsHidden)


Interesting, how this (doesn't) works for script-defined classes.

…7 serialization

… factory

…y object

…fined classes

yotsuda · 2026-01-06T00:37:58Z

Please see failed tests. For "AddMember on JsonObject" I see:
...
What is $jstr in V2?
As for 127 serialization I think we can select expected result based on the experimental feature status.

Both issues are fixed in the latest commits.

AddMember on JsonObject (Version + ETS):

V2 now produces the same output as V1 for Version objects with ETS properties:

$versionObject = New-Object System.Version 2, 3, 4, 14
$versionObject | Add-Member -MemberType NoteProperty -Name Note -Value "a version object"
$versionObject | Add-Member -MemberType ScriptProperty -Name Rev -Value { $this.Revision }
$versionObject | Add-Member -MemberType ScriptProperty -Name IsOld -Value { $this.Major -lt 3 }
$versionObject | ConvertTo-Json

Output (both V1 and V2):
{
  "Major": 2,
  "Minor": 3,
  "Build": 4,
  "Revision": 14,
  "MajorRevision": 0,
  "MinorRevision": 14,
  "Note": "a version object",
  "Rev": 14,
  "IsOld": true
}

The fix adds V1-compatible logic: "true primitive types" (string, DateTime, etc.) always serialize as scalars ignoring ETS, while non-primitive STJ scalar types (Version, IPAddress, etc.) serialize as objects when they have ETS properties.

[char]127 serialization:

Implemented as you suggested - the test now selects expected result based on experimental feature status:

$expectedToJson = $testCase.ToJson
if ($testCase.ToJsonV2 -and (Get-ExperimentalFeature PSJsonSerializerV2).Enabled)
{
    $expectedToJson = $testCase.ToJsonV2
}

V1: "" (DEL control character disappears)
V2: "\u007F" (correct Unicode escape)

Commit: 8efb723

…eeded

iSazonov

@yotsuda Thanks! It seems I see final :-)

I expect you to address all the previous comments that are not closed. After that, we should work on compatibility tests and come back here to complete the work.

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

iSazonov · 2026-01-06T06:33:10Z

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

+                return false;
+            }
+
+            // V1 primitive types always serialize as scalars, ignoring ETS properties


Are you sure? I see V1 code (ProcessValue method) skip ETS in AddPsProperties method only if:

isPureObj = true (LanguagePrimitives.ConvertTo() add ETS)

it is not PSObject (it is raw object)

It is string or Datetime type.

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

test/powershell/Modules/Microsoft.PowerShell.Utility/Json.Tests.ps1

…Cmdlet/ConvertToJsonCommandV2.cs Co-authored-by: Ilya <darpa@yandex.ru>

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

iSazonov · 2026-01-06T19:33:35Z

src/Microsoft.PowerShell.Commands.Utility/commands/utility/WebCmdlet/ConvertToJsonCommandV2.cs

+        private void SerializeAsObject(Utf8JsonWriter writer, PSObject pso, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+            AppendPSProperties(writer, pso, options, PSMemberViewTypes.Extended | PSMemberViewTypes.Adapted);


I see V1 does:

Enumerate properties using reflection.

Add extended and adapted properties (excluding duplicates from 1.).

It seems if we request adapted properties we get reflection properties too. I guess there may be differences, but I do not know how it works in depth.

@SeeminglyScience @daxian-dbw Could you please help?

I created Version type object, then add ETS noteproperty with Add-Member, then request properties with PSMemberInfoIntegratingCollection:

for Base I see only the note property,

for Extended I see only the note property,

for Adapted I see the note property and native properties.

My understanding is that is how PSObject wrapping works. PSObject is a property bag. So for Base just the ps object is considered. For Extend - only ETS properties as exclusively separate. For Adapted - adapters are involved including .Net Adapter which return native .Net members. Some adapters can be invovled (including XML, CIM/WMI,COM). Property priority is Extended -> Adapded -> Base.

V1 code add native .Net properties by reflection then enumerate Extended and Adapted ones with PSMemberInfoIntegratingCollection and add them only if the name is not already in list. So reflection properties win.
If we use only PSMemberInfoIntegratingCollection in V2 - Extended properties win. It is breaking change.
Perhaps it would be worthwhile to adhere to this native PowerShell behavior, but since historically this cmdlet works differently, it is not difficult for us to do the same by taking properties from the Json Default cache or by psObj.Properties.Match("*", PSMemberTypes.Property); (although it is more expensive).

…ack in WriteProperty

Add PSJsonSerializerV2 for ConvertTo-Json using TruncatingConverterFa…

af39326

…ctory

yotsuda marked this pull request as ready for review January 3, 2026 00:04

iSazonov reviewed Jan 3, 2026

View reviewed changes

yotsuda and others added 4 commits January 4, 2026 10:20

Update src/Microsoft.PowerShell.Commands.Utility/commands/utility/Web…

657d034

…Cmdlet/ConvertToJsonCommandV2.cs Co-authored-by: Ilya <darpa@yandex.ru>

Update src/Microsoft.PowerShell.Commands.Utility/commands/utility/Web…

ef6fc9e

…Cmdlet/ConvertToJsonCommandV2.cs Co-authored-by: Ilya <darpa@yandex.ru>

Rename converters with PSJson prefix and refactor code structure

4095b20

Replace explicit type checks with Debug.Assert in CanConvert

783f3b3

yotsuda force-pushed the feature-convertto-json-factory-v2 branch from 74a83c8 to 783f3b3 Compare January 4, 2026 05:03

Simplify WriteValue method to match Serialize pattern

165ed2e

iSazonov reviewed Jan 4, 2026

View reviewed changes

Simplify IsScalar and WriteValue by removing redundant checks and mov…

f3c6ce8

…e write-only check to WriteProperty

yotsuda added 5 commits January 5, 2026 21:23

Refactor to share warning state between PSJsonPSObjectConverter and f…

9c63357

…actory

Handle extended/adapted properties in WriteDepthExceeded like V1

92f28b8

Add ETS property support for arrays and test for array with ETS seria…

d2e296f

…lization

Refactor to pass ConvertToJsonCommandV2 to converters instead of fact…

cc0b10a

…ory state

Remove custom cache for IsStjNativeScalarType, rely on STJ internal c…

87e8cba

…aching

iSazonov added the CL-General Indicates that a PR should be marked as a general cmdlet change in the Change Log label Jan 5, 2026

iSazonov reviewed Jan 5, 2026

View reviewed changes

yotsuda added 6 commits January 6, 2026 07:19

Fix CI test failures for ETS on scalar types, Int64 enum, and char 12…

8efb723

…7 serialization

Refactor PSJsonPSObjectConverter to accept cmdlet directly instead of…

4c5e3ff

… factory

Remove nullable annotation from cmdlet parameter as it is never null

9774f06

Exclude System.Object from scalar type check as it serializes to empt…

3b37433

…y object

Improve comment for BigInteger scalar type check

6ac53b8

Add XML doc comment explaining ShouldSkipProperty scope for script-de…

e969de9

…fined classes

yotsuda added 2 commits January 6, 2026 10:27

Add tests for depth exceeded behavior with PSObject ETS properties

eeea80a

Fix DateTime ETS test to use UTC and add missing Add-Member

f6ff545

yotsuda mentioned this pull request Jan 6, 2026

Add PSJsonSerializerV2 experimental feature for ConvertTo-Json using System.Text.Json #26637

Closed

7 tasks

Fix WriteProperty to preserve ETS properties on PSObject at depth exc…

67a1bbd

…eeded

iSazonov reviewed Jan 6, 2026

View reviewed changes

test/powershell/Modules/Microsoft.PowerShell.Utility/Json.Tests.ps1 Outdated Show resolved Hide resolved

yotsuda mentioned this pull request Jan 6, 2026

Add compatibility tests for ConvertTo-Json #26639

Open

6 tasks

yotsuda and others added 4 commits January 6, 2026 16:45

Update src/Microsoft.PowerShell.Commands.Utility/commands/utility/Web…

58a8bfa

…Cmdlet/ConvertToJsonCommandV2.cs Co-authored-by: Ilya <darpa@yandex.ru>

Address review comments: improve comments and fix exception handling

046d1fc

Fix scalar ETS handling to match V1 behavior

e4365e0

Refactor converters to reference cmdlet directly instead of factory

43ac7af

iSazonov reviewed Jan 6, 2026

View reviewed changes

Refactor ETS property handling using Count pattern and fix null fallb…

e341a12

…ack in WriteProperty

yotsuda requested a review from a team as a code owner January 7, 2026 01:59

Add PSJsonSerializerV2 for ConvertTo-Json using TruncatingConverterFactory #26654

Are you sure you want to change the base?

Add PSJsonSerializerV2 for ConvertTo-Json using TruncatingConverterFactory #26654

Conversation

yotsuda commented Jan 3, 2026

PR Summary

PR Context

Background

Solution

Architecture Benefits

Key Differences from PR #26637

PR Checklist

Changes Made

Modified Files

ConvertToJsonCommandV2.cs

ConvertTo-Json.PSJsonSerializerV2.Tests.ps1

Testing

Existing Tests (ConvertTo-Json.Tests.ps1)

V2 Specific Tests (ConvertTo-Json.PSJsonSerializerV2.Tests.ps1)

Related Work

Branch Structure

Uh oh!

iSazonov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iSazonov commented Jan 4, 2026

Uh oh!

yotsuda commented Jan 4, 2026 • edited by unfurl-links bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iSazonov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iSazonov Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iSazonov commented Jan 5, 2026

Uh oh!

iSazonov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

iSazonov Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iSazonov Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

yotsuda commented Jan 6, 2026

Uh oh!

iSazonov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

iSazonov Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`ConvertToJsonCommandV2.cs`

`ConvertTo-Json.PSJsonSerializerV2.Tests.ps1`

yotsuda commented Jan 4, 2026 •

edited by unfurl-links bot

Loading