Assessment: `netstandard2.0` support for Cysharp/ToonEncoder

Executive summary

Recommendation: accept the direction of issue #5, but implement it as multi-targeting:

<TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>

rather than changing the library exclusively to netstandard2.0.

The compatibility work looks moderate rather than architectural.

The strongest argument in favor is that ToonEncoder's principal dependency, SerializerFoundation, already targets:

netstandard2.0
netstandard2.1
net9.0
net10.0

and already uses PolySharp conditionally for its .NET Standard builds.

ToonEncoder's own source-generator project also already targets netstandard2.0, uses C# 14, and references PolySharp.

So adopting the same approach in the runtime library would be consistent with the existing Cysharp codebase rather than introducing a new compatibility strategy.

Estimated feasibility: high.

Suggested implementation: netstandard2.0;net10.0, PolySharp only on netstandard2.0, plus a small number of compatibility paths for newer BCL APIs.

1. Current state

Issue #5 asks whether ToonEncoder can target netstandard2.0 instead of requiring .NET 10, primarily to increase adoption.

Currently the runtime project contains:

<TargetFramework>net10.0</TargetFramework>

with dependencies on:

<PackageReference Include="SerializerFoundation" Version="0.2.1" />
<PackageReference Include="System.IO.Hashing" Version="10.0.1" />

The README consequently advertises .NET 10 as the minimum runtime requirement.

This minimum is therefore mostly a consequence of the ToonEncoder project target and its use of modern runtime APIs, rather than a fundamental limitation of its serialization foundation.

2. Dependency compatibility

SerializerFoundation

This is the most significant positive finding.

SerializerFoundation, which supplies ToonEncoder's IWriteBuffer infrastructure, already targets:

<TargetFrameworks>
  netstandard2.0;
  netstandard2.1;
  net9.0;
  net10.0
</TargetFrameworks>

For its .NET Standard targets it adds:

System.IO.Pipelines
System.Runtime.CompilerServices.Unsafe
PolySharp

and adds Microsoft.Bcl.AsyncInterfaces specifically for netstandard2.0.

That means one of the usual blockers in a backport — the foundational dependency only supporting a modern runtime — does not exist here.

It also provides a proven compatibility configuration that ToonEncoder could largely imitate.

System.IO.Hashing

This dependency is not a blocker either.

System.IO.Hashing 10.0.1 ships a real netstandard2.0 target in addition to modern .NET targets. Its .NET Standard implementation pulls in System.Buffers and System.Memory.

Therefore ToonEncoder can retain this dependency while targeting .NET Standard.

System.Text.Json

ToonEncoder uses JsonElement, JsonSerializer, JsonSerializerOptions, etc. Under .NET 10 these APIs come from the shared framework, so there is currently no explicit package reference.

For netstandard2.0, ToonEncoder would need an explicit System.Text.Json package reference.

The .NET 10 System.Text.Json package itself ships a netstandard2.0 implementation, so this is supported rather than a workaround.

Its compatibility dependency chain includes packages such as:

Microsoft.Bcl.AsyncInterfaces
System.Buffers
System.IO.Pipelines
System.Memory
System.Runtime.CompilerServices.Unsafe
System.Text.Encodings.Web
System.Threading.Tasks.Extensions

This increases the NuGet dependency graph for legacy consumers, but it is conventional for a netstandard2.0 library using modern System.Text.Json.

3. PolySharp

PolySharp is appropriate here, but it should be understood as a compiler compatibility tool rather than a BCL compatibility layer.

The repository already uses exactly this model in ToonEncoder.Generator:

<TargetFramework>netstandard2.0</TargetFramework>
<LangVersion>14</LangVersion>
...
<PackageReference Include="PolySharp" Version="1.15.0">
    <PrivateAssets>all</PrivateAssets>
    ...
</PackageReference>

SerializerFoundation does essentially the same thing for its netstandard2.0 and netstandard2.1 builds.

I would therefore use PolySharp for ToonEncoder's netstandard2.0 target as well.

A good pattern would be:

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
  <LangVersion>14</LangVersion>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
  <PackageReference Include="PolySharp" Version="1.15.0" PrivateAssets="all" />
  <PackageReference Include="System.Text.Json" Version="10.0.11" />
</ItemGroup>

The exact System.Text.Json version should ideally be managed consistently with the rest of the repository.

PolySharp should remain PrivateAssets="all" because consumers do not need to know that ToonEncoder used it while compiling.

4. Actual source compatibility work

Changing the TFM and adding PolySharp will not by itself make the runtime project compile.

The important distinction is:

modern C# syntax/compiler attributes → PolySharp can often solve these;
modern BCL APIs → need packages, conditional compilation, or equivalent implementations.

The current ToonWriter provides concrete examples.

`SearchValues<T>`

ToonEncoder currently creates a number of cached SearchValues<char> and SearchValues<byte> instances and uses span APIs such as ContainsAny and IndexOfAny against those search sets.

This is performance-oriented modern BCL functionality.

It is likely the most visible source-level obstacle to simply retargeting the project.

PolySharp does not exist to recreate an optimized runtime type such as SearchValues<T>.

The best approach is therefore conditional optimization:

#if NET8_0_OR_GREATER
    // SearchValues<T> optimized implementation
#else
    // small compatibility implementation using Span.IndexOfAny /
    // explicit character checks
#endif

This preserves the optimized modern implementation for .NET 10 while giving netstandard2.0 a functionally equivalent fallback.

Given how small these character sets are, a compatibility implementation need not be complicated.

Most importantly, the slower compatibility path would apply only to legacy targets; there is no reason to regress the .NET 10 implementation.

`double.IsFinite`

The writer currently performs:

if (!double.IsFinite(value))
{
    ...
}

For the compatibility target this can trivially become an internal helper such as:

static bool IsFinite(double value)
{
#if NETSTANDARD2_0
    return !double.IsNaN(value) && !double.IsInfinity(value);
#else
    return double.IsFinite(value);
#endif
}

This has negligible maintenance cost.

Spans, buffers and UTF-8 formatting

A lot of ToonEncoder is intentionally span-oriented:

ReadOnlySpan<T>
Span<T>
IBufferWriter<byte>
Utf8Formatter
Utf8Parser
unsafe/ref-based operations

At first glance this looks hostile to .NET Standard 2.0, but it is not necessarily so. The relevant compatibility packages (System.Memory, System.Buffers, Unsafe, etc.) are already a normal part of the .NET Standard compatibility ecosystem, and several are already pulled transitively by System.Text.Json/System.IO.Hashing/SerializerFoundation.

In other words, the implementation does not need to be rewritten into old-style arrays and strings.

That would destroy one of the library's principal performance characteristics and is unnecessary.

5. Do not downgrade the entire implementation

The biggest mistake would be turning:

net10.0

into only:

netstandard2.0

and then rewriting everything according to the lowest common denominator.

That would sacrifice useful JIT/runtime optimizations and make it harder to exploit newer APIs in the future.

Instead, retain:

net10.0

as the optimized primary implementation and expose:

netstandard2.0

as a compatibility target.

Conceptually:

                    ToonEncoder
                        |
            +-----------+-----------+
            |                       |
       netstandard2.0             net10.0
       compatibility             optimized
            |                       |
       PolySharp                 modern BCL
       STJ package               SearchValues
       compatibility helpers     latest runtime

This keeps the cost of broad compatibility isolated.

6. Why `netstandard2.0`, rather than `netstandard2.1`

If broad adoption is genuinely the goal, netstandard2.0 is materially more useful.

It enables consumption by a much broader range of:

older .NET applications;
.NET Framework applications;
Unity environments;
other runtimes implementing .NET Standard 2.0.

A netstandard2.1 target is easier technically but excludes .NET Framework completely and therefore captures substantially less of the compatibility benefit.

Because SerializerFoundation has already done the work for netstandard2.0, there is also less reason for ToonEncoder to stop at 2.1.

7. Package structure I would recommend

Something approximately like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
    <LangVersion>14</LangVersion>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>Cysharp.AI</RootNamespace>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="SerializerFoundation" Version="0.2.1" />
    <PackageReference Include="System.IO.Hashing" Version="10.0.1" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="System.Text.Json" Version="10.0.11" />

    <PackageReference Include="PolySharp" Version="1.15.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>
        runtime; build; native; contentfiles; analyzers; buildtransitive
      </IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>

There may be one or two additional explicit compatibility dependencies after an actual test build, but most should arrive through SerializerFoundation and System.Text.Json.

8. Testing requirements

I would not consider the feature complete merely because dotnet build succeeds.

CI should run the same behavioral fixtures against both target families.

At minimum:

net10.0
netstandard2.0 compatibility consumer

A useful compatibility consumer test would be an actual application targeting something that consumes netstandard2.0, rather than only compiling the library itself.

Important areas:

UTF-8 and UTF-16 quoting/escaping.
Comma, pipe and tab delimiters.
Floating-point NaN and infinities.
JsonElement conversion.
object -> System.Text.Json -> TOON path.
source-generated tabular converters.
async stream writing.
enums, GUIDs and date/time formatting.
nullability/nullable values.
package installation without dependency conflicts.

Because some compatibility code will replace performance APIs such as SearchValues<T>, the existing TOON fixtures are especially valuable: both implementations should produce byte-identical output.

9. Performance considerations

There should be a deliberate distinction between:

semantic compatibility and performance parity.

I would promise semantic compatibility on netstandard2.0, but not identical throughput.

The .NET 10 target should continue using modern optimized APIs.

The netstandard2.0 target can use slightly less sophisticated search/formatting helpers where required.

This is a reasonable trade:

net10.0       → best possible performance
netstandard2.0 → broad compatibility, still allocation-conscious

Trying to achieve identical low-level performance on legacy runtimes would make this feature unnecessarily expensive.

10. Maintenance cost

I would rate the ongoing cost as low to moderate provided compatibility logic is centralized.

Avoid sprinkling:

#if NETSTANDARD2_0

through every serializer method.

Instead introduce very small compatibility abstractions, for example:

Internal/
    Compatibility/
        SearchValuesCompat.cs
        DoubleCompat.cs

Then most encoder code remains identical for both TFMs.

That also makes deletion easy if netstandard2.0 is eventually dropped.

11. Adoption impact

Issue #5's claim that broader targeting would increase adoption is credible.

Right now installation requires .NET 10 even though ToonEncoder's public purpose — JSON/TOON conversion and buffer writing — is not intrinsically a .NET-10-only operation.

Supporting netstandard2.0 would notably open the library to environments where upgrading the application's runtime is not practical.

This is particularly relevant for a serialization/data-format package: these are typically most useful when they can sit low in a dependency graph rather than dictate the application's runtime version.

12. Risks

The main risks are manageable:

Area	Risk	Assessment
SerializerFoundation	Dependency incompatible	Low — already supports netstandard2.0
System.IO.Hashing	Dependency incompatible	Low — official netstandard2.0 asset exists
System.Text.Json	Missing from framework	Low — official package supports netstandard2.0
C# 14 syntax/features	Compiler compatibility	Low — PolySharp pattern already used
Modern BCL APIs	Missing APIs	Medium — requires compatibility implementations
Performance	Legacy target slower	Expected/acceptable
NuGet graph	More dependencies	Moderate but conventional
CI complexity	Multiple targets	Low
Long-term maintenance	Conditional code	Low if centralized

13. Recommendation

I would accept issue #5 in principle.

I would phrase the implementation goal as:

Add netstandard2.0 as a compatibility target while retaining net10.0 as the optimized target.

The existing architecture is unusually favorable to doing this because:

SerializerFoundation already supports netstandard2.0.
SerializerFoundation already demonstrates the desired PolySharp strategy.
ToonEncoder's generator already uses netstandard2.0 + C# 14 + PolySharp.
System.IO.Hashing already supports netstandard2.0.
System.Text.Json provides an official netstandard2.0 package.
The visible incompatibilities in ToonEncoder itself are primarily localized modern-BCL optimizations rather than architectural dependencies on .NET 10.

So I would classify this as worth implementing and probably smaller than the current .NET 10 requirement initially suggests.

Proposed decision

Status: Recommended.

Target:

netstandard2.0;net10.0

Compatibility strategy:

PolySharp
+ official System.* compatibility packages
+ narrowly scoped fallbacks for modern BCL APIs

Do not:

replace net10.0 entirely
rewrite span/buffer architecture
force modern code down to the lowest-common-denominator implementation

Expected result: significantly broader consumer compatibility with little impact on the high-performance .NET 10 path.

Assessment: netstandard2.0 support for Cysharp/ToonEncoder

Uh oh!

netstandard2.0 compat #5

Description

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions