XAML Parser Architecture
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
The WPF Designer for Visual Studio loads Extensible Application Markup Language (XAML) documents and creates WPF objects for display in Visual Studio. Errors encountered during loading appear in the Error List window.
XAML Load Phases
The WPF Designer loads a XAML document and creates a corresponding abstract syntax tree (AST). The AST is a data structure which represents the parsed XAML. It is a finite, labeled, directed tree in which the internal nodes are labeled by operators, and the leaf nodes represent the operands of the node operators. The leaves have nullary operators, which are variables or constants.
Loading a XAML document occurs in a series of phases, as shown in the following table.
XAML Load Phase |
Description |
|---|---|
XML Syntax Verification |
Scanner: Lexical pass which checks for anything malformed, checks for invalid characters, and creates lexical tokens. Parser: Creates the AST and performs pair analysis to make sure tags are well formed and balanced. |
XAML Syntax Verification |
ConvertToXaml looks up all of the types, puts the type information into the XAML AST, and annotates the XAML AST. Validate performs error checking and checks the positions of nodes in the tree. |
Model and Object Instantiation |
Discrete phase with a separate walk through the AST, which creates the Editing Model and WPF objects. |
Nodes which have errors from previous phases are marked as erroneous and are not visited again during any subsequent phases. If errors are encountered in the Scanner and Parser phases, the Model and Object Instantiation phase is not attempted.
XML Syntax Verification
The Scanner and Parser phases verify that the document to load is a well-formed XML document which does not contain XML syntax errors. An example of an XML syntax error is a <Button> tag without a matching </Button> end tag. The parser attempts error recovery, and because of this multiple errors may be reported from a single attempt at parsing the document.
XAML Syntax Verification
The parser traverses the XML AST in separate passes to verify that the document is a valid XAML document, which means that it conforms to the XAML XML schema and does not contain invalid XAML. An example of invalid XAML is an element that uses invalid property declarations, such as <Button SomeProperty="Mark">.
These passes include type resolution, so that information, such as element names and property names, can be validated against the element type. For example, the parser checks whether SomeProperty is a property on Button. Missing types cause errors.
The parser attempts error recovery, and multiple errors may be reported from a single attempt at parsing the document. However, not all possible errors are reported. For example, if an element name is misspelled and the property name within that element is misspelled, only the element error will be reported initially, because the property names cannot be validated until the element has been correctly resolved.
Note
This phase does not include the validation of property values. For example, <Button Background="xBlue"/> is not be detected during this phase. See discussion later in this topic.
Model and Object Instantiation
At the end of the syntax verification, there is an AST corresponding to the XAML that a XAML-specific document tree which acts as a view or cursor into that AST.
In the last phase, the model and the underlying instances are instantiated and property values converted from strings and assigned. The parser does this by creating a document tree using a document tree manager class. When the document tree is created for the XAML, the underlying WPF instances are also created. These instances are used as the view in the designer.
When the model and instances are created, if an exception is raised, the creation of any objects for the children of the node where the error occurred is not completed. The model is constructed for the rest of the tree. This exposes as many of the errors as possible.
For example, in the code fragment, <Button Background="Test"/>, the TypeConverter for the Brush type attempts to convert Test to a Brush instance. Because Test is not a valid Brush value, The type converter raises an exception which halts the parsing process for any child nodes, but the exception does not affect the parsing of the rest of the document.
Property values are converted from strings when the owning object is instantiated. This occurs when the owning object is used on the design surface. Many value range errors are not reported until the parent object is used by the designer.
This behavior is similar to WPF compilation. The WPF compiler does not validate or attempt to convert attribute (property) values during compilation. Type converters are not called until the object tree is instantiated by WPF at runtime.
Note
For loading external resource dictionaries, there is an interaction between the Editing Model and the parser. When the Editing Model must load additional XAML files, it triggers a XAML load operation.
Error Messages
A WPF Designer error message help topic describes which of the XAML loading phases raised the error. The following table shows the correspondence of messages to phases.
XAML Loading Phase |
Error message |
|---|---|
XML Syntax Verification |
This error is raised when the XAML file is not a well-formed XML document. |
XAML Syntax Verification |
This error is raised when the file is a valid XML document, but is not a well-formed XAML document. |
Model and Object Instantiation |
This error is raised when the file is a well-formed XAML document, but contains one or more type mismatches. |