XamlReader.LoadAsync Method

Definition

Namespace:

System.Windows.Markup

Assembly:

PresentationFramework.dll

Reads XAML markup and returns an object that corresponds to the root of the specified markup.

Overloads

LoadAsync(Stream, ParserContext, Boolean)
LoadAsync(XmlReader, Boolean)
LoadAsync(Stream, ParserContext)	Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.
LoadAsync(Stream)	Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.
LoadAsync(XmlReader)	Reads the XAML input in the specified XmlReader and returns the root of the corresponding object tree.
LoadAsync(Stream, Boolean)

LoadAsync(Stream, ParserContext, Boolean)

public:
 System::Object ^ LoadAsync(System::IO::Stream ^ stream, System::Windows::Markup::ParserContext ^ parserContext, bool useRestrictiveXamlReader);

public object LoadAsync (System.IO.Stream stream, System.Windows.Markup.ParserContext parserContext, bool useRestrictiveXamlReader);

member this.LoadAsync : System.IO.Stream * System.Windows.Markup.ParserContext * bool -> obj

Public Function LoadAsync (stream As Stream, parserContext As ParserContext, useRestrictiveXamlReader As Boolean) As Object

Parameters

stream

Stream

parserContext

ParserContext

useRestrictiveXamlReader

Boolean

Returns

Object

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(Stream, ParserContext, Boolean).

LoadAsync(XmlReader, Boolean)

public:
 System::Object ^ LoadAsync(System::Xml::XmlReader ^ reader, bool useRestrictiveXamlReader);

public object LoadAsync (System.Xml.XmlReader reader, bool useRestrictiveXamlReader);

member this.LoadAsync : System.Xml.XmlReader * bool -> obj

Public Function LoadAsync (reader As XmlReader, useRestrictiveXamlReader As Boolean) As Object

Parameters

reader

XmlReader

useRestrictiveXamlReader

Boolean

Returns

Object

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(XmlReader, Boolean).

LoadAsync(Stream, ParserContext)

Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.

public:
 System::Object ^ LoadAsync(System::IO::Stream ^ stream, System::Windows::Markup::ParserContext ^ parserContext);

public object LoadAsync (System.IO.Stream stream, System.Windows.Markup.ParserContext parserContext);

member this.LoadAsync : System.IO.Stream * System.Windows.Markup.ParserContext -> obj

Public Function LoadAsync (stream As Stream, parserContext As ParserContext) As Object

Parameters

stream

Stream

A stream containing the XAML input to load.

parserContext

ParserContext

Context information used by the parser.

Returns

Object

The root of the created object tree.

Exceptions

ArgumentNullException

stream is null.

InvalidOperationException

Multiple load operations are performed concurrently with the same XamlReader.

Remarks

An asynchronous XAML load operation will initially return an object that is purely the root object. Asynchronously, XAML parsing then continues, and any child objects are filled in under the root. This is in contrast to the typical WPF XAML processing behavior and its interaction with WPF concepts of object lifetime. In the typical (non-async) interaction, all properties of an object including all child collections are filled before returning an element and reporting it as loaded. That behavior equates to a bottom-up methodology for creating the tree where the root object is the last object to become available.

You typically would assign the returned object to some location in your application's object tree, with the knowledge that content might still be filling in and might cause incremental layout updates if the entire content is exposed as part of the UI. For this reason it is typical to isolate or virtualize any asynchronously loaded objects from XAML, and to use application-specific logic or application state to notify when LoadCompleted is handled.

In order for LoadAsync to load markup asynchronously, the root element in the XAML markup must contain the attribute and value x:SynchronousMode="Async". The value is treated as case sensitive. If the XAML markup root does not contain x:SynchronousMode="Async", no exception is thrown, and the call is processed as a synchronous load (see Load(Stream, ParserContext)).

Only one asynchronous load operation per instance of the XamlReader class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the XamlReader class an InvalidOperationException is thrown.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(Stream, ParserContext).

See also

• XamlWriter

LoadAsync(Stream)

Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.

public:
 System::Object ^ LoadAsync(System::IO::Stream ^ stream);

public object LoadAsync (System.IO.Stream stream);

member this.LoadAsync : System.IO.Stream -> obj

Public Function LoadAsync (stream As Stream) As Object

Parameters

stream

Stream

The stream containing the XAML input to load.

Returns

Object

The object that is the root of the created object tree.

Exceptions

ArgumentNullException

stream is null.

InvalidOperationException

Multiple load operations are pending concurrently with the same XamlReader.

Remarks

An asynchronous XAML load operation will initially return an object that is purely the root object. Asynchronously, XAML parsing then continues, and any child objects are filled in under the root. This is in contrast to the typical WPF XAML processing behavior and its interaction with WPF concepts of object lifetime. In the typical (non-async) interaction, all properties of an object including all child collections are filled before returning an element and reporting it as loaded. That behavior equates to a bottom-up methodology for creating the tree where the root object is the last object to become available.

You typically would assign the returned object to some location in your WPF application's object tree, with the knowledge that content might still be filling in and might cause incremental layout updates if the entire content is exposed as part of the UI. For this reason it is typical to isolate or virtualize any asynchronously loaded objects from XAML, and to use application-specific logic or application state to notify when LoadCompleted is handled.

In order for LoadAsync to load XAML input asynchronously, the root element in the XAML input must contain the attribute and value x:SynchronousMode="Async". The value is treated as case sensitive. If the XAML input root does not contain x:SynchronousMode="Async", no exception is thrown, and the call is processed as a synchronous load (see Load(Stream)).

Only one asynchronous load operation per instance of the XamlReader class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the XamlReader class an InvalidOperationException is thrown.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(Stream).

See also

• XamlWriter

LoadAsync(XmlReader)

Reads the XAML input in the specified XmlReader and returns the root of the corresponding object tree.

public:
 System::Object ^ LoadAsync(System::Xml::XmlReader ^ reader);

public object LoadAsync (System.Xml.XmlReader reader);

member this.LoadAsync : System.Xml.XmlReader -> obj

Public Function LoadAsync (reader As XmlReader) As Object

Parameters

reader

XmlReader

An existing XmlReader that has already loaded/read the XAML input.

Returns

Object

The root of the created object tree.

Exceptions

ArgumentNullException

reader is null.

InvalidOperationException

Multiple load operations are performed concurrently with the same XamlReader.

Remarks

An asynchronous XAML load operation will initially return an object that is purely the root object. Asynchronously, XAML parsing then continues, and any child objects are filled in under the root. This is in contrast to the typical WPF XAML processing behavior and its interaction with WPF concepts of object lifetime. In the typical (non-async) interaction, all properties of an object including all child collections are filled before returning an element and reporting it as loaded. That behavior equates to a bottom-up methodology for creating the tree where the root object is the last object to become available.

You typically would assign the returned object from LoadAsync to some location in your application's object tree, with the knowledge that content might still be filling in and might cause incremental layout updates if the entire content is exposed as part of the UI. For this reason it is typical to isolate or virtualize any asynchronously loaded objects from XAML, and to use application-specific logic or application state to notify when LoadCompleted is handled.

In order for LoadAsync to load XAML input asynchronously, the root element in the XAML markup must contain the attribute and value x:SynchronousMode="Async". The value is treated as case sensitive. If the XAML markup root does not contain x:SynchronousMode="Async", no exception is thrown, and the call is instead processed as a synchronous load (see Load(XmlReader)).

Only one asynchronous load operation per instance of the XamlReader class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the XamlReader class an InvalidOperationException is thrown.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(XmlReader).

See also

• XamlWriter

LoadAsync(Stream, Boolean)

public:
 System::Object ^ LoadAsync(System::IO::Stream ^ stream, bool useRestrictiveXamlReader);

public object LoadAsync (System.IO.Stream stream, bool useRestrictiveXamlReader);

member this.LoadAsync : System.IO.Stream * bool -> obj

Public Function LoadAsync (stream As Stream, useRestrictiveXamlReader As Boolean) As Object

Parameters

stream

Stream

useRestrictiveXamlReader

Boolean

Returns

Object

Remarks

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by Load(Stream, Boolean).