XamlReader.ReadSubtree Method

Definition

Namespace:

System.Xaml

Assembly:

System.Xaml.dll

Returns a XamlReader that is based on the current XamlReader, where the returned XamlReader is used to iterate through a subtree of the XAML node structure.

public:
 virtual System::Xaml::XamlReader ^ ReadSubtree();

public virtual System.Xaml.XamlReader ReadSubtree ();

abstract member ReadSubtree : unit -> System.Xaml.XamlReader
override this.ReadSubtree : unit -> System.Xaml.XamlReader

Public Overridable Function ReadSubtree () As XamlReader

Returns

XamlReader

A new XAML reader instance for the subtree.

Remarks

This method has a default implementation and returns a valid XamlReader. The returned XamlReader is an internal class that restricts certain XamlReader actions. The restrictions are consistent with the purpose of reading only a dimensioned subtree of a larger source for a XAML node set, and of returning end-of-file or null at the current node when the subtree is exited.

Generally, you should check the current node from the initial Read to determine whether you need a subtree reader. How you check this may be implementation-specific; however, avoid creating multiple subtree readers for every subtree. In addition, avoid invoking a subtree reader for certain node cases (for example, for NamespaceDeclaration) that cannot contain a subtree of nodes.

After you obtain a subtree reader, you must call Read on it to obtain a current node (or call Skip to obtain a next node). You do not automatically obtain an initial node position from the subtree reader when you create it.

The reader you obtain by calling ReadSubtree from this default implementation is an internal class. The internal class bases its behavior on the XamlReader implementation that is being used when ReadSubtree is called. The purpose of the internal class is to wrap the Read and general traversal behavior. The traversal stays within the intended subtree by keeping track of StartMember/EndMember pairs or StartObject/EndObject pairs. It also correctly returns false for Read and true for IsEof when the reader is at the end of the subtree, as defined by its entry point. In general, you assume that any XamlReader API you call from a subtree reader has the same implementation as the overall XamlReader except for the traversal bounding behavior.

However, ReadSubtree is virtual. Therefore, a specific XamlReader implementation can provide behavior that differs from the XamlReader internal wrapper behavior; and a XamlReader implementation can even disable subtree reader functionality by returning NotImplementedException or other exceptions.