Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
543 lines (488 sloc) 43.2 KB
<Type Name="XamlReader" FullName="System.Windows.Markup.XamlReader">
<TypeSignature Language="C#" Value="public class XamlReader" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit XamlReader extends System.Object" />
<TypeSignature Language="DocId" Value="T:System.Windows.Markup.XamlReader" />
<TypeSignature Language="VB.NET" Value="Public Class XamlReader" />
<TypeSignature Language="C++ CLI" Value="public ref class XamlReader" />
<TypeSignature Language="F#" Value="type XamlReader = class" />
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.Object</BaseTypeName>
</Base>
<Interfaces />
<Docs>
<summary>Reads XAML input and creates an object graph, using the WPF default XAML reader and an associated XAML object writer.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The synchronous <xref:System.Windows.Markup.XamlReader.Load%2A> methods are static, but the asynchronous <xref:System.Windows.Markup.XamlReader.LoadAsync%2A> methods are not static and require an instance of the <xref:System.Windows.Markup.XamlReader> class to use.
The output of the `Load` methods is a single object, which represents the root object of a created object tree or object graph. Object graphs that are created by <xref:System.Windows.Markup.XamlReader> are typically added to the existing object tree of a WPF application at run time. Otherwise the new object graph is considered disconnected for purposes of the WPF application model. This means that it does not render, and cannot be accessed using any of the object tree techniques as applied to the WPF application's main object tree (for example, the APIs <xref:System.Windows.FrameworkElement.FindName%2A>, <xref:System.Windows.LogicalTreeHelper>, <xref:System.Windows.Media.VisualTreeHelper>). For more information on object tree concepts, see [Trees in WPF](~/docs/framework/wpf/advanced/trees-in-wpf.md).
<xref:System.Windows.Markup.XamlReader> supports the following primary scenarios:
- **Cloning/object factory**: Without additional mechanisms, a reference type generally cannot be included in more than one position in a WPF object tree. (Examples of additional mechanisms that offer support for sharing or re-use in WPF include objects that are based on <xref:System.Windows.Freezable>, or support for commonly shareable objects such as <xref:System.Windows.Media.Brush> that are referenced as an item from a <xref:System.Windows.ResourceDictionary>.) One way to clone an object that is already in the object tree is to serialize the object using <xref:System.Windows.Markup.XamlWriter.Save%2A?displayProperty=nameWithType>. You then use the serialized string as input for a call to <xref:System.Windows.Markup.XamlReader.Load%2A>, with a stream or <xref:System.Xml.XmlReader> as an intermediary.
- **Constructing objects based on just-in-time information**: There are often other ways to have late-binding or user-supplied input change the state of existing objects. For example you could use the same value to set more than one property, or use data binding. But if you have a scenario where even the type of object to create is only determinable at run time or with user interaction, then creating such an object by building up a string for <xref:System.Windows.Markup.XamlReader.Load%2A> input is often a useful technique.
- **Using existing resource techniques**: The <xref:System.IO.Stream> type is used frequently in other frameworks or technologies for transferring data or objects across application boundaries or for similar situations. You can then use the <xref:System.IO.Stream> techniques to store or obtain XAML-formatted data that you eventually use to create an object as part of your application.
- **Fixed documents:** Your application might load local or downloaded XPS documents for inclusion in a WPF application object tree and UI.
> [!NOTE]
> This documentation sometimes describes an object graph, as opposed to an object tree. A strict parent-child relationship does not always exist in the run time object relationships of a run time WPF application, so an object graph is a more widely applicable terminology. However, because WPF also includes two different tree conceptualization APIs (<xref:System.Windows.LogicalTreeHelper>, <xref:System.Windows.Media.VisualTreeHelper>) the tree metaphor still applies adequately to most real-world cases in WPF. From the XAML language perspective however, the object graph is often the best way to think about how objects are created out of XAML, because the XAML language itself does not necessarily specify helper class methodologies that bring the relationships more into a tree structure again.
## Code Access Security, Loose XAML, and XamlReader
XAML is a markup language that directly represents object instantiation and execution. Therefore, elements created in XAML have the same ability to interact with system resources (network access, file system IO, for example) as the equivalent generated code does.
[!INCLUDE[TLA2#tla_winclient](~/includes/tla2sharptla-winclient-md.md)] supports the [!INCLUDE[TLA2#tla_net](~/includes/tla2sharptla-net-md.md)] security framework [!INCLUDE[TLA#tla_cas](~/includes/tlasharptla-cas-md.md)]. This means that [!INCLUDE[TLA2#tla_winclient](~/includes/tla2sharptla-winclient-md.md)] content running in the internet zone has reduced execution permissions. "Loose XAML" (pages of noncompiled XAML interpreted at load time by a XAML viewer) and [!INCLUDE[TLA#tla_xbap](~/includes/tlasharptla-xbap-md.md)] are usually run in this internet zone and use the same permission set. However, XAML loaded in to a fully trusted application has the same access to the system resources as the hosting application does. For more information, see [WPF Partial Trust Security](~/docs/framework/wpf/wpf-partial-trust-security.md).
The implications of these statements for <xref:System.Windows.Markup.XamlReader> is that your application design must make trust decisions about the XAML you decide to load. If you are loading XAML that is not trusted, consider implementing your own sandboxing technique for how you load the resulting object graph.
<xref:System.Windows.Markup.XamlReader> can also be called by partial trust code. In this case, Internet security zone is applied for code access security. If anything in the loaded XAML is invalid under Internet security zone, a XAML parse exception is thrown. Under XBAP and other cases that are partial trust at the platform level, where <xref:System.Windows.Markup.XamlReader> is part of the execution, you get the same exception behavior as with explicit partial trust calls.
## WPF XAML, XAML Readers/Writers, and XAML Language Versioning
XAML2009 includes language features such as [x:Reference](~/docs/framework/xaml-services/x-reference-markup-extension.md) and [x:FactoryMethod](~/docs/framework/xaml-services/x-factorymethod-directive.md). You can use signatures of `Load` or `Parse` to load XAML that uses these features. However, those language features are not supported for XAML that needs to be markup compiled (such as XAML for the **Page** build action in a WPF application, or any XAML that involves the markup compile task in the build actions).
WPF types and the WPF technology in general support concepts that rely on access to WPF internals. For instance, how WPF implements dependency properties relies on internal techniques for efficient type-member lookup. Access to these internals is enabled by the XAML reading and writing APIs provided in <xref:System.Windows.Markup.XamlWriter> and <xref:System.Windows.Markup.XamlReader> from the <xref:System.Windows.Markup> namespace and PresentationFramework assembly. However, the lower-level XAML readers and XAML writers from the System.Xaml assembly (classes based on <xref:System.Xaml.XamlReader?displayProperty=nameWithType>, <xref:System.Xaml.XamlWriter?displayProperty=nameWithType>) do not have access to the WPF internals. There is no dependency from System.Xaml to any WPF-specific assembly. Without access to the WPF internals, System.Xaml readers and writers cannot correctly load or save all WPF types, or types based on WPF types. In particular, the System.Xaml readers and writers do not understand concepts such as the WPF dependency property backing property store, or all the specifics of how WPF uses styles, resource dictionaries and templates. Therefore you have a choice to make:
- If you are loading WPF types, and/or you are using XAML in BAML form in any way, use the PresentationFramework XAML readers and XAML writers.
- If you are not relying on any WPF types or the BAML form of XAML, and are not using another specific technology's XAML reader or XAML writer implementation for reasons that are specific to that framework, use the System.Xaml XAML readers and XAML writers.
## System.Xaml Backing Implementation in .NET 4
<xref:System.Windows.Markup.XamlReader> is the callable API surface for the WPF framework-level XAML parser. The same underlying XAML parser also performs the run-time XAML loading and parsing for WPF applications that target [!INCLUDE[net_v30_short](~/includes/net-v30-short-md.md)] and [!INCLUDE[net_v35_short](~/includes/net-v35-short-md.md)].
If you are targeting [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], the external API is the same, but parts of the implementation are built on the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)] general XAML implementation in the System.Xaml assembly, which improves many of the technical and reporting aspects of parsing XAML. Targeting [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)] necessarily entails including System.Xaml as a reference, and details of implementation such as the exceptions reported may come from System.Xaml defined types.
## Examples
The following example converts a <xref:System.Windows.Controls.Button> into a string using the <xref:System.Windows.Markup.XamlWriter> class. The string is then loaded back into a <xref:System.Windows.Controls.Button> using the static <xref:System.Windows.Markup.XamlReader.Load%2A> method on the <xref:System.Windows.Markup.XamlReader> class.
[!code-csharp[xamlreaderwritersnippets#XamlReaderLoadXmlReader](~/samples/snippets/csharp/VS_Snippets_Wpf/XamlReaderWriterSnippets/CSharp/Window1.xaml.cs#xamlreaderloadxmlreader)]
[!code-vb[xamlreaderwritersnippets#XamlReaderLoadXmlReader](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XamlReaderWriterSnippets/visualbasic/window1.xaml.vb#xamlreaderloadxmlreader)]
]]></format>
</remarks>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public XamlReader ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.#ctor" />
<MemberSignature Language="VB.NET" Value="Public Sub New ()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; XamlReader();" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters />
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Windows.Markup.XamlReader" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="CancelAsync">
<MemberSignature Language="C#" Value="public void CancelAsync ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance void CancelAsync() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.CancelAsync" />
<MemberSignature Language="VB.NET" Value="Public Sub CancelAsync ()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; void CancelAsync();" />
<MemberSignature Language="F#" Value="member this.CancelAsync : unit -&gt; unit" Usage="xamlReader.CancelAsync " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Aborts the current asynchronous load operation, if there is an asynchronous load operation pending.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Windows.Markup.XamlReader.CancelAsync%2A> is an asynchronous operation; therefore, some loading may occur before the operation is aborted.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="GetWpfSchemaContext">
<MemberSignature Language="C#" Value="public static System.Xaml.XamlSchemaContext GetWpfSchemaContext ();" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Xaml.XamlSchemaContext GetWpfSchemaContext() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.GetWpfSchemaContext" />
<MemberSignature Language="VB.NET" Value="Public Shared Function GetWpfSchemaContext () As XamlSchemaContext" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Xaml::XamlSchemaContext ^ GetWpfSchemaContext();" />
<MemberSignature Language="F#" Value="static member GetWpfSchemaContext : unit -&gt; System.Xaml.XamlSchemaContext" Usage="System.Windows.Markup.XamlReader.GetWpfSchemaContext " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Xaml.XamlSchemaContext</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Returns a <see cref="T:System.Xaml.XamlSchemaContext" /> object that represents the WPF schema context settings for a <see cref="T:System.Windows.Markup.XamlReader" />.</summary>
<returns>A <see cref="T:System.Xaml.XamlSchemaContext" /> object that represents the WPF schema context settings for a <see cref="T:System.Windows.Markup.XamlReader" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
<MemberGroup MemberName="Load">
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Reads XAML input and returns the root of the corresponding object tree.</summary>
</Docs>
</MemberGroup>
<Member MemberName="Load">
<MemberSignature Language="C#" Value="public static object Load (System.IO.Stream stream);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Load(class System.IO.Stream stream) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Load(System.IO.Stream)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Load(System::IO::Stream ^ stream);" />
<MemberSignature Language="F#" Value="static member Load : System.IO.Stream -&gt; obj" Usage="System.Windows.Markup.XamlReader.Load stream" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="stream" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="stream">The XAML to load, in stream form.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.IO.Stream" /> and returns an <see cref="T:System.Object" /> that is the root of the corresponding object tree.</summary>
<returns>The object at the root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Examples
The following example saves a <xref:System.Windows.Controls.Button> into a <xref:System.IO.MemoryStream> using the <xref:System.Windows.Markup.XamlWriter> class. The stream is then loaded back into a <xref:System.Windows.Controls.Button> using the static <xref:System.Windows.Markup.XamlReader.Load%2A> method on the <xref:System.Windows.Markup.XamlReader> class.
[!code-csharp[XamlReaderWriterSnippets#XamlReaderLoadXmlReader](~/samples/snippets/csharp/VS_Snippets_Wpf/XamlReaderWriterSnippets/CSharp/Window1.xaml.cs#xamlreaderloadxmlreader)]
[!code-vb[XamlReaderWriterSnippets#XamlReaderLoadXmlReader](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XamlReaderWriterSnippets/visualbasic/window1.xaml.vb#xamlreaderloadxmlreader)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="stream" /> is <see langword="null" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<Member MemberName="Load">
<MemberSignature Language="C#" Value="public static object Load (System.Xaml.XamlReader reader);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Load(class System.Xaml.XamlReader reader) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Load(System.Xaml.XamlReader)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Load (reader As XamlReader) As Object" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Load(System::Xaml::XamlReader ^ reader);" />
<MemberSignature Language="F#" Value="static member Load : System.Xaml.XamlReader -&gt; obj" Usage="System.Windows.Markup.XamlReader.Load reader" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="reader" Type="System.Xaml.XamlReader" Index="0" FrameworkAlternate="netcore-3.0;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
</Parameters>
<Docs>
<param name="reader">A <see cref="T:System.Xaml.XamlReader" /> object. This is expected to be initialized with input XAML.</param>
<summary>Reads the XAML input through a provided <see cref="T:System.Xaml.XamlReader" /> and returns an object that is the root of the corresponding object tree.</summary>
<returns>The object that is the root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The input <xref:System.Xaml.XamlReader> can be <xref:System.Windows.Baml2006.Baml2006Reader>. This is how you can load BAML at run time, or for localization tool purposes.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="reader" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="Load">
<MemberSignature Language="C#" Value="public static object Load (System.Xml.XmlReader reader);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Load(class System.Xml.XmlReader reader) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Load(System.Xml.XmlReader)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Load (reader As XmlReader) As Object" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Load(System::Xml::XmlReader ^ reader);" />
<MemberSignature Language="F#" Value="static member Load : System.Xml.XmlReader -&gt; obj" Usage="System.Windows.Markup.XamlReader.Load reader" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="reader" Type="System.Xml.XmlReader" />
</Parameters>
<Docs>
<param name="reader">The <see cref="T:System.Xml.XmlReader" /> that has already loaded the XAML input to load in XML form.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.Xml.XmlReader" /> and returns an object that is the root of the corresponding object tree.</summary>
<returns>The object that is the root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Examples
The following example converts a <xref:System.Windows.Controls.Button> into a string using the <xref:System.Windows.Markup.XamlWriter> class. The string is then loaded back into a <xref:System.Windows.Controls.Button> using the static <xref:System.Windows.Markup.XamlReader.Load%2A> method on the <xref:System.Windows.Markup.XamlReader> class.
[!code-csharp[XamlReaderWriterSnippets#XamlReaderLoadXmlReader](~/samples/snippets/csharp/VS_Snippets_Wpf/XamlReaderWriterSnippets/CSharp/Window1.xaml.cs#xamlreaderloadxmlreader)]
[!code-vb[XamlReaderWriterSnippets#XamlReaderLoadXmlReader](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XamlReaderWriterSnippets/visualbasic/window1.xaml.vb#xamlreaderloadxmlreader)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="reader" /> is <see langword="null" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<Member MemberName="Load">
<MemberSignature Language="C#" Value="public static object Load (System.IO.Stream stream, System.Windows.Markup.ParserContext parserContext);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Load(class System.IO.Stream stream, class System.Windows.Markup.ParserContext parserContext) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Load(System.IO.Stream,System.Windows.Markup.ParserContext)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Load(System::IO::Stream ^ stream, System::Windows::Markup::ParserContext ^ parserContext);" />
<MemberSignature Language="F#" Value="static member Load : System.IO.Stream * System.Windows.Markup.ParserContext -&gt; obj" Usage="System.Windows.Markup.XamlReader.Load (stream, parserContext)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="stream" Type="System.IO.Stream" />
<Parameter Name="parserContext" Type="System.Windows.Markup.ParserContext" />
</Parameters>
<Docs>
<param name="stream">The stream that contains the XAML input to load.</param>
<param name="parserContext">Context information used by the parser.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.IO.Stream" /> and returns an object that is the root of the corresponding object tree.</summary>
<returns>The object that is the root of the created object tree.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="stream" /> is <see langword="null" />.
-or-
<paramref name="parserContext" /> is <see langword="null" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<MemberGroup MemberName="LoadAsync">
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Reads XAML markup and returns an object that corresponds to the root of the specified markup.</summary>
</Docs>
</MemberGroup>
<Member MemberName="LoadAsync">
<MemberSignature Language="C#" Value="public object LoadAsync (System.IO.Stream stream);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance object LoadAsync(class System.IO.Stream stream) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.LoadAsync(System.IO.Stream)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Object ^ LoadAsync(System::IO::Stream ^ stream);" />
<MemberSignature Language="F#" Value="member this.LoadAsync : System.IO.Stream -&gt; obj" Usage="xamlReader.LoadAsync stream" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="stream" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="stream">The stream containing the XAML input to load.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.IO.Stream" /> and returns the root of the corresponding object tree.</summary>
<returns>The object that is the root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## 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 <xref:System.Windows.Markup.XamlReader.LoadCompleted> is handled.
In order for <xref:System.Windows.Markup.XamlReader.LoadAsync%2A> 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 <xref:System.Windows.Markup.XamlReader.Load%28System.IO.Stream%29>).
Only one asynchronous load operation per instance of the <xref:System.Windows.Markup.XamlReader> class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the <xref:System.Windows.Markup.XamlReader> class an <xref:System.InvalidOperationException> is thrown.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="stream" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">Multiple load operations are pending concurrently with the same <see cref="T:System.Windows.Markup.XamlReader" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<Member MemberName="LoadAsync">
<MemberSignature Language="C#" Value="public object LoadAsync (System.Xml.XmlReader reader);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance object LoadAsync(class System.Xml.XmlReader reader) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.LoadAsync(System.Xml.XmlReader)" />
<MemberSignature Language="VB.NET" Value="Public Function LoadAsync (reader As XmlReader) As Object" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Object ^ LoadAsync(System::Xml::XmlReader ^ reader);" />
<MemberSignature Language="F#" Value="member this.LoadAsync : System.Xml.XmlReader -&gt; obj" Usage="xamlReader.LoadAsync reader" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="reader" Type="System.Xml.XmlReader" />
</Parameters>
<Docs>
<param name="reader">An existing <see cref="T:System.Xml.XmlReader" /> that has already loaded/read the XAML input.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.Xml.XmlReader" /> and returns the root of the corresponding object tree.</summary>
<returns>The root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## 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 <xref:System.Windows.Markup.XamlReader.LoadAsync%2A> 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 <xref:System.Windows.Markup.XamlReader.LoadCompleted> is handled.
In order for <xref:System.Windows.Markup.XamlReader.LoadAsync%2A> 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 <xref:System.Windows.Markup.XamlReader.Load%28System.Xml.XmlReader%29>).
Only one asynchronous load operation per instance of the <xref:System.Windows.Markup.XamlReader> class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the <xref:System.Windows.Markup.XamlReader> class an <xref:System.InvalidOperationException> is thrown.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="reader" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">Multiple load operations are performed concurrently with the same <see cref="T:System.Windows.Markup.XamlReader" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<Member MemberName="LoadAsync">
<MemberSignature Language="C#" Value="public object LoadAsync (System.IO.Stream stream, System.Windows.Markup.ParserContext parserContext);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance object LoadAsync(class System.IO.Stream stream, class System.Windows.Markup.ParserContext parserContext) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.LoadAsync(System.IO.Stream,System.Windows.Markup.ParserContext)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Object ^ LoadAsync(System::IO::Stream ^ stream, System::Windows::Markup::ParserContext ^ parserContext);" />
<MemberSignature Language="F#" Value="member this.LoadAsync : System.IO.Stream * System.Windows.Markup.ParserContext -&gt; obj" Usage="xamlReader.LoadAsync (stream, parserContext)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="stream" Type="System.IO.Stream" />
<Parameter Name="parserContext" Type="System.Windows.Markup.ParserContext" />
</Parameters>
<Docs>
<param name="stream">A stream containing the XAML input to load.</param>
<param name="parserContext">Context information used by the parser.</param>
<summary>Reads the XAML input in the specified <see cref="T:System.IO.Stream" /> and returns the root of the corresponding object tree.</summary>
<returns>The root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## 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 <xref:System.Windows.Markup.XamlReader.LoadCompleted> is handled.
In order for <xref:System.Windows.Markup.XamlReader.LoadAsync%2A> 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 <xref:System.Windows.Markup.XamlReader.Load%28System.IO.Stream%2CSystem.Windows.Markup.ParserContext%29>).
Only one asynchronous load operation per instance of the <xref:System.Windows.Markup.XamlReader> class can be performed at a time. If more than one asynchronous operation is attempted on the same instance of the <xref:System.Windows.Markup.XamlReader> class an <xref:System.InvalidOperationException> is thrown.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="stream" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">Multiple load operations are performed concurrently with the same <see cref="T:System.Windows.Markup.XamlReader" />.</exception>
<altmember cref="T:System.Windows.Markup.XamlWriter" />
</Docs>
</Member>
<Member MemberName="LoadCompleted">
<MemberSignature Language="C#" Value="public event System.ComponentModel.AsyncCompletedEventHandler LoadCompleted;" />
<MemberSignature Language="ILAsm" Value=".event class System.ComponentModel.AsyncCompletedEventHandler LoadCompleted" />
<MemberSignature Language="DocId" Value="E:System.Windows.Markup.XamlReader.LoadCompleted" />
<MemberSignature Language="VB.NET" Value="Public Custom Event LoadCompleted As AsyncCompletedEventHandler " FrameworkAlternate="netcore-3.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; event System::ComponentModel::AsyncCompletedEventHandler ^ LoadCompleted;" />
<MemberSignature Language="F#" Value="member this.LoadCompleted : System.ComponentModel.AsyncCompletedEventHandler " Usage="member this.LoadCompleted : System.ComponentModel.AsyncCompletedEventHandler " />
<MemberSignature Language="VB.NET" Value="Public Event LoadCompleted As AsyncCompletedEventHandler " FrameworkAlternate="netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<MemberType>Event</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.ComponentModel.AsyncCompletedEventHandler</ReturnType>
</ReturnValue>
<Docs>
<summary>Occurs when an asynchronous load operation completes.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Windows.Markup.XamlReader.LoadCompleted> is also raised when an asynchronous load operation aborts.
]]></format>
</remarks>
<altmember cref="T:System.ComponentModel.AsyncCompletedEventHandler" />
</Docs>
</Member>
<MemberGroup MemberName="Parse">
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Reads the markup in the specified text string and returns an object that corresponds to the root of the specified markup.</summary>
</Docs>
</MemberGroup>
<Member MemberName="Parse">
<MemberSignature Language="C#" Value="public static object Parse (string xamlText);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Parse(string xamlText) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Parse(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Parse (xamlText As String) As Object" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Parse(System::String ^ xamlText);" />
<MemberSignature Language="F#" Value="static member Parse : string -&gt; obj" Usage="System.Windows.Markup.XamlReader.Parse xamlText" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="xamlText" Type="System.String" />
</Parameters>
<Docs>
<param name="xamlText">The input XAML, as a single text string.</param>
<summary>Reads the XAML input in the specified text string and returns an object that corresponds to the root of the specified markup.</summary>
<returns>The root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The implementation calls <xref:System.Windows.Markup.XamlReader.Load%2A> internally after creating a stream from the string. See <xref:System.Windows.Markup.XamlReader.Load%2A> for additional information such as possible exceptions.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Parse">
<MemberSignature Language="C#" Value="public static object Parse (string xamlText, System.Windows.Markup.ParserContext parserContext);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig object Parse(string xamlText, class System.Windows.Markup.ParserContext parserContext) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Windows.Markup.XamlReader.Parse(System.String,System.Windows.Markup.ParserContext)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Object ^ Parse(System::String ^ xamlText, System::Windows::Markup::ParserContext ^ parserContext);" />
<MemberSignature Language="F#" Value="static member Parse : string * System.Windows.Markup.ParserContext -&gt; obj" Usage="System.Windows.Markup.XamlReader.Parse (xamlText, parserContext)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>PresentationFramework</AssemblyName>
<AssemblyVersion>3.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="xamlText" Type="System.String" />
<Parameter Name="parserContext" Type="System.Windows.Markup.ParserContext" />
</Parameters>
<Docs>
<param name="xamlText">The input XAML, as a single text string.</param>
<param name="parserContext">Context information used by the parser.</param>
<summary>Reads the XAML markup in the specified text string (using a specified <see cref="T:System.Windows.Markup.ParserContext" />) and returns an object that corresponds to the root of the specified markup.</summary>
<returns>The root of the created object tree.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The implementation calls <xref:System.Windows.Markup.XamlReader.Load%2A> internally after creating a stream from the string. See <xref:System.Windows.Markup.XamlReader.Load%2A> for additional information such as possible exceptions.
]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>
You can’t perform that action at this time.