IDocumentSerializer Interface

Definition

Namespace:Avalonia.Controls.Documents.Serialization

Assembly:Avalonia.Controls.Documents

Package:Avalonia.Controls.Documents

Interface for document format serializers.

public interface IDocumentSerializer

Remarks

Implementations should be thread-safe for concurrent serialization operations. Serialization uses Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot so it can run away from the UI thread.

The contract is synchronous. Every format here is processor-bound - tokenizing, tree building, text layout - and assembles its output in memory rather than streaming it, so none of them performs asynchronous I/O. An asynchronous pair would only occupy a pool thread for the duration of synchronous work while looking like it released one. A caller that wants the cost off its own thread wraps the call:

// Capture on the UI thread, write off it
var snapshot = document.CreateSnapshot();
await Task.Run(() => serializer.Serialize(snapshot, stream));

A format that supports only one direction throws NotSupportedException from the other one and reports it through Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanRead / Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanWrite.

Methods

Name	Description
CanDeserialize	Checks if a stream appears to contain this format.
Deserialize	Deserializes a document from a stream on the calling thread.
DeserializeAsync	Deserializes a document from a stream off the calling thread.
Serialize	Serializes a document snapshot to a stream on the calling thread.
SerializeAsync	Serializes a document snapshot to a stream off the calling thread.

CanDeserialize Method

Checks if a stream appears to contain this format.

public bool CanDeserialize(System.IO.Stream stream)

Parameters

stream System.IO.Stream

The stream to check. Must be readable and seekable.

Returns

bool

True if the stream likely contains this format; otherwise, false.

Remarks

This method does not consume the stream; it restores the original position after checking.

Deserialize Method

Deserializes a document from a stream on the calling thread.

public Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot Deserialize(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

stream System.IO.Stream

The stream to read from. Must be readable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The deserialized Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot.

Remarks

Defaults to blocking on Avalonia.Controls.Documents.Serialization.IDocumentSerializer.DeserializeAsync(System.IO.Stream,System.Threading.CancellationToken), so a serializer written against the released interface keeps working. Implement this member instead: no format here performs asynchronous I/O, so the asynchronous pair only moves processor-bound work onto a pool thread.

Exceptions

• `stream` is null.
• `stream` is not readable.
• This serializer cannot read; see [Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanRead](xref:Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanRead).
• The stream content is invalid for this format.

DeserializeAsync Method

Deserializes a document from a stream off the calling thread.

public System.Threading.Tasks.Task<Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot> DeserializeAsync(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

stream System.IO.Stream

The stream to read from. Must be readable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

System.Threading.Tasks.Task<Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot>

The deserialized Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot.

Remarks

A thread-offload convenience rather than asynchronous I/O: no format here reads asynchronously, so this wraps the synchronous work. Call Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken) directly when you are already off the UI thread.

Serialize Method

Serializes a document snapshot to a stream on the calling thread.

public void Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot snapshot, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

snapshot Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The document snapshot to serialize.

stream System.IO.Stream

The stream to write to. Must be writable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Remarks

Defaults to blocking on Avalonia.Controls.Documents.Serialization.IDocumentSerializer.SerializeAsync(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot,System.IO.Stream,System.Threading.CancellationToken), so a serializer written against the released interface keeps working. Implement this member instead.

Exceptions

• `snapshot` or `stream` is null.
• `stream` is not writable.
• This serializer cannot write; see [Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanWrite](xref:Avalonia.Controls.Documents.Serialization.IDocumentSerializer.CanWrite).

SerializeAsync Method

Serializes a document snapshot to a stream off the calling thread.

public System.Threading.Tasks.Task SerializeAsync(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot snapshot, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken)

Parameters

snapshot Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot

The document snapshot to serialize.

stream System.IO.Stream

The stream to write to. Must be writable.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

System.Threading.Tasks.Task

Remarks

A thread-offload convenience rather than asynchronous I/O. Call Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Serialize(Avalonia.Controls.Documents.Serialization.Snapshot.DocumentSnapshot,System.IO.Stream,System.Threading.CancellationToken) directly when you are already off the UI thread.

Properties

Name	Description
CanRead	Whether this serializer supports reading. Read-only UIs can filter serializer lists on this instead of catching NotSupportedException from Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken).
CanWrite	Whether this serializer supports writing documents.
FileExtension	Gets the file extension including the dot (e.g., ".rtf").
FormatName	Gets the format name this serializer handles (e.g., "Rtf", "Docx", "PlainText").
MimeType	Gets the MIME type for the format (e.g., "application/rtf").

CanRead Property

Whether this serializer supports reading. Read-only UIs can filter serializer lists on this instead of catching NotSupportedException from Avalonia.Controls.Documents.Serialization.IDocumentSerializer.Deserialize(System.IO.Stream,System.Threading.CancellationToken).

public bool CanRead { get; set; }

Remarks

Defaults to so a serializer written before this member existed still compiles. A serializer that cannot read says so.

CanWrite Property

Whether this serializer supports writing documents.

public bool CanWrite { get; set; }

Remarks

Defaults to so a serializer written before this member existed still compiles. A serializer that cannot write says so.

FileExtension Property

Gets the file extension including the dot (e.g., ".rtf").

public string FileExtension { get; set; }

FormatName Property

Gets the format name this serializer handles (e.g., "Rtf", "Docx", "PlainText").

public string FormatName { get; set; }

MimeType Property

Gets the MIME type for the format (e.g., "application/rtf").

public string MimeType { get; set; }