CrystalXml

Namespace: SnowBank.Data.Xml · class

Sink plumbing for ICrystalXmlSerializer: the eight output entry points

Remarks

Every method here owns the whole sink lifecycle: it constructs the destination buffer, constructs the emitter over it, calls WriteXml, and reads the result back through the emitter's own Writer, never through the caller's writer variable (the emitter copies the writer struct by value: see the remarks on CrystalXmlWriter). Keeping that dance inside these helpers means nobody outside this file has to know the rule exists.

ToText and ToSlice/ToBytes go through the byte-exact CrystalXmlWriter. ToXDocument and the XmlWriter overload of WriteTo go through the infoset emitters instead, and only guarantee infoset equivalence, not a byte-exact output.

Methods

ToBytes

static byte[] ToBytes<T>(ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes value to a Byte array of XML

• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

static byte[] ToBytes<T>(ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null, Encoding encoding = null)

Serializes a sequence of items to a Slice of XML, as a single collection root element

• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

ToSlice

static Slice ToSlice<T>(ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes value to a Slice of XML

• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

static Slice ToSlice<T>(ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null, Encoding encoding = null)

Serializes a sequence of items to a Slice of XML, as a single collection root element

• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

ToText

static string ToText<T>(ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes value to a String of XML text

• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element

static string ToText<T>(ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null)

Serializes a sequence of items to a String of XML text, as a single collection root element

• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name

ToXDocument

static XDocument ToXDocument<T>(ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes value to an in-memory XDocument

• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element

Only infoset equivalence with the byte-exact output is guaranteed here, not a byte-exact document: see the remarks on .

static XDocument ToXDocument<T>(ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null)

Serializes a sequence of items to a String of XML text, as a single collection root element

• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name

WriteTo

static void WriteTo<T>(TextWriter destination, ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes value as XML text into destination

• destination — Destination writer; ownership stays with the caller, who is responsible for flushing and disposing it
• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element

Writes through a pooled Char buffer (TextWriterBufferProxy), draining to destination via Write whenever the buffer would need to grow.

Same failure-path contract as WriteTo: on failure the pooled buffer is always returned, the un-drained tail is not written, and the caller sees the original exception; either way destination is never closed or disposed.

static void WriteTo<T>(IBufferWriter<byte> destination, ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes value as UTF-8 encoded XML into destination

• destination — Destination buffer writer
• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element

is an interface, so it cannot itself satisfy the struct constraint on TWriter; see the remarks on . This overload owns no pooled resource of its own, so on failure whatever already wrote through simply stays there.

static void WriteTo<T>(XmlWriter destination, ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes value into destination

• destination — Destination writer, not owned: the caller flushes and disposes it, and configures its XmlWriterSettings
• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element

Only infoset equivalence with the byte-exact output is guaranteed here: the concrete bytes depend on how was configured. See the remarks on .

static void WriteTo<T>(Stream destination, ICrystalXmlSerializer<T> serializer, T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes value as UTF-8 encoded XML into destination

• destination — Destination stream; ownership stays with the caller, who is responsible for flushing and disposing it
• serializer — Serializer that knows how to write a T
• value — Value to serialize, or null to write the empty/self-closing root element
• settings — Optional settings passed through to serializer
• rootName — Optional override for the name of the root element
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

Writes synchronously through a pooled Byte buffer (StreamBufferProxy), draining to destination via Write whenever the buffer would need to grow. Deliberately not a PipeWriter: this method is synchronous, and blocking on StreamPipeWriter.FlushAsync() is not a supported use of the IValueTaskSource-backed ValueTask a FileStream or NetworkStream returns.

Failure-path contract. If serializer throws, the pooled buffer is always returned to Shared, the still-buffered tail is not written to destination (chunks already pushed out by an earlier growth-triggered drain stay written), and the caller always sees the original exception, never a cleanup failure. This method never closes, disposes, or otherwise completes destination: ownership stays with the caller for the whole call. A non-default encoding takes the simpler ToSlice path instead, building the whole buffer before writing it out in one call, so nothing reaches destination at all if serializer throws.

static void WriteTo<T>(TextWriter destination, ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null)

Serializes a sequence of items as XML text into destination, as a single collection root element

• destination — Destination writer; ownership stays with the caller, who is responsible for flushing and disposing it
• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name

Same buffering and failure-path contract as .

static void WriteTo<T>(IBufferWriter<byte> destination, ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null)

Serializes a sequence of items as UTF-8 encoded XML into destination, as a single collection root element

• destination — Destination buffer writer
• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name

Same ownership contract as : this overload owns no pooled resource of its own.

static void WriteTo<T>(XmlWriter destination, ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null)

Serializes a sequence of items into destination, as a single collection root element

• destination — Destination writer, not owned: the caller flushes and disposes it, and configures its XmlWriterSettings
• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name

Only infoset equivalence with the byte-exact output is guaranteed here: see the remarks on .

static void WriteTo<T>(Stream destination, ICrystalXmlElementSerializer<T> itemSerializer, IEnumerable<T> items, CrystalXmlSettings? settings = null, string rootName = null, string itemName = null, Encoding encoding = null)

Serializes a sequence of items as XML into destination, as a single collection root element

• destination — Destination stream; ownership stays with the caller, who is responsible for flushing and disposing it
• itemSerializer — Serializer of the item type, which names the item elements and, on the DataContract profile, the root
• items — Items to serialize, or null for the empty root element, marked nil when the item serializer's profile marks nulls
• settings — Optional settings passed through to itemSerializer
• rootName — Optional name for the root element, in place of the profile's ArrayOfX convention; required on the General profile, which has no convention
• itemName — Optional name for the item elements, in place of the item type's own element name
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

Same buffering and failure-path contract as . A non-default takes the simpler path instead, building the whole buffer before writing it out in one call.

Fields

MaxDepth

const int MaxDepth

Maximum nesting depth a generated XML emission may reach before it raises CrystalXmlCycleException

Locked to MaxDepth, which documents the depth/cycle guard shared by both formats: a document must not serialize on one and be rejected by the other over where "too deep" starts.

The counter only tracks generated recursion: it resets to zero across a call into WriteXml (a custom member converter) or WriteXml (a self-writing type), so a cycle running through such a hook is not covered and still overflows the native stack. The measured overflow point of the generated recursion is around 2300 nested WriteXmlElement frames (one frame per level).