DataContractAttribute Класс

Определение

Указывает, что тип определяет или реализует контракт данных и может быть сериализован сериализатором, таким как DataContractSerializer. Чтобы сделать тип сериализуемым, авторы типа должны определить для него контракт данных.

public ref class DataContractAttribute sealed : Attribute
[System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Enum | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
public sealed class DataContractAttribute : Attribute
[<System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Enum | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)>]
type DataContractAttribute = class
    inherit Attribute
Public NotInheritable Class DataContractAttribute
Inherits Attribute
Наследование
DataContractAttribute
Атрибуты

Примеры

В приведенном ниже примере выполняется сериализация и десериализация класса Person, к которому был применен атрибут DataContractAttribute. Обратите внимание, что свойствам Namespace и Name были заданы значения, переопределяющие параметры по умолчанию.

namespace DataContractAttributeExample
{
    // Set the Name and Namespace properties to new values.
    [DataContract(Name = "Customer", Namespace = "http://www.contoso.com")]
    class Person : IExtensibleDataObject
    {
        // To implement the IExtensibleDataObject interface, you must also
        // implement the ExtensionData property.
        private ExtensionDataObject extensionDataObjectValue;
        public ExtensionDataObject ExtensionData
        {
            get
            {
                return extensionDataObjectValue;
            }
            set
            {
                extensionDataObjectValue = value;
            }
        }

        [DataMember(Name = "CustName")]
        internal string Name;

        [DataMember(Name = "CustID")]
        internal int ID;

        public Person(string newName, int newID)
        {
            Name = newName;
            ID = newID;
        }
    }

    class Test
    {
        public static void Main()
        {
            try
            {
                WriteObject("DataContractExample.xml");
                ReadObject("DataContractExample.xml");
                Console.WriteLine("Press Enter to end");
                Console.ReadLine();
            }
            catch (SerializationException se)
            {
                Console.WriteLine
                ("The serialization operation failed. Reason: {0}",
                  se.Message);
                Console.WriteLine(se.Data);
                Console.ReadLine();
            }
        }

        public static void WriteObject(string path)
        {
            // Create a new instance of the Person class and
            // serialize it to an XML file.
            Person p1 = new Person("Mary", 1);
            // Create a new instance of a StreamWriter
            // to read and write the data.
            FileStream fs = new FileStream(path,
            FileMode.Create);
            XmlDictionaryWriter writer = XmlDictionaryWriter.CreateTextWriter(fs);
            DataContractSerializer ser =
                new DataContractSerializer(typeof(Person));
            ser.WriteObject(writer, p1);
            Console.WriteLine("Finished writing object.");
            writer.Close();
            fs.Close();
        }
        public static void ReadObject(string path)
        {
            // Deserialize an instance of the Person class
            // from an XML file. First create an instance of the
            // XmlDictionaryReader.
            FileStream fs = new FileStream(path, FileMode.OpenOrCreate);
            XmlDictionaryReader reader =
                XmlDictionaryReader.CreateTextReader(fs, new XmlDictionaryReaderQuotas());

            // Create the DataContractSerializer instance.
            DataContractSerializer ser =
                new DataContractSerializer(typeof(Person));

            // Deserialize the data and read it from the instance.
            Person newPerson = (Person)ser.ReadObject(reader);
            Console.WriteLine("Reading this object:");
            Console.WriteLine(String.Format("{0}, ID: {1}",
            newPerson.Name, newPerson.ID));
            fs.Close();
        }
    }
}
Namespace DataContractAttributeExample
    ' Set the Name and Namespace properties to new values.
    <DataContract(Name := "Customer", [Namespace] := "http://www.contoso.com")>  _
    Class Person
        Implements IExtensibleDataObject
        ' To implement the IExtensibleDataObject interface, you must also
        ' implement the ExtensionData property.
        Private extensionDataObjectValue As ExtensionDataObject 
        
        Public Property ExtensionData() As ExtensionDataObject _
          Implements IExtensibleDataObject.ExtensionData
            Get
                Return extensionDataObjectValue
            End Get
            Set
                extensionDataObjectValue = value
            End Set
        End Property
        
        <DataMember(Name := "CustName")>  _
        Friend Name As String
        
        <DataMember(Name := "CustID")>  _
        Friend ID As Integer
        
        
        Public Sub New(ByVal newName As String, ByVal newID As Integer) 
            Name = newName
            ID = newID
        
        End Sub 
    End Class 
    
    
    Class Test
        
        Public Shared Sub Main() 
            Try
                WriteObject("DataContractExample.xml")
                ReadObject("DataContractExample.xml")
                Console.WriteLine("Press Enter to end")
                Console.ReadLine()
            Catch se As SerializationException
                Console.WriteLine("The serialization operation failed. Reason: {0}", _
                   se.Message)
                Console.WriteLine(se.Data)
                Console.ReadLine()
            End Try
        
        End Sub 
        
        
        Public Shared Sub WriteObject(ByVal path As String) 
            ' Create a new instance of the Person class and 
            ' serialize it to an XML file.
            Dim p1 As New Person("Mary", 1)
            ' Create a new instance of a StreamWriter
            ' to read and write the data.
            Dim fs As New FileStream(path, FileMode.Create)
            Dim writer As XmlDictionaryWriter = XmlDictionaryWriter.CreateTextWriter(fs)
            Dim ser As New DataContractSerializer(GetType(Person))
            ser.WriteObject(writer, p1)
            Console.WriteLine("Finished writing object.")
            writer.Close()
            fs.Close()
        
        End Sub 
        
        Public Shared Sub ReadObject(ByVal path As String) 
            ' Deserialize an instance of the Person class 
            ' from an XML file. First create an instance of the 
            ' XmlDictionaryReader.
            Dim fs As New FileStream(path, FileMode.OpenOrCreate)
            Dim reader As XmlDictionaryReader = XmlDictionaryReader. _
              CreateTextReader(fs, New XmlDictionaryReaderQuotas())
            
            ' Create the DataContractSerializer instance.
            Dim ser As New DataContractSerializer(GetType(Person))
            
            ' Deserialize the data and read it from the instance.
            Dim newPerson As Person = CType(ser.ReadObject(reader), Person)
            Console.WriteLine("Reading this object:")
            Console.WriteLine(String.Format("{0}, ID: {1}", newPerson.Name, newPerson.ID))
            fs.Close()
        
        End Sub 
    End Class 
End Namespace

Комментарии

Применяйте атрибут DataContractAttribute к типам (классам, структурам или перечислениям), используемым в операциях сериализации и десериализации средством DataContractSerializer. при отправке или получении сообщений с помощью инфраструктуры Windows Communication Foundation (WCF) также следует применять DataContractAttribute к любым классам, содержащим данные, отправляемые в сообщениях и обрабатывающих их. Дополнительные сведения о контрактах данных см. в разделе Использование контрактов данных.

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

Внимание!

Атрибут DataMemberAttribute можно применять к закрытым полям. Необходимо помнить, что возвращаемые полем данные (даже если поле закрытое) сериализуются и десериализуются, и, следовательно, могут быть просмотрены или перехвачены злоумышленником или процессом.

Дополнительные сведения о контрактах данных см. в разделах, перечисленных в разделе использование контрактов данных.

Контракты данных

Контракт данных — это абстрактное описание набора полей с именем и типом данных для каждого поля. Контракт данных существует вне любых реализаций, что делает возможным взаимодействие служб на разных платформах. Поскольку данные, передаваемые между службами, соответствуют одному и тому же контракту, все службы могут обработать данные. Эта обработка также называется слабо связанной системой. Контракт данных похож на интерфейс в том, что контракт указывает, каким образом должны подаваться данные, чтобы они могли быть обработаны приложением. Например, контракт данных может вызвать тип данных "Person", имеющий два текстовых поля "FirstName" и "LastName". Чтобы создать контракт данных, примените атрибут DataContractAttribute к классу и атрибут DataMemberAttribute ко всем полям или свойствам, которые требуется сериализовать. После сериализации данные соответствуют контракту данных, неявно встроенному в этот тип.

Примечание

Поведение контракта данных при наследовании существенно отличается от поведения реального интерфейса. Интерфейсы наследуются любыми производными типами. Если применить атрибут DataContractAttribute к базовому классу, производные типы не будут наследовать атрибут или поведение. Но если у производного типа есть контракт данных, элементы данных базового класса сериализуются. Однако необходимо применить атрибут DataMemberAttribute к новым членам производного класса, чтобы сделать их сериализуемыми.

Документы схемы XML и средство SvcUtil

При обмене данными с другими службами необходимо описать контракт данных. Чтобы определить контракты данных для текущей версии DataContractSerializer, можно использовать схему XML. (Другие формы метаданных и описания могут использоваться для той же цели.) Чтобы создать схему XML из приложения, используйте средство служебной программы метаданных ServiceModel (Svcutil.exe) с параметром командной строки /дконли . Если на вход средства передана сборка, по умолчанию средство создает набор схем XML, определяющий все типы контрактов данных этой сборки. И наоборот, можно использовать средство Svcutil.exe для создания определений классов Visual Basic или C#, соответствующих требованиям схем XML, использующих конструкторы, которые могут быть выражены посредством контрактов данных. В этом случае параметр командной строки /дконли не требуется.

Если на вход средства Svcutil.exe передана схема XML, по умолчанию средство создает набор классов. При рассмотрении этих классов можно заметить, что был применен атрибут DataContractAttribute. Эти классы можно использовать для создания нового приложения обработки данных, которыми требуется обмениваться с другими службами.

также можно запустить средство для конечной точки, возвращающей документ языка описания веб-служб (WSDL), который автоматически создает код и конфигурацию для создания клиента Windows Communication Foundation (WCF). Созданный код включает типы, отмеченные атрибутом DataContractAttribute.

Повторное использование существующих типов

Существует два основных требования контракта данных: наличие постоянного имени и наличие списка элементов. Постоянное имя состоит из универсального кода ресурса (URI) пространства имен и локального имени контракта. По умолчанию при применении DataContractAttribute к классу используется имя класса в качестве локального имени и пространства имен класса (с префиксом "http://schemas.datacontract.org/2004/07/" ) в качестве URI пространства имен. Значения по умолчанию можно переопределить, задав свойства Name и Namespace. Можно также изменить пространство имен, применив атрибут ContractNamespaceAttribute к пространству имен. Используйте эту возможность, когда существует тип, обрабатывающий данные необходимым образом, но его пространство имен и имя класса отличаются от контракта данных. Переопределив значения по умолчанию, можно повторно использовать этот существующий тип и обеспечить соответствие сериализованных данных контракту данных.

Примечание

В любом коде можно использовать слово DataContract вместо длинного DataContractAttribute.

Управление версиями

Контракт данных также может размещать свои более поздние версии. То есть в случае, когда более поздняя версия контракта включает дополнительные данные, эти данные хранятся и возвращаются отправителю без изменений. Для этого реализуйте интерфейс IExtensibleDataObject.

Дополнительные сведения об управлении версиями см. в разделе Управление версиями контракта данных.

Конструкторы

DataContractAttribute()

Инициализирует новый экземпляр класса DataContractAttribute.

Свойства

IsNameSetExplicitly

Получает значение, указывающее, был ли объект Name задан явно.

IsNamespaceSetExplicitly

Получает значение, указывающее, был ли объект Namespace задан явно.

IsReference

Возвращает или задает значение, указывающее, следует ли сохранять данные ссылки на объект.

IsReferenceSetExplicitly

Получает значение, указывающее, был ли объект IsReference задан явно.

Name

Возвращает или задает имя для контракта данных типа.

Namespace

Возвращает или задает пространство имен для контракта данных типа.

TypeId

В случае реализации в производном классе возвращает уникальный идентификатор для этого атрибута Attribute.

(Унаследовано от Attribute)

Методы

Equals(Object)

Возвращает значение, показывающее, равен ли экземпляр указанному объекту.

(Унаследовано от Attribute)
GetHashCode()

Возвращает хэш-код данного экземпляра.

(Унаследовано от Attribute)
GetType()

Возвращает объект Type для текущего экземпляра.

(Унаследовано от Object)
IsDefaultAttribute()

При переопределении в производном классе указывает, является ли значение этого экземпляра значением по умолчанию для производного класса.

(Унаследовано от Attribute)
Match(Object)

При переопределении в производном классе возвращает значение, указывающее, является ли этот экземпляр равным заданному объекту.

(Унаследовано от Attribute)
MemberwiseClone()

Создает неполную копию текущего объекта Object.

(Унаследовано от Object)
ToString()

Возвращает строку, представляющую текущий объект.

(Унаследовано от Object)

Явные реализации интерфейса

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

Сопоставляет набор имен соответствующему набору идентификаторов диспетчеризации.

(Унаследовано от Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Возвращает сведения о типе объекта, которые можно использовать для получения сведений о типе интерфейса.

(Унаследовано от Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Возвращает количество предоставляемых объектом интерфейсов для доступа к сведениям о типе (0 или 1).

(Унаследовано от Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Предоставляет доступ к открытым свойствам и методам объекта.

(Унаследовано от Attribute)

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

См. также раздел