DataContractSerializer 类

定义

使用提供的数据协定,将类型实例序列化和反序列化为 XML 流或文档。 此类不能被继承。

public ref class DataContractSerializer sealed : System::Runtime::Serialization::XmlObjectSerializer
public sealed class DataContractSerializer : System.Runtime.Serialization.XmlObjectSerializer
type DataContractSerializer = class
    inherit XmlObjectSerializer
Public NotInheritable Class DataContractSerializer
Inherits XmlObjectSerializer
继承
DataContractSerializer

示例

下面的示例代码演示一种名为 Person 且由 DataContractSerializer 序列化的类型。 它将 DataContractAttribute 特性应用于类并将 DataMemberAttribute 应用于成员,以便向 DataContractSerializer 指示要序列化的内容。

namespace DataContractSerializerExample
{
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.Runtime.Serialization;
    using System.Xml;

    // You must apply a DataContractAttribute or SerializableAttribute
    // to a class to have it serialized by the DataContractSerializer.
    [DataContract(Name = "Customer", Namespace = "http://www.contoso.com")]
    class Person : IExtensibleDataObject
    {
        [DataMember()]
        public string FirstName;
        [DataMember]
        public string LastName;
        [DataMember()]
        public int ID;

        public Person(string newfName, string newLName, int newID)
        {
            FirstName = newfName;
            LastName = newLName;
            ID = newID;
        }

        private ExtensionDataObject extensionData_Value;

        public ExtensionDataObject ExtensionData
        {
            get
            {
                return extensionData_Value;
            }
            set
            {
                extensionData_Value = value;
            }
        }
    }

    public sealed class Test
    {
        private Test() { }

        public static void Main()
        {
            try
            {
                WriteObject("DataContractSerializerExample.xml");
                ReadObject("DataContractSerializerExample.xml");
            }

            catch (SerializationException serExc)
            {
                Console.WriteLine("Serialization Failed");
                Console.WriteLine(serExc.Message);
            }
            catch (Exception exc)
            {
                Console.WriteLine(
                "The serialization operation failed: {0} StackTrace: {1}",
                exc.Message, exc.StackTrace);
            }

            finally
            {
                Console.WriteLine("Press <Enter> to exit....");
                Console.ReadLine();
            }
        }

        public static void WriteObject(string fileName)
        {
            Console.WriteLine(
                "Creating a Person object and serializing it.");
            Person p1 = new Person("Zighetti", "Barbara", 101);
            FileStream writer = new FileStream(fileName, FileMode.Create);
            DataContractSerializer ser =
                new DataContractSerializer(typeof(Person));
            ser.WriteObject(writer, p1);
            writer.Close();
        }

        public static void ReadObject(string fileName)
        {
            Console.WriteLine("Deserializing an instance of the object.");
            FileStream fs = new FileStream(fileName,
            FileMode.Open);
            XmlDictionaryReader reader =
                XmlDictionaryReader.CreateTextReader(fs, new XmlDictionaryReaderQuotas());
            DataContractSerializer ser = new DataContractSerializer(typeof(Person));

            // Deserialize the data and read it from the instance.
            Person deserializedPerson =
                (Person)ser.ReadObject(reader, true);
            reader.Close();
            fs.Close();
            Console.WriteLine(String.Format("{0} {1}, ID: {2}",
            deserializedPerson.FirstName, deserializedPerson.LastName,
            deserializedPerson.ID));
        }
    }
' You must apply a DataContractAttribute or SerializableAttribute
' to a class to have it serialized by the DataContractSerializer.
<DataContract(Name := "Customer", [Namespace] := "http://www.contoso.com")>  _
Class Person
    Implements IExtensibleDataObject
    <DataMember()>  _
    Public FirstName As String
    <DataMember()>  _
    Public LastName As String
    <DataMember()>  _
    Public ID As Integer
    
    Public Sub New(ByVal newfName As String, ByVal newLName As String, ByVal newID As Integer) 
        FirstName = newfName
        LastName = newLName
        ID = newID
    End Sub 
    
    Private extensionData_Value As ExtensionDataObject
    
    Public Property ExtensionData() As ExtensionDataObject Implements _
       IExtensibleDataObject.ExtensionData
        Get
            Return extensionData_Value
        End Get
        Set
            extensionData_Value = value
        End Set
    End Property
End Class 


NotInheritable Public Class Test
    
    Private Sub New() 
    
    End Sub 
     
    Public Shared Sub Main() 
        Try
            WriteObject("DataContractSerializerExample.xml")
            ReadObject("DataContractSerializerExample.xml")
        
        Catch serExc As SerializationException
            Console.WriteLine("Serialization Failed")
            Console.WriteLine(serExc.Message)
        Catch exc As Exception
            Console.WriteLine("The serialization operation failed: {0} StackTrace: {1}", exc.Message, exc.StackTrace)
        
        Finally
            Console.WriteLine("Press <Enter> to exit....")
            Console.ReadLine()
        End Try
    End Sub 
    
    Public Shared Sub WriteObject(ByVal fileName As String) 
        Console.WriteLine("Creating a Person object and serializing it.")
        Dim p1 As New Person("Zighetti", "Barbara", 101)
        Dim writer As New FileStream(fileName, FileMode.Create)
        Dim ser As New DataContractSerializer(GetType(Person))
        ser.WriteObject(writer, p1)
        writer.Close()
    End Sub 

    Public Shared Sub ReadObject(ByVal fileName As String) 
        Console.WriteLine("Deserializing an instance of the object.")
        Dim fs As New FileStream(fileName, FileMode.Open)
        Dim reader As XmlDictionaryReader = _
            XmlDictionaryReader.CreateTextReader(fs, New XmlDictionaryReaderQuotas())
        Dim ser As New DataContractSerializer(GetType(Person))
        
        ' Deserialize the data and read it from the instance.
        Dim deserializedPerson As Person = CType(ser.ReadObject(reader, True), Person)
        reader.Close()
        fs.Close()
        Console.WriteLine(String.Format("{0} {1}, ID: {2}", deserializedPerson.FirstName, deserializedPerson.LastName, deserializedPerson.ID))
    End Sub 
End Class

注解

使用 DataContractSerializer 类可以将类型实例序列化和反序列化为 XML 流或文档。 例如,可以使用包含重要数据(如名称和地址)的属性创建一个名为 Person 的类型。 然后,可以创建和操作一个 Person 类实例,并在 XML 文档中写入所有其属性值以便于以后检索,或者在 XML 流中写入这些值以立即进行传输。 最重要的是,DataContractSerializer用于序列化和反序列化在 Windows Communication Foundation (WCF) 消息中发送的数据。 通过将 DataContractAttribute 属性 (Attribute) 应用于类,而将 DataMemberAttribute 属性 (Attribute) 应用于类成员,可以指定要序列化的属性 (Property) 和字段。

有关可序列化的类型的列表,请参阅 数据协定序列化程序支持的类型

要使用 DataContractSerializer,请先创建一个类实例和适于写入或读取格式的对象;例如 XmlDictionaryWriter 实例。 然后调用 WriteObject 方法以保留数据。 要检索数据,请创建一个适于读取数据格式的对象(如 XML 文档的 XmlDictionaryReader),然后调用 ReadObject 方法。

有关使用 DataContractSerializer的详细信息,请参阅 序列化和反序列化

可以使用客户端应用程序配置文件中的 dataContractSerializer 元素设置数据协定序列化程序<>的类型。

准备序列化或反序列化类

DataContractSerializerDataContractAttributeDataMemberAttribute 类结合使用。 要准备序列化某个类,请将 DataContractAttribute 应用于该类。 对于返回要序列化的数据的类的每个成员,请应用 DataMemberAttribute。 您可以序列化字段和属性,而无论其可访问性级别是什么:private、protected、internal、protected internal 或 public。

例如,您的架构指定具有 Customer 属性的 ID,但现有应用程序已使用一个名为 Person 且具有 Name 属性的类型。 要创建一个符合协定的类型,请先将 DataContractAttribute 应用于该类。 然后,将 DataMemberAttribute 应用于每个要序列化的字段或属性。

备注

可以将 DataMemberAttribute 同时应用于私有和公共成员。

XML 的最终格式不需要为文本。 相反,DataContractSerializer 以 XML infoset 形式写入数据,这样,即可以 XmlReaderXmlWriter 可识别的任意格式写入数据。 建议您使用 XmlDictionaryReaderXmlDictionaryWriter 类读取和写入数据,因为这两个类都经过优化可与 DataContractSerializer 一起使用。

如果要创建具有在序列化或反序列化发生前必须填充的字段或属性的类,请使用回调属性,如 版本容错序列化回调中所述。

添加到已知类型的集合中

在序列化或反序列化对象时,DataContractSerializer 必须“已知”该类型。 首先,创建一个实现 IEnumerable<T>(如 List<T>)的类实例,并将已知类型添加到集合中。 然后,使用接受 DataContractSerializer(例如,IEnumerable<T>)的重载之一创建 DataContractSerializer(Type, IEnumerable<Type>) 的实例。

备注

与其他基元类型不同, DateTimeOffset 结构默认不是已知类型,因此必须手动将其添加到已知类型列表中, (请参阅 数据协定已知类型) 。

向前兼容性

DataContractSerializer 理解旨在与将来版本保持兼容的数据协定。 这些类型实现了 IExtensibleDataObject 接口。 此接口具有 ExtensionData 属性,该属性返回 ExtensionDataObject 对象。 有关详细信息,请参阅向前兼容的数据协定

在部分信任模式下运行

在反序列化期间实例化目标对象时,DataContractSerializer 不调用目标对象的构造函数。 如果创作可从部分信任 (访问的 [DataContract] 类型,该类型是公共 AllowPartiallyTrustedCallers 的,并且程序集中应用了属性) ,并且执行某些与安全相关的操作,则必须注意不会调用构造函数。 特别是,下面的方法无效:

  • 如果尝试通过将构造函数指定为内部或私有或者将 LinkDemand 添加到构造函数中来限制部分信任访问;在部分信任模式下进行反序列化期间,这两种方法都没有任何效果。

  • 如果编码的类假定构造函数已运行,该类可能会进入一种可被利用的无效内部状态。

构造函数

DataContractSerializer(Type)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。

DataContractSerializer(Type, DataContractSerializerSettings)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型和设置的对象。

DataContractSerializer(Type, IEnumerable<Type>)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象以及可在对象图中呈现的已知类型的集合。

DataContractSerializer(Type, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、图中要序列化的最大项数、指定忽略意外数据的参数、是否使用非标准的 XML 结构来保留对象引用数据以及自定义序列化的代理项。

DataContractSerializer(Type, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate, DataContractResolver)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、图中要序列化的最大项数、要忽略意外数据的参数、是否使用非标准的 XML 构造来保留图中的对象引用数据、自定义序列化的代理项以及在运行时映射 xsi:type 声明的备选方法。

DataContractSerializer(Type, String, String)

使用提供的 XML 根元素和命名空间初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。

DataContractSerializer(Type, String, String, IEnumerable<Type>)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还在两个字符串参数中指定根 XML 元素和命名空间,并指定了可在对象图中呈现的已知类型的列表。

DataContractSerializer(Type, String, String, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、图中要序列化的最大项数、指定忽略意外数据的参数、是否使用非标准的 XML 结构来保留对象引用数据、自定义序列化的代理项以及包含内容的 XML 元素和命名空间。

DataContractSerializer(Type, String, String, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate, DataContractResolver)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、图中要序列化的最大项数、要忽略意外数据的参数、是否使用非标准的 XML 构造来保留在图中的对象引用数据、自定义序列化的代理项、包含内容的 XML 元素和命名空间以及在运行时映射 xsi:type 声明的备选方法。

DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString)

使用通过类型为 DataContractSerializer 的参数指定的 XML 根元素和命名空间初始化 XmlDictionaryString 类的新实例,以便序列化或反序列化指定类型的对象。

DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString, IEnumerable<Type>)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还在两个 XmlDictionaryString 参数中指定根 XML 元素和命名空间,并指定了可在对象图中呈现的已知类型的列表。

DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、要序列化的最大图项数、指定忽略意外数据的参数、是否使用非标准的 XML 结构来保留对象引用数据、自定义序列化的代理项以及指定包含内容的 XML 元素和命名空间的 XmlDictionaryString 参数。

DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate, DataContractResolver)

初始化 DataContractSerializer 类的新实例,以便序列化或反序列化指定类型的对象。 此方法还指定了可在对象图中呈现的已知类型的列表、图中要序列化的最大项数、要忽略意外数据的参数、是否使用非标准的 XML 构造来保留图中的对象引用数据、自定义序列化的代理项、指定包含内容的 XML 元素和命名空间的 XmlDictionaryString 参数以及在运行时映射 xsi:type 声明的备选方法。

属性

DataContractResolver

获取用于动态将 xsi:type 声明映射到已知协定类型的组件。

DataContractSurrogate

获取一个可扩展序列化或反序列化过程的代理项类型。

IgnoreExtensionDataObject

获取一个值,指定在对类进行序列化或反序列化时是否忽略类扩展提供的数据。

KnownTypes

获取一个类型集合,这些类型可能出现在使用此 DataContractSerializer 实例序列化的对象图中。

MaxItemsInObjectGraph

获取对象图中要序列化或反序列化的最大项数。

PreserveObjectReferences

获取一个值,指定是否使用非标准的 XML 结构来保留对象引用数据。

SerializeReadOnlyTypes

获取指定只读类型是否序列化的值。

方法

Equals(Object)

确定指定对象是否等于当前对象。

(继承自 Object)
GetHashCode()

作为默认哈希函数。

(继承自 Object)
GetType()

获取当前实例的 Type

(继承自 Object)
IsStartObject(XmlDictionaryReader)

确定是否将 XmlDictionaryReader 定位在可反序列化的对象上。

IsStartObject(XmlReader)

确定是否将 XmlReader 定位在可反序列化的对象上。

MemberwiseClone()

创建当前 Object 的浅表副本。

(继承自 Object)
ReadObject(Stream)

使用 Stream 读取 XML 流或文档,然后返回反序列化的对象。

(继承自 XmlObjectSerializer)
ReadObject(XmlDictionaryReader)

使用 XmlDictionaryReader 读取 XML 文档或流,然后返回反序列化的对象。

(继承自 XmlObjectSerializer)
ReadObject(XmlDictionaryReader, Boolean)

使用 XmlDictionaryReader 读取 XML 流并返回反序列化的对象,并且还指定在读取其值之前是否进行检查以验证对象名称。

ReadObject(XmlDictionaryReader, Boolean, DataContractResolver)

读取一个 XML 文档或文档流,并返回反序列化的对象。 此方法包括用于指定是否验证对象名称的参数和用于在运行时映射 xsi:type 声明的解析器。

ReadObject(XmlReader)

使用 XmlReader 读取 XML 流,并返回反序列化的对象。

ReadObject(XmlReader, Boolean)

使用 XmlReader 读取 XML 流并返回反序列化的对象,并且还指定在读取其值之前是否进行检查以验证对象名称。

ToString()

返回表示当前对象的字符串。

(继承自 Object)
WriteEndObject(XmlDictionaryWriter)

使用 XmlDictionaryWriter 写入结束 XML 元素。

WriteEndObject(XmlWriter)

使用 XmlWriter 写入结束 XML 元素。

WriteObject(Stream, Object)

使用指定的 Stream 将对象的完整内容(开始、内容和结束)写入 XML 文档或流。

(继承自 XmlObjectSerializer)
WriteObject(XmlDictionaryWriter, Object)

使用指定的 XmlDictionaryWriter 将对象的完整内容(开始、内容和结束)写入 XML 文档或流。

(继承自 XmlObjectSerializer)
WriteObject(XmlDictionaryWriter, Object, DataContractResolver)

使用指定的 XmlDictionaryWriter 将所有对象数据(开始 XML 元素、内容和结束元素)写入 XML 文档或流。 此方法包含用于在运行时映射 xsi:type 声明的解析器。

WriteObject(XmlWriter, Object)

使用 XmlWriter 将所有对象数据(开始 XML 元素、内容和结束元素)写入 XML 文档或流。

WriteObjectContent(XmlDictionaryWriter, Object)

使用 XmlDictionaryWriter 写入 XML 内容。

WriteObjectContent(XmlWriter, Object)

使用 XmlWriter 写入 XML 内容。

WriteStartObject(XmlDictionaryWriter, Object)

使用 XmlDictionaryWriter 写入开始 XML 元素。

WriteStartObject(XmlWriter, Object)

使用 XmlWriter 写入开始 XML 元素。

扩展方法

GetSerializationSurrogateProvider(DataContractSerializer)

返回用于此序列化程序的代理项序列化提供程序。

SetSerializationSurrogateProvider(DataContractSerializer, ISerializationSurrogateProvider)

指定用于此 DataContractSerializer 的代理项序列化提供程序。

适用于

线程安全性

此类的实例是线程安全的,除非实例与或的DataContractResolver实现IDataContractSurrogate一起使用。

另请参阅