DataContractSerializer Класс

Ссылка

Определение

Пространство имен:: System.Runtime.Serialization

Сборка:: System.Runtime.Serialization.Xml.dll

Сборка:: System.Runtime.Serialization.dll

Сборка:: netstandard.dll

Важно!

Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

Сериализует и десериализует экземпляр типа в 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

Наследование: Object

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 для сохранения данных. Для извлечения данных создайте объект, соответствующий чтению формата данных (аналогичный XmlDictionaryReader для XML-документа) и вызовите метод ReadObject.

Дополнительные сведения об использовании см. в разделе Сериализация и десериализация DataContractSerializer.

Тип сериализатора контракта данных можно задать с помощью <элемента dataContractSerializer> в файле конфигурации клиентского приложения.

Подготовка классов к сериализации и десериализации

DataContractSerializer используется совместно с классами DataContractAttribute и DataMemberAttribute. Чтобы подготовить класс к сериализации, примените к нему атрибут DataContractAttribute. Примените атрибут DataMemberAttribute к каждому члену класса, возвращающему данные, которые требуется сериализовать. Можно сериализовать поля и свойства вне зависимости от специальных возможностей: закрытые, защищенные, внутренние, защищенные внутренние или открытые.

Например, схема задает тип Customer со свойством ID; уже существует приложение, использующее тип Person со свойством Name. Чтобы создать тип, соответствующий контракту, вначале примените к классу атрибут DataContractAttribute. Затем примените атрибут DataMemberAttribute ко всем сериализуемым полям или свойствам.

Примечание

Атрибут DataMemberAttribute можно применять как к закрытым, так и к защищенным элементам.

Окончательный формат XML не обязательно должен быть текстовым. DataContractSerializer записывает данные в информационный набор XML, позволяющий записывать данные в любом формате, распознаваемом XmlReader и XmlWriter. Для чтения и записи рекомендуется использовать классы XmlDictionaryReader и XmlDictionaryWriter, так как они оптимизированы для работы с 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)	Инициализирует новый экземпляр класса 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 для выполнения сериализации или десериализации объекта указанного типа с помощью предоставленных корневых элемента и пространства имен XML, заданных посредством параметров типа XmlDictionaryString.
DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString, IEnumerable<Type>)	Инициализирует новый экземпляр класса DataContractSerializer для сериализации или десериализации объекта указанного типа. Этот метод также задает корневые XML-элемент и пространство имен в двух параметрах XmlDictionaryString, а также список известных типов, которые могут присутствовать в графе объекта.
DataContractSerializer(Type, XmlDictionaryString, XmlDictionaryString, IEnumerable<Type>, Int32, Boolean, Boolean, IDataContractSurrogate)	Инициализирует новый экземпляр класса DataContractSerializer для сериализации или десериализации объекта указанного типа. Этот метод также задает список известных типов, которые могут присутствовать в графе объекта; максимальное количество сериализуемых элементов графа; параметры, указывающие, пропускать ли непредвиденные данные, использовать ли нестандартные конструкции XML для сохранения данных ссылок на объект в графе и использовать ли суррогат для пользовательской сериализации; а также параметры XmlDictionaryString, задающие XML-элемент и пространство имен, в которых находится содержимое.
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)	Считывает XML-поток или XML-документ с помощью средства чтения Stream и возвращает десериализованный объект. (Унаследовано от XmlObjectSerializer)
ReadObject(XmlDictionaryReader)	Считывает XML-документ или XML-поток с помощью средства чтения XmlDictionaryReader и возвращает десериализованный объект. (Унаследовано от XmlObjectSerializer)
ReadObject(XmlDictionaryReader, Boolean)	Считывает XML-поток с помощью средства чтения XmlDictionaryReader и возвращает десериализованный объект; также указывает, была ли выполнена проверка имени объекта перед чтением его значения.
ReadObject(XmlDictionaryReader, Boolean, DataContractResolver)	Считывает XML-документ или поток XML-документов и возвращает десериализованный объект. Метод включает параметр, определяющий, проверяется ли имя объекта, и сопоставитель для сопоставления объявлений `xsi:type` во время выполнения.
ReadObject(XmlReader)	Считывает XML-поток с помощью средства чтения XmlReader и возвращает десериализованный объект.
ReadObject(XmlReader, Boolean)	Считывает XML-поток с помощью средства чтения XmlReader и возвращает десериализованный объект; также указывает, была ли выполнена проверка имени объекта перед чтением его значения.
ToString()	Возвращает строку, представляющую текущий объект. (Унаследовано от Object)
WriteEndObject(XmlDictionaryWriter)	Выполняет запись закрывающего XML-элемента с помощью средства записи XmlDictionaryWriter.
WriteEndObject(XmlWriter)	Выполняет запись закрывающего XML-элемента с помощью средства записи XmlWriter.
WriteObject(Stream, Object)	Записывает полное содержимое объекта (начало записи, запись содержимого и завершение записи) в XML-документ или поток с помощью указанного средства записи Stream. (Унаследовано от XmlObjectSerializer)
WriteObject(XmlDictionaryWriter, Object)	Записывает полное содержимое объекта (начало записи, запись содержимого и завершение записи) в XML-документ или поток с помощью указанного средства записи XmlDictionaryWriter. (Унаследовано от XmlObjectSerializer)
WriteObject(XmlDictionaryWriter, Object, DataContractResolver)	Записывает все данные объекта (начиная с XML-элемента, содержимого и включающего элемента) в XML-документ или поток с помощью указанного xmlDictionaryWriter. Метод включает сопоставитель для сопоставления объявлений `xsi:type` во время выполнения.
WriteObject(XmlWriter, Object)	Записывает все данные объекта (начальный XML-элемент, содержимое и закрывающий элемент) в XML-документ или поток с помощью средства записи XmlWriter.
WriteObjectContent(XmlDictionaryWriter, Object)	Выполняет запись содержимого XML с помощью средства записи XmlDictionaryWriter.
WriteObjectContent(XmlWriter, Object)	Выполняет запись содержимого XML с помощью средства записи XmlWriter.
WriteStartObject(XmlDictionaryWriter, Object)	Выполняет запись открывающего XML-элемента с помощью модуля записи XmlDictionaryWriter.
WriteStartObject(XmlWriter, Object)	Выполняет запись открывающего XML-элемента с помощью модуля записи XmlWriter.

Методы расширения

GetSerializationSurrogateProvider(DataContractSerializer)	Возвращает суррогатный поставщик сериализации для этого сериализатора.
SetSerializationSurrogateProvider(DataContractSerializer, ISerializationSurrogateProvider)	Указывает суррогатный поставщик сериализации для этого DataContractSerializer.

Применяется к

Потокобезопасность

Экземпляры этого класса являются потокобезопасными, за исключением случаев, когда экземпляр используется с реализацией IDataContractSurrogate или DataContractResolver.