XamlReader 类

定义

使用 WPF 默认 XAML 读取器和关联的 XAML 对象编写器读取 XAML 输入并创建对象图。Reads XAML input and creates an object graph, using the WPF default XAML reader and an associated XAML object writer.

public ref class XamlReader
public class XamlReader
type XamlReader = class
Public Class XamlReader
继承
XamlReader

示例

下面的示例使用类将转换为 Button 字符串 XamlWriterThe following example converts a Button into a string using the XamlWriter class. 然后, Button 使用类上的静态方法将该字符串重新加载到中 Load XamlReaderThe string is then loaded back into a Button using the static Load method on the XamlReader class.

// Create the Button.
Button originalButton = new Button();
originalButton.Height = 50;
originalButton.Width = 100;
originalButton.Background = Brushes.AliceBlue;
originalButton.Content = "Click Me";

// Save the Button to a string.
string savedButton = XamlWriter.Save(originalButton);

// Load the button
StringReader stringReader = new StringReader(savedButton);
XmlReader xmlReader = XmlReader.Create(stringReader);
Button readerLoadButton = (Button)XamlReader.Load(xmlReader);
' Create the Button.
Dim originalButton As New Button()
originalButton.Height = 50
originalButton.Width = 100
originalButton.Background = Brushes.AliceBlue
originalButton.Content = "Click Me"

' Save the Button to a string.
Dim savedButton As String = XamlWriter.Save(originalButton)

' Load the button
Dim stringReader As New StringReader(savedButton)
Dim xmlReader As XmlReader = XmlReader.Create(stringReader)
Dim readerLoadButton As Button = CType(XamlReader.Load(xmlReader), Button)

注解

同步 Load 方法是静态的,但异步 LoadAsync 方法不是静态的,需要类的实例 XamlReader 才能使用。The synchronous Load methods are static, but the asynchronous LoadAsync methods are not static and require an instance of the XamlReader class to use.

方法的输出 Load 是一个对象,它表示已创建的对象树或对象关系图的根对象。The output of the Load methods is a single object, which represents the root object of a created object tree or object graph. 创建的对象图 XamlReader 通常会在运行时添加到 WPF 应用程序的现有对象树中。Object graphs that are created by XamlReader are typically added to the existing object tree of a WPF application at run time. 否则,在 WPF 应用程序模型中,新的对象图被视为已断开连接。Otherwise the new object graph is considered disconnected for purposes of the WPF application model. 这意味着,它不会呈现,并且不能使用任何对象树技术来访问该应用于 WPF 应用程序的主对象树 (例如,Api FindNameLogicalTreeHelper VisualTreeHelper) 。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 FindName, LogicalTreeHelper, VisualTreeHelper). 有关对象树概念的详细信息,请参阅 WPF 中的树For more information on object tree concepts, see Trees in WPF.

XamlReader 支持以下主要方案:XamlReader supports the following primary scenarios:

  • 克隆/对象工厂:没有其他机制,引用类型通常不能包含在 WPF 对象树中的多个位置中。Cloning/object factory: Without additional mechanisms, a reference type generally cannot be included in more than one position in a WPF object tree. (提供对在 WPF 中共享或重复使用的附加机制的示例包括基于的对象 Freezable ,或支持通常可共享的对象(例如), Brush 这些对象将作为中的项进行引用 ResourceDictionary 。 ) 克隆对象树中已存在的对象的一种方法是使用序列化对象 XamlWriter.Save(Examples of additional mechanisms that offer support for sharing or re-use in WPF include objects that are based on Freezable, or support for commonly shareable objects such as Brush that are referenced as an item from a ResourceDictionary.) One way to clone an object that is already in the object tree is to serialize the object using XamlWriter.Save. 然后使用序列化的字符串作为对的调用的输入 Load ,使用流或 XmlReader 作为中介。You then use the serialized string as input for a call to Load, with a stream or 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. 但如果你有这样一种方案,即使要创建的对象类型只在运行时是可在运行时或与用户交互的情况下才可进行,那么通过构建输入字符串来创建此类对象 Load 通常是一项有用的技术。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 Load input is often a useful technique.

  • 使用现有的资源技术Stream 类型经常用在其他框架或技术中,用于跨应用程序边界传输数据或对象,也可用于类似情况。Using existing resource techniques: The Stream type is used frequently in other frameworks or technologies for transferring data or objects across application boundaries or for similar situations. 然后,你可以使用这些 Stream 技术来存储或获取 XAML 格式的数据,最终将这些数据用于创建作为应用程序一部分的对象。You can then use the Stream techniques to store or obtain XAML-formatted data that you eventually use to create an object as part of your application.

  • 固定文档: 您的应用程序可能会加载本地或下载的 XPS 文档,以将其包含在 WPF 应用程序对象树和 UI 中。Fixed documents: Your application might load local or downloaded XPS documents for inclusion in a WPF application object tree and UI.

备注

此文档有时描述对象图,而不是对象树。This documentation sometimes describes an object graph, as opposed to an object tree. 在运行时 WPF 应用程序的运行时对象关系中并不总是存在严格的父子关系,因此,对象图是更广泛适用的术语。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. 但是,因为 WPF 还包括两个不同的概念化 Api (LogicalTreeHelperVisualTreeHelper) 树比喻仍适用于 WPF 中的大多数真实情况。However, because WPF also includes two different tree conceptualization APIs (LogicalTreeHelper, VisualTreeHelper) the tree metaphor still applies adequately to most real-world cases in WPF. 但从 XAML 语言角度来看,对象图通常是考虑如何从 XAML 创建对象的最佳方法,因为 XAML 语言本身并不一定指定帮助器类方法,这会将关系更多地引入树结构。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.

代码访问安全性、松散 XAML 和 XamlReaderCode Access Security, Loose XAML, and XamlReader

XAML 是一种直接表示对象实例化和执行的标记语言。XAML is a markup language that directly represents object instantiation and execution. 因此,在 XAML 中创建的元素能够像等效的生成代码那样与系统资源(如网络访问、文件系统 IO)进行交互。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.

WPF 支持 .NET security framework Code Access Security (CA) 。WPF supports the .NET security framework Code Access Security (CAS). 这意味着在 Internet 区域中运行的 WPF 内容具有缩减的执行权限。This means that WPF content running in the internet zone has reduced execution permissions. "宽松 XAML" (在加载时由 XAML 查看器解释的非编译 XAML 页) 和 XAML 浏览器应用程序 (XBAP) 通常在此 internet 区域中运行并使用同一权限集。"Loose XAML" (pages of noncompiled XAML interpreted at load time by a XAML viewer) and XAML browser application (XBAP) are usually run in this internet zone and use the same permission set. 但是,加载到完全受信任的应用程序中的 XAML 与承载应用程序具有相同的系统资源访问权限。However, XAML loaded in to a fully trusted application has the same access to the system resources as the hosting application does. 有关详细信息,请参阅 WPF 部分信任安全性For more information, see WPF Partial Trust Security.

这些语句的含义在于, XamlReader 你的应用程序设计必须对你决定加载的 XAML 做出信任决策。The implications of these statements for XamlReader is that your application design must make trust decisions about the XAML you decide to load. 如果要加载不受信任的 XAML,请考虑为如何加载生成的对象图实现自己的沙盒技术。If you are loading XAML that is not trusted, consider implementing your own sandboxing technique for how you load the resulting object graph.

XamlReader 还可以由部分信任代码调用。XamlReader can also be called by partial trust code. 在这种情况下,会对代码访问安全性应用 Internet 安全区域。In this case, Internet security zone is applied for code access security. 如果加载的 XAML 中的任何内容在 Internet 安全区域下无效,则会引发 XAML 分析异常。If anything in the loaded XAML is invalid under Internet security zone, a XAML parse exception is thrown. 在 XBAP 和平台级别的部分信任的其他情况下(其中 XamlReader 是执行过程的一部分),你将获得与显式部分信任调用相同的异常行为。Under XBAP and other cases that are partial trust at the platform level, where XamlReader is part of the execution, you get the same exception behavior as with explicit partial trust calls.

WPF XAML、XAML 读取器/编写器和 XAML 语言版本控制WPF XAML, XAML Readers/Writers, and XAML Language Versioning

XAML2009 包含语言功能,如 x:Referencex:FactoryMethodXAML2009 includes language features such as x:Reference and x:FactoryMethod. 您可以使用或的 Load 签名 Parse 来加载使用这些功能的 XAML。You can use signatures of Load or Parse to load XAML that uses these features. 但是,对于需要进行标记 (编译的 XAML (如 WPF 应用程序中的 生成操作的 xaml)或包含生成操作) 中的标记编译任务的任何 xaml,不支持这些语言功能。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 类型和 WPF 技术一般支持依赖于访问 WPF 内部的概念。WPF types and the WPF technology in general support concepts that rely on access to WPF internals. 例如,WPF 实现依赖属性的方式依赖于有效的类型成员查找的内部技术。For instance, how WPF implements dependency properties relies on internal techniques for efficient type-member lookup. 对这些内部机制的访问通过 XamlWriter XamlReaderSystem.Windows.Markup 命名空间和 PresentationFramework 程序集的和中提供的 XAML 读取和写入 api 启用。Access to these internals is enabled by the XAML reading and writing APIs provided in XamlWriter and XamlReader from the System.Windows.Markup namespace and PresentationFramework assembly. 但是,) 基于的 (类的 system.exception 程序集的较低级别 XAML 读取器和 XAML 编写 System.Xaml.XamlReaderSystem.Xaml.XamlWriter 不能访问 WPF 内部。However, the lower-level XAML readers and XAML writers from the System.Xaml assembly (classes based on System.Xaml.XamlReader, System.Xaml.XamlWriter) do not have access to the WPF internals. 与任何 WPF 特定的程序集之间没有任何依赖关系。There is no dependency from System.Xaml to any WPF-specific assembly. 如果没有访问 WPF 内部的权限,则 system.exception 读取器和编写器无法正确加载或保存所有 WPF 类型或基于 WPF 类型的类型。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. 具体而言,系统 .Xaml 读取器和编写器不理解 WPF 依赖属性的支持属性存储等概念,也不了解 WPF 如何使用样式、资源字典和模板的所有细节。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:

  • 如果正在加载 WPF 类型,并且/或者以任何方式在 BAML 窗体中使用 XAML,请使用 PresentationFramework XAML 读取器和 XAML 编写器。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.

  • 如果不依赖于任何 WPF 类型或 XAML 的 BAML 形式,并且出于特定于该框架的原因而未使用其他特定技术的 XAML 读取器或 XAML 编写器实现,请使用 system.exception XAML 读取器和 XAML 编写器。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.

.NET 4 中的 system.exception 后备实现System.Xaml Backing Implementation in .NET 4

XamlReader 是 WPF 框架级别 XAML 分析器的可调用 API 图面。XamlReader is the callable API surface for the WPF framework-level XAML parser. 对于面向 .NET Framework 3.0 和 .NET Framework 3.5 的 WPF 应用程序,相同的基础 XAML 分析器还会执行运行时 XAML 加载和分析。The same underlying XAML parser also performs the run-time XAML loading and parsing for WPF applications that target .NET Framework 3.0 and .NET Framework 3.5.

如果以 .NET Framework 4 为目标,则外部 API 是相同的,但实现的各个部分都是在 system.exception 程序集中的 .NET Framework 4 一般 XAML 实现的基础上生成的,这可提高分析 XAML 的技术和报告方面的诸多方面。If you are targeting .NET Framework 4, the external API is the same, but parts of the implementation are built on the .NET Framework 4 general XAML implementation in the System.Xaml assembly, which improves many of the technical and reporting aspects of parsing XAML. 面向 .NET Framework 4 一定需要包含 system.exception 作为引用,如所报告的异常等实现的详细信息可能来自 system.exception 定义的类型。Targeting .NET Framework 4 necessarily entails including System.Xaml as a reference, and details of implementation such as the exceptions reported may come from System.Xaml defined types.

构造函数

XamlReader()

初始化 XamlReader 类的新实例。Initializes a new instance of the XamlReader class.

方法

CancelAsync()

如果有挂起的异步加载操作,则中止当前的异步加载操作。Aborts the current asynchronous load operation, if there is an asynchronous load operation pending.

Equals(Object)

确定指定对象是否等于当前对象。Determines whether the specified object is equal to the current object.

(继承自 Object)
GetHashCode()

作为默认哈希函数。Serves as the default hash function.

(继承自 Object)
GetType()

获取当前实例的 TypeGets the Type of the current instance.

(继承自 Object)
GetWpfSchemaContext()

返回一个 XamlSchemaContext 对象,该对象表示 XamlReader 的 WPF 架构上下文设置。Returns a XamlSchemaContext object that represents the WPF schema context settings for a XamlReader.

Load(Stream)

读取指定 Stream 中的 XAML 输入,并返回作为相应对象树根的 ObjectReads the XAML input in the specified Stream and returns an Object that is the root of the corresponding object tree.

Load(Stream, Boolean)
Load(Stream, ParserContext)

读取指定 Stream 中的 XAML 输入,并返回作为相应对象树根的对象。Reads the XAML input in the specified Stream and returns an object that is the root of the corresponding object tree.

Load(Stream, ParserContext, Boolean)
Load(XamlReader)

通过所提供的 XamlReader 读取 XAML 输入,并返回作为相应对象树根的对象。Reads the XAML input through a provided XamlReader and returns an object that is the root of the corresponding object tree.

Load(XmlReader)

读取指定 XmlReader 中的 XAML 输入,并返回作为相应对象树根的对象。Reads the XAML input in the specified XmlReader and returns an object that is the root of the corresponding object tree.

Load(XmlReader, Boolean)
LoadAsync(Stream)

读取指定 Stream 中的 XAML 输入,并返回相应对象树的根。Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.

LoadAsync(Stream, Boolean)
LoadAsync(Stream, ParserContext)

读取指定 Stream 中的 XAML 输入,并返回相应对象树的根。Reads the XAML input in the specified Stream and returns the root of the corresponding object tree.

LoadAsync(Stream, ParserContext, Boolean)
LoadAsync(XmlReader)

读取指定 XmlReader 中的 XAML 输入,并返回相应对象树的根。Reads the XAML input in the specified XmlReader and returns the root of the corresponding object tree.

LoadAsync(XmlReader, Boolean)
MemberwiseClone()

创建当前 Object 的浅表副本。Creates a shallow copy of the current Object.

(继承自 Object)
Parse(String)

读取指定文本字符串中的 XAML 输入,并返回与指定标记的根对应的对象。Reads the XAML input in the specified text string and returns an object that corresponds to the root of the specified markup.

Parse(String, Boolean)
Parse(String, ParserContext)

(使用指定的 ParserContext)读取指定文本字符串中的 XAML 标记,并返回与指定标记的根对应的对象。Reads the XAML markup in the specified text string (using a specified ParserContext) and returns an object that corresponds to the root of the specified markup.

Parse(String, ParserContext, Boolean)
ToString()

返回表示当前对象的字符串。Returns a string that represents the current object.

(继承自 Object)

事件

LoadCompleted

在异步加载操作完成时发生。Occurs when an asynchronous load operation completes.

适用于

另请参阅