Class XpingJsonSerializer

Namespace

Xping.Sdk.Core.Serialization

Assembly

Xping.Sdk.Core.dll

Provides JSON serialization and deserialization services for the Xping SDK using System.Text.Json. This class implements the IXpingSerializer interface and provides consistent serialization behavior across all components of the SDK.

public sealed class XpingJsonSerializer : IXpingSerializer

Inheritance

object

XpingJsonSerializer

Implements

IXpingSerializer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This serializer is thread-safe and can be used as a singleton. It uses the standard Xping serialization options defined in XpingSerializerOptions.

Constructors

XpingJsonSerializer()

Initializes a new instance of the XpingJsonSerializer class with API options.

public XpingJsonSerializer()

XpingJsonSerializer(JsonSerializerOptions)

Initializes a new instance of the XpingJsonSerializer class with custom options.

public XpingJsonSerializer(JsonSerializerOptions options)

Parameters

options JsonSerializerOptions

The JSON serialization options to use.

Exceptions

ArgumentNullException

Thrown when options is null.

Methods

DeserializeAsync<T>(Stream, CancellationToken)

Asynchronously deserializes a stream containing JSON to an object of the specified type. This method is useful for deserializing large objects or when working with streams.

public Task<T?> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream containing the JSON to deserialize.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task<T>

A task representing the asynchronous operation, containing the deserialized object or null.

Type Parameters

T

The type to deserialize to.

Remarks

The stream is NOT disposed by this method. The caller retains ownership of the stream and is responsible for disposing it. The stream position is advanced as data is read. The stream remains open after deserialization completes.

Exceptions

ArgumentNullException

Thrown when stream is null.

JsonException

Thrown when the JSON is invalid or cannot be converted to the target type.

Deserialize<T>(ReadOnlySpan<byte>)

Deserializes a UTF-8 encoded JSON byte array to an object of the specified type.

public T? Deserialize<T>(ReadOnlySpan<byte> utf8Json)

Parameters

utf8Json ReadOnlySpan<byte>

The UTF-8 encoded JSON byte array to deserialize.

Returns

T

The deserialized object, or null if the JSON represents a null value.

Type Parameters

T

The type to deserialize to.

Exceptions

JsonException

Thrown when the JSON is invalid or cannot be converted to the target type.

Deserialize<T>(string)

Deserializes a JSON string to an object of the specified type.

public T? Deserialize<T>(string json)

Parameters

json string

The JSON string to deserialize.

Returns

T

The deserialized object, or null if the JSON represents a null value.

Type Parameters

T

The type to deserialize to.

Exceptions

ArgumentNullException

Thrown when json is null.

JsonException

Thrown when the JSON is invalid or cannot be converted to the target type.

SerializeAsync<T>(Stream, T, CancellationToken)

Asynchronously serializes an object to a stream in JSON format. This method is useful for serializing large objects or when working with streams.

public Task SerializeAsync<T>(Stream stream, T value, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to write the JSON to.

value T

The object to serialize.

cancellationToken CancellationToken

A cancellation token to observe while waiting for the task to complete.

Returns

Task

A task representing the asynchronous operation.

Type Parameters

T

The type of the object to serialize.

Remarks

The stream is NOT disposed by this method. The caller retains ownership of the stream and is responsible for disposing it. The stream position is advanced to the end of the written content, and the stream is flushed to ensure all data is written.

Exceptions

ArgumentNullException

Thrown when stream or value is null.

SerializeToUtf8Bytes<T>(T)

Serializes an object to a UTF-8 encoded byte array.

public byte[] SerializeToUtf8Bytes<T>(T value)

Parameters

value T

The object to serialize.

Returns

byte[]

A UTF-8 encoded byte array containing the JSON representation.

Type Parameters

T

The type of the object to serialize.

Exceptions

ArgumentNullException

Thrown when value is null.

Serialize<T>(T)

Serializes an object to a JSON string.

public string Serialize<T>(T value)

Parameters

value T

The object to serialize.

Returns

string

A JSON string representation of the object.

Type Parameters

T

The type of the object to serialize.

Exceptions

ArgumentNullException

Thrown when value is null.