CrystalXmlWriterEmitter

Namespace: SnowBank.Data.Xml · struct

XML infoset emitter that forwards events straight into a XmlWriter

Remarks

The other infoset sink for ICrystalXmlEmitter (the DOM-building one is CrystalXDocumentEmitter). Every event is a direct passthrough to the wrapped XmlWriter, which already implements the XML infoset (attribute ordering, escaping, self-closing). Only infoset equivalence is guaranteed, not a byte-exact format: the concrete bytes depend entirely on the XmlWriterSettings the caller configured.

The attribute-ordering precondition from ICrystalXmlEmitter is already enforced by the wrapped writer, which throws on a misordered WriteAttributeString; this type adds no redundant check.

WriteRawAscii routes through WriteString, not WriteRaw. Measured: WriteRaw(string.Empty) writes nothing and lets the element self-close, dropping the "even empty content counts" rule of WriteRawAscii, whereas WriteString(string.Empty) forces the expanded form. Pre-validated ASCII never contains a character the escaper treats specially, so the output is identical for every non-empty value.

Also measured against the BCL: the wrapped writer already applies XML 1.0 section 2.11 end-of-line normalization on write and already entitizes TAB/LF/CR inside attribute values, so neither needs any help from this type.

The format core's control-character sanitization does NOT apply here. The characters XML 1.0 cannot represent (C0 controls, unpaired surrogate halves, U+FFFE/U+FFFF) reach the wrapped writer unchanged, which answers for them under its own CheckCharacters (throws by default); content that may carry them must be sanitized before it reaches the emitter.

Namespace declarations and prefixes belong to the wrapped writer. It tracks what is in scope, invents the aliases, and places the declarations where its own rules put them, which is what it does for every caller. So WriteNamespaceDeclaration and WriteDefaultNamespaceDeclaration do nothing here: a declaration is a statement about the bytes, and the bytes are not this type's to decide. What does reach the output is every namespace a name carries, so the expanded names of the document are exactly the ones that were written.

This type owns none of the writer's lifetime: the caller flushes and disposes it. Like every ICrystalXmlEmitter, it must still be passed by ref per the interface remarks.

Constructors

CrystalXmlWriterEmitter

CrystalXmlWriterEmitter(XmlWriter writer)

Wraps an existing XmlWriter

writer — Destination writer. Not owned: the caller flushes and disposes it, and configures its XmlWriterSettings (indentation, encoding, conformance level, ...).

Properties

Writer

XmlWriter Writer { get; }

Destination writer that every event is forwarded to, unowned by this emitter

Methods

WriteAttribute

void WriteAttribute(in CrystalXmlName name, ReadOnlySpan<char> value)

Appends an attribute to the start tag that is currently open

name — Name of the attribute, in both its text and UTF-8 representations
value — Value of the attribute, escaped by the implementation

Only valid between a and the first content event or of that element.

void WriteAttribute(in CrystalXmlName name, in CrystalXmlNamespace ns, ReadOnlySpan<char> value)

Appends an attribute in an explicit namespace to the start tag that is currently open

name — Local name of the attribute, in both its text and UTF-8 representations
ns — Namespace of the attribute, which takes precedence over the one name carries
value — Value of the attribute, escaped by the implementation

An attribute is never in the default namespace: a namespaced attribute always takes a prefix, which is why this overload and the one above are not the same call with an empty namespace.

WriteDefaultNamespaceDeclaration

void WriteDefaultNamespaceDeclaration(in CrystalXmlNamespace ns)

Declares a namespace as the DEFAULT namespace on the start tag that is currently open

ns — Namespace to declare, or the empty namespace to cancel an inherited default

The default namespace covers the ELEMENTS of the open element's subtree, never their attributes. An element whose own namespace is the default therefore needs no prefix, which is what makes a document readable.

It does not change the namespace of the element that carries it. An element gets its namespace when it is opened, and nothing afterwards moves it. So an element that is itself in the namespace it declares says so at WriteStartElement, which also declares it when nothing in scope binds it. The text emitter would produce the same bytes either way, but the infoset implementations have committed the name by then, and a call that means one thing on one sink and another on the next is worth no bytes.

WriteEndElement

void WriteEndElement(in CrystalXmlName name)

Closes the element that is currently open

name — Name of the element being closed, in both its text and UTF-8 representations

The name is passed back by the caller (the generated code always knows it statically) so that implementations do not have to allocate a stack of names.

WriteNamespaceDeclaration

void WriteNamespaceDeclaration(in CrystalXmlNamespace ns)

Declares a namespace on the start tag that is currently open, under a prefix the implementation picks

ns — Namespace to declare

The declaration covers the open element and everything inside it, so this is how a caller places one declaration above several uses instead of letting each use declare its own. A collection wrapper naming its items' namespace, or an element whose nested contract lives in another namespace than its own name, are the two shapes that need it: without them each child declares the same namespace again.

Asking for a namespace that is already in scope writes NOTHING. The call means "this namespace is usable inside this element", and an inherited declaration already says so; binding a second alias to one namespace would only add bytes. So a caller can ask unconditionally, which is what lets one generated body serve both a root element (whose namespace its caller already declared) and a nested one (whose caller did not).

Only valid while the start tag is still open.

WriteQNameAttribute

void WriteQNameAttribute(in CrystalXmlName name, in CrystalXmlName value)

Appends an attribute in an explicit namespace whose VALUE is a qualified name

name — Local name of the attribute (type, on the DataContract format)
value — The qualified name the attribute carries: its local name, and the namespace it belongs to

Separate from because a qualified name is a namespace and a local name, not text: the implementation resolves the namespace to a prefix in scope and writes prefix:Local, so nothing formats a string to describe a name the implementation already holds.

void WriteQNameAttribute(in CrystalXmlName name, in CrystalXmlNamespace ns, in CrystalXmlName value)

Appends an attribute in an explicit namespace whose VALUE is a qualified name

name — Local name of the attribute (type, on the DataContract format)
ns — Namespace of the attribute, which takes precedence over the one name carries
value — The qualified name the attribute carries: its local name, and the namespace it belongs to

WriteRawAscii

void WriteRawAscii(ReadOnlySpan<char> ascii)

Appends content that is already known to be valid, unescaped ASCII

ascii — Pre-validated ASCII content: a formatted number, a date, a base64 payload, ...

This bypasses the escaper entirely, which is the point: these forms cannot contain a character that would need escaping. Passing arbitrary user text here would emit malformed XML.

Like WriteText, this counts as content.

void WriteRawAscii(string ascii)

Appends pre-validated ASCII content, treating null as "no content at all"

ascii — Pre-validated ASCII content. null writes nothing, leaving the element free to self-close; an empty string counts as content and forces the expanded form.

On the interface for the same reason as : an interface-constrained caller must get the same format as a caller holding the concrete struct.

WriteStartElement

void WriteStartElement(in CrystalXmlName name)

Opens a new element

name — Name of the element, in both its text and UTF-8 representations

The start tag stays open until content is written or the element is closed, so that can still append attributes to it.

void WriteStartElement(in CrystalXmlName name, in CrystalXmlNamespace ns)

Opens a new element in an explicit namespace

name — Local name of the element, in both its text and UTF-8 representations
ns — Namespace of the element, which takes precedence over the one name carries

This overload exists so that one cached name can be written in more than one namespace: the item name string is in the collections namespace under a List and in the XML Schema namespace as the value of a type annotation, and caching it twice would be caching the same three bytes twice.

WriteText

void WriteText(ReadOnlySpan<char> text)

Appends text content to the element that is currently open, escaping it as needed

text — Raw text; the implementation escapes it

Writing text always counts as content, so an empty span still forces the expanded form instead of the self-closing one.

void WriteText(string text)

Appends text content to the element that is currently open, treating null as "no content at all"

text — Raw text. null writes nothing, leaving the element free to self-close as <Name />; an empty string counts as content and forces the expanded <Name></Name> form.

This member is on the interface, and not merely an overload on the concrete emitters, because generated bodies only see interface members through the where TEmitter : struct, ICrystalXmlEmitter constraint. Were it absent, emitter.WriteText(someString) would bind through the implicit string conversion, turning a into an empty span and flipping the output from to .