DCoding.Xml.XInclude
1.0.1
dotnet add package DCoding.Xml.XInclude --version 1.0.1
NuGet\Install-Package DCoding.Xml.XInclude -Version 1.0.1
<PackageReference Include="DCoding.Xml.XInclude" Version="1.0.1" />
<PackageVersion Include="DCoding.Xml.XInclude" Version="1.0.1" />
<PackageReference Include="DCoding.Xml.XInclude" />
paket add DCoding.Xml.XInclude --version 1.0.1
#r "nuget: DCoding.Xml.XInclude, 1.0.1"
#:package DCoding.Xml.XInclude@1.0.1
#addin nuget:?package=DCoding.Xml.XInclude&version=1.0.1
#tool nuget:?package=DCoding.Xml.XInclude&version=1.0.1
DCoding.Xml.XInclude
V1.0 technical selection: Community, Professional. Declared assets/hosts: net8.0, net11.0. See the current edition and API/runtime catalog for mode and host limits. Selection and retained development results do not replace final artifact qualification, the supplied license or human release approval.
Optional, explicit XInclude preprocessing for immutable XDM documents. Reference this package and call
XIncludeProcessor.ProcessAsync(new XIncludeRequest(source, resources)) to compose a new document. Ordinary XML parsing,
XPath doc(), and compatibility entry points do not start inclusion processing. No resource can be acquired without the
caller-selected XmlHostResourceServices; omitted services deny every resource. Results contain no streams or host services.
Each included information item exposes XdmXmlNode.IncludeHistory: an immutable list of the original include elements,
ordered outermost first. Nested root replacement prepends the outer instruction; descendants retain the history of their
own inclusion boundaries. XML, text and fallback replacements participate. Preserving and stripping schema-copy modes
retain this XML Infoset extension. Adapter-owned LINQ annotations retain item and character-run boundaries; moving an
annotation to a different item is rejected. History consumes the existing finite source, output-node and work limits.
using DCoding.Xml.Xdm;
using DCoding.Xml.XInclude;
// source is an immutable XDM document; resolver is the caller's explicit host policy.
var resources = new XmlHostResourceServices(resourceResolver: resolver);
var result = await XIncludeProcessor.ProcessAsync(new XIncludeRequest(source, resources,
new XIncludeOptions(maximumResourceBytes: 1_048_576, maximumDepth: 64), cancellationToken));
This M38 surface implements whole-document parse="xml" replacement, nested XML inclusions, strict parse="text" decoding, detached identities,
bounded async host acquisition, cancellation, and structured errors. Host-supplied XDM documents and bounded XML 1.0 bytes
are accepted. Selecting XmlInputProfile.Xml11 on the six-argument request also permits XML 1.1 byte resources through the
shared bounded loader, including line-end normalization, restricted character references, modern names and namespace
undeclarations. Omitted profiles retain XML 1.0. Byte parsing prohibits DTDs by default. Explicit
new XIncludeOptions(allowInternalDtd: true) permits bounded internal declarations, defaults and entity expansion;
external DTD/entity acquisition remains denied. parse="xml" remains XML
parsing regardless of server media type; it never silently changes into text inclusion.
Source and acquired base-URI metadata, namespaces, attributes, comments, processing instructions, and child order are copied
without serializing or mutating source trees. Recursive inclusion is bounded and tracks the resolver's absolute identity plus
the exact XML-decoded pointer value within the current chain, together with active source include-node guards.
The accept and accept-language attributes are copied exactly into the immutable shared host request's RequestMetadata
under Accept and Accept-Language. Values outside U+0020 through U+007E are fatal before acquisition. These hints grant no
HTTP, filesystem, credential, or header authority; the caller's resolver chooses representations and redirects. Every
include is authorized and read under the cumulative budget, including repeated identities. XML snapshots are stable within
one operation and one resolved identity/negotiation combination; different negotiated representations and separate operations
retain independent snapshots. Reusing a snapshot never bypasses a later host denial. Included result nodes remain fresh copies.
Text acquisition uses the shared Text resource kind. Encoding selection follows external host EncodingName, then XML-media
byte signatures/declarations, then the encoding attribute, then UTF-8. XML media detection applies to text/xml,
application/xml, and text/*+xml / application/*+xml; it detects encoding without parsing the text as markup.
Supported encodings are UTF-8, generic and endian-specific UTF-16/UTF-32, ASCII, Latin-1, and IBM037 (also CP037,
IBM-037, EBCDIC-CP-US). IBM037 uses the explicitly selected built-in code-page provider; registered global providers
cannot replace it. An EBCDIC XML signature requires a supported explicit encoding declaration. Other encodings produce a
resource error; no ambient default is consulted. Generic UTF-16/UTF-32 uses a BOM to choose
byte order, defaulting to big endian when no BOM exists. Generic UTF names discard the first decoded BOM; explicit
UTF-16LE, UTF-16BE, UTF-32LE, and UTF-32BE retain a leading U+FEFF. XML signatures must agree with an XML encoding
declaration. Malformed byte sequences and forbidden XML characters are fatal InvalidText errors. Decoding counts characters
before allocating the result and checks cancellation between blocks. CR, CRLF, LF, NEL, LS, and literal markup are preserved.
A text reference to the including XML resource is legal and never starts recursive XML parsing.
The six-argument request overload accepts the shared XmlInputProfile before the final cancellation token. Existing overloads and
an omitted or null profile select XML 1.0. Explicit XmlInputProfile.Xml11 permits the XML 1.1 character range for text
inclusions, including control characters representable through character references in XML 1.1. NUL, isolated surrogates,
U+FFFE and U+FFFF remain fatal. The exact profile reaches each authorized host request and stays local to the operation;
it grants no resource access. The selected profile also controls the shared XML byte loader. Text line endings remain unchanged in both profiles.
Structural preflight validates every active instruction in each available document before fetching its first include.
It rejects invalid parse/href/xpointer combinations, malformed href percent escapes, all literal href fragments (including a trailing #), non-ASCII or
control characters in negotiation attributes, duplicate fallbacks, illegal direct XInclude children and misplaced fallbacks.
Other include content and unused fallback contents are ignored as specified. Active fallback structure is checked only on
a resource error; fatal structure is never recovered by a fallback. Document-element replacement requires exactly one
element surrounded only by comments and processing instructions.
XML subresource selection reuses the optional DCoding.Xml.XPointer Framework implementation. Shorthand IDs, element()
and ordered xmlns() context are supported without another parser or URI decoding. Unsupported parts are skipped in order;
no supported match, malformed Framework syntax, and unsupported xpointer() are resource errors. They never substitute
the whole document. A malformed complete pointer is rejected before acquisition.
Missing or empty href with an xpointer addresses the unchanged original document, even when xml:base appears external,
without resource acquisition. External XML is recursively composed into its acquired Infoset before subresource selection.
An explicit IXIncludePointerSelector overrides the built-in selection. It receives the appropriate unchanged source or
composed acquired Infoset and exact attribute value. Its nodes are checked for membership, legal item kinds, finite size
and source order before copying. Caller exceptions propagate. All intermediate composition consumes the operation budgets.
Different pointers may legally reenter a resource still being composed. Such selection uses the request-local stable original snapshot and recursively composes the selected fragment; an explicit selector receives that same original snapshot. Normal external selection receives the completed acquired Infoset. Repeated location/pointer pairs, self/ancestor instruction selection and actual multi-resource loops are fatal. Sibling repeats and text inclusion of active XML resources are legal. Every acquisition is authorized/read before snapshot reuse, including aliases and reentry; negotiation cannot bypass a repeated location/pointer guard. All chain guards unwind on exit, remain local to the operation, and grant no ambient access.
An engine resource error selects exactly one direct xi:fallback and recursively processes its children. The wrapper and its
instruction attributes are omitted; an empty fallback removes the include. Fallback children may contain XML markup or text
regardless of the failed request's parse mode. Dormant fallback content is ignored. Structural/XML/cycle failures, exhausted
limits, cancellation and trusted host/selector exceptions do not activate fallback. Failed acquisition and all recovery work
share the same cumulative budgets. A resource error without fallback is fatal, retaining its existing code, source node,
acquisition URI and denial reason, with the original recoverable resource exception as its inner cause. An outer fallback
cannot recover that already fatal nested error.
Top-level included elements retain their complete source namespace snapshots, including bindings used only in QName-valued
content. Conflicting receiver prefixes and default namespaces do not change expanded names. XML bytes, selected subresources,
fallback children and nested replacements preserve their original effective base URI and document identity. xml:base is
added or replaced with an absolute value at the inclusion boundary when needed; existing relative values are normalized so
they cannot be applied again against the receiving parent. Inherited xml:lang is retained with a boundary attribute when it
differs from the actual receiver, comparing case-insensitively; an empty value prevents receiver language from leaking into a
language-free included resource. xml:space remains ordinary data. Added/replaced attributes count against operation limits.
The source trees stay unchanged. Serializer round trips retain relative-resource resolution and language inheritance.
XDM exposes immutable DocumentInfo and AttributeInfo snapshots. DOM/reader projection retains DTD attribute types,
specified/defaulted state, original entity identifiers, declaration base URIs, notation identity and reference properties.
Internal parameter entities are expanded under finite metadata limits. When the platform hides external declarations,
IsDtdComplete is false; composition rejects that incomplete snapshot. The host may supply complete declarations explicitly
through the DOM or reader overload accepting XdmXmlDocumentInfo. These snapshots grant no resource authority.
Opaque navigators report incomplete declarations by default. FromXPathNavigatorWithInfoset accepts a request-local
metadata callback for each projected node; complete declarations and node properties are supplied explicitly, references
are rebuilt against fresh identities, and callback failures propagate. The callback is never retained.
XdmInfosetValueState distinguishes present values (including empty collections), no value and unknown knowledge.
This applies to attribute types and references, multiply declared notation sets, entity and PI notation links, and character
whitespace classification. NamespaceAttributes retains lexical declarations/defaulting and empty undeclarations separately
from inherited namespace nodes. DocumentInfo.DocumentType retains the principal document-type item and original DTD PI
order; acquired document types are not substituted into the principal document. Instruction metadata retains original bases.
Composition strips the element-content-whitespace property while retaining the actual character data.
Mixed source text chunks expose per-character classification through TextInfo.GetCharacterInfo; copied chunks retain it.
Adapter-owned LINQ text nodes retain the mandated stripping through the shared adapter.
UnexpandedEntityReference nodes retain original entity names, system/public identifiers and declaration bases in their
child position, without acquiring or expanding the entity. DOM and preserving/constructed copies retain these information
items. Opaque navigators use ordered XdmEntityReferenceInsertion metadata, including offsets within coalesced text.
Insertions cannot split a Unicode character. These Infoset extensions have no fabricated XDM typed value and LINQ exports
reject them. A DOM host can explicitly identify successfully expanded empty replacements through the disposition callback.
If a platform hid skipped external entities, AreEntityReferencesComplete is false and composition requires complete host
metadata. Engine-owned byte parsing continues to deny external acquisitions. Empty DTD identifiers remain distinct from
absent identifiers.
Included attributes retain ID typing and references. Only entity/notation declarations referenced by actually included items are added to the principal document; identical declarations deduplicate and conflicting names are fatal. IDREF/IDREFS references are rebuilt against fresh result identities in normalized token order, including repeated tokens. Missing or ambiguous targets produce a references property with no value; references to excluded source nodes do not survive. Constructed/preserving copies rebuild these links too, including references on namespace attributes. Explicit navigator fragment projections obtain declarations from the owner document callback before resolving their retained references. Metadata declarations and reference edges consume operation quotas. Byte inputs retain detected encodings even when the original XML has no encoding declaration; character-backed inputs report unavailable physical encoding. Ambiguous notation names have an indexed lookup and share metadata quotas. Adapter-owned LINQ documents retain declaration/encoding knowledge through immutable annotations consumed by the shared adapter; serializing or reconstructing a LINQ object independently does not carry those annotations. LINQ exports reject DTD properties, instruction notation and source whitespace classification that their object model cannot preserve. Sources remain immutable.
Schema assessment remains an explicit operation after composition; stale assessed trees are rejected before acquisition.
The broader xpointer() scheme is unsupported. Unsupported pointers produce a resource error; schema-assessed
trees currently fail with UnsupportedFeature and never receive stale assessment data.
An unrecovered denied resource retains ResourceUnavailable with FatalError category. Empty href has no
whole-document retrieval behavior on this surface and produces a resource error. This route does not claim complete
XInclude 1.0 Second Edition conformance.
XIncludeException carries an exact error code, category, original immutable source node, trusted acquired URI when available,
and host denial reason. Cancellation propagates as OperationCanceledException; host resolver/stream failures preserve their
original exceptions. Failure exposes no partial result. Limits count all acquired bytes/read work, traversal steps, emitted
nodes, cumulative source scalar values, and cumulative output string values. Source-node inspections accumulate across the
principal tree and every acquired snapshot, including repeated cache inspections; output-node limits separately include
intermediate composed trees discarded by pointer selection. Both count attributes and namespace nodes. Fallback and snapshot
reuse never reset an allowance. Resolver acquisitions and every stream read, including end-of-stream probes, consume resource
work. Built-in pointer evaluation conservatively reserves parsing and each part's ID/navigation/membership traversal upper
bound before dispatch; misses consume that same work allowance before fallback can run. Trusted selector callback computation
remains caller controlled; engine enumeration and membership checks consume the finite operation allowance.
Nested intermediate composition shares one active projection-depth allowance, so pointer processing cannot multiply
recursive call depth by restarting a document at depth zero. Maximum depth has a hard supported ceiling of 128. Each call has independent
budgets; shared services do not confer authority on later calls that omit them. Owned streams are disposed asynchronously
before parsing, and borrowed streams remain open.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net11.0
- DCoding.Xml.Xdm (>= 1.0.1)
- DCoding.Xml.XPointer (>= 1.0.1)
-
net8.0
- DCoding.Xml.Xdm (>= 1.0.1)
- DCoding.Xml.XPointer (>= 1.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.1 | 53 | 11/20/2026 |
Stable 1.0.1: licensing and packaging correction delivery. Public APIs and edition rights are unchanged.