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 屬性套用至類別,並將 DataMemberAttribute 屬性套用至類別成員,即可指定已序列化的屬性和欄位。

如需可序列化的型別清單,請參閱 資料合約序列化程式支援的類型

如果要使用 DataContractSerializer,請先建立類別的執行個體,以及適合用於寫入或讀取此格式的物件;例如,XmlDictionaryWriter 的執行個體。 接著,呼叫 WriteObject 方法以保留資料。 如果要擷取資料,請建立適合用於讀取此資料格式的物件 (例如適合 XML 文件的 XmlDictionaryReader),接著呼叫 ReadObject 方法。

如需使用 DataContractSerializer 的詳細資訊,請參閱 序列化和還原序列化

您可以使用用戶端應用程式組態檔中的dataContractSerializer > 元素,設定資料合約序列化程式的 < 型別。

準備類別以進行序列化或還原序列化

DataContractSerializer 會組合 DataContractAttributeDataMemberAttribute 類別一起使用。 如果要準備類別以進行序列化,請將 DataContractAttribute 套用至此類別。 對於每個會傳回您要序列化之資料的類別成員,請套用 DataMemberAttribute。 您可以序列化欄位和屬性,不論其存取範圍為何:private、protected、internal、protected internal 或 public。

例如,您的結構描述指定含有 Customer 屬性的 ID,但是您的現有應用程式是使用名為 Person 且具有 Name 屬性的型別。 如果要建立符合該合約的型別,請先將 DataContractAttribute 套用至類別。 然後將 DataMemberAttribute 套用至要序列化的每個欄位或屬性。

注意

您可以將 DataMemberAttribute 同時套用至 Private 和 Public 成員。

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 套用屬性的元件中) ,而且會執行某些安全性相關動作,您必須注意不會呼叫建構函式。 特別值得一提的是,下列技巧將無法運作:

  • 如果您嘗試透過將建構函式設為 internal 或 private,或是將 LinkDemand 新增至建構函式等方式來限制部分信任存取,上述這些方式都無法在部分信任環境中的還原序列化期間發揮作用。

  • 如果您撰寫的類別程式碼會假定該建構函式已經執行,則此類別可能會處於易遭利用的無效 internal 狀態。

建構函式

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)

初始化 DataContractSerializer 類別的新執行個體,以便序列化或還原序列化已指定型別的物件 (該型別會使用提供的 XML 根項目和命名空間)。

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 類別的新執行個體,以便序列化或還原序列化所指定型別的物件 (該型別會使用透過型別 XmlDictionaryString 之參數所指定的 XML 根項目和命名空間)。

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 建構來保存圖形中的物件參考資料、自訂序列化的代理、XmlDictionaryString 的參數 (會指定 XML 項目和包含內容的命名空間),以及在執行階段對應 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 使用時除外。

另請參閱