XamlReader class

Applies to Windows and Windows Phone

Provides a XAML processor engine for parsing XAML and creating corresponding object trees.

Inheritance

Object
  XamlReader

Syntax


public ref class XamlReader sealed 

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The XamlReader class has these types of members:

Methods

The XamlReader class has these methods. It also inherits methods from the Object class.

MethodDescription
Load Parses a well-formed XAML fragment and creates a corresponding object tree, and returns the root of the object tree.
LoadWithInitialTemplateValidation Parses a well-formed XAML fragment creates a corresponding object tree, and returns the root of the object tree. Also performs load-time validation of any linked templates.

 

Remarks

XamlReader  is a utility class with methods that create objects based on an input of XAML markup in string form. XamlReader provides object construction behavior that parallels how XAML is parsed by the Windows Runtime XAML parser and the use of XAML for defining the UI of a Windows Store app.

Parsing the XAML input with XamlReader.Load generates run-time object trees of Windows Runtime objects. The object tree provides a way to program against those objects at run time, by walking through parts of the complete tree.

There are several concepts that are important to understand, when you create objects from XAML with the XamlReader.Load method:

  • The XAML content string must define a single root element.
  • The XAML content string must be well-formed XML, as well as being valid XAML.
  • The XAML content must define a default xmlns. Typically this is the Windows Runtime XAML vocabulary, as identified by http://schemas.microsoft.com/winfx/2006/xaml/presentation.
  • Any custom assemblies referenced in a XAML namespace mapping must already be available to the application.
  • The XAML should not attempt to specify x:Class, or include any XAML-defined attributes for event handlers.
  • You can't use FindName in the general XAML namescope to find a runtime object added, but you can search within the specific XAML namescope of the object created. For more info, see XAML namescopes.
  • Object creation logic cannot integrate the loaded XAML with code-behind classes at run time. If you want to add event handlers, you must do so in code by referencing objects obtained from within the object tree structure of the Load result, and using language-specific syntax for attaching handlers (such as +=).
  • There must be existing XAML content; you cannot replace the entire tree of content. You must at the very least preserve the original root element so that the app model implications of a loaded XAML page remain active.
  • The object that is created from Load can be assigned to only one location in the primary object tree. If you want to add objects created from identical XAML to different areas of the application's primary object tree, you must parse the XAML multiple times using the same input string, using different destinations for the return value.
  • The primary object tree remaining must support an appropriate property to set.

Examples

This example creates a single Ellipse from a XAML string, calling Load. Then it connects the created but disconnected Ellipse to the Children collection of an element that already existed in the running Windows Store app. Finally the example accesses the Ellipse again in the location where it was added by using a query, and changes one of its properties.


string xaml =
"<Ellipse Name=\"EllipseAdded\" Width=\"300.5\" Height=\"200\" 
Fill=\"Red\" \"http://schemas.microsoft.com/winfx/2006/xaml/presentation\"/>";
object ellipse = XamlReader.Load(xaml);
//stackPanelRoot is the visual root of a Page in existing XAML markup already loaded by the appmodel
stackPanelRoot.Children.Add(ellipse as UIElement);
//walk the tree using XLinq result and cast back to a XAML type to set a property on it at runtime
var result = (from item in stackPanelRoot.Children
  where (item is FrameworkElement) 
  && ((FrameworkElement) item).Name == "EllipseAdded"
  select item as FrameworkElement).FirstOrDefault();
((Ellipse) result).Fill = new SolidColorBrush(Colors.Yellow);

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Markup
Windows::UI::Xaml::Markup [C++]

Metadata

Windows.winmd

See also

Basic XAML syntax guide
XAML overview

 

 

Show:
© 2014 Microsoft