DataContractAttribute DataContractAttribute DataContractAttribute DataContractAttribute Class

Определение

Указывает, что тип определяет или реализует контракт данных и может быть сериализован сериализатором, таким как DataContractSerializer.Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Чтобы сделать тип сериализуемым, авторы типа должны определить для него контракт данных.To make their type serializable, type authors must define a data contract for their type.

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
type DataContractAttribute = class
    inherit Attribute
Public NotInheritable Class DataContractAttribute
Inherits Attribute
Наследование
DataContractAttributeDataContractAttributeDataContractAttributeDataContractAttribute
Атрибуты

Примеры

В приведенном ниже примере выполняется сериализация и десериализация класса Person, к которому был применен атрибут DataContractAttribute.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Обратите внимание, что свойствам Namespace и Name были заданы значения, переопределяющие параметры по умолчанию.Note that the Namespace and Name properties have been set to values that override the default settings.

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.Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. При отправке или получении сообщений с помощью инфраструктуры Windows Communication Foundation (WCF) также следует применять DataContractAttribute к любым классам, содержащим данные, отправляемые в сообщениях и обрабатывающих их.If you send or receive messages by using the Windows Communication Foundation (WCF) infrastructure, you should also apply the DataContractAttribute to any classes that hold and manipulate data sent in messages. Дополнительные сведения о контрактах данных см. в разделе Использование контрактов данных.For more information about data contracts, see Using Data Contracts.

Также необходимо применить атрибут DataMemberAttribute ко всем полям, свойствам или событиям, содержащим сериализуемые значения.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Применение атрибута DataContractAttribute явно разрешает DataContractSerializer выполнять сериализацию и десериализацию данных.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Внимание!

Атрибут DataMemberAttribute можно применять к закрытым полям.You can apply the DataMemberAttribute to private fields. Необходимо помнить, что возвращаемые полем данные (даже если поле закрытое) сериализуются и десериализуются, и, следовательно, могут быть просмотрены или перехвачены злоумышленником или процессом.Be aware that the data returned by the field (even if it is private) is serialized and deserialized, and thus can be viewed or intercepted by a malicious user or process.

Дополнительные сведения о контрактах данных см. в разделах, перечисленных в разделе использование контрактов данных.For more information about data contracts, see the topics listed in Using Data Contracts.

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

Контракт данных — это абстрактное описание набора полей с именем и типом данных для каждого поля.A data contract is an abstract description of a set of fields with a name and data type for each field. Контракт данных существует вне любых реализаций, что делает возможным взаимодействие служб на разных платформах.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Поскольку данные, передаваемые между службами, соответствуют одному и тому же контракту, все службы могут обработать данные.As long as the data passed between the services conforms to the same contract, all the services can process the data. Эта обработка также называется слабо связанной системой.This processing is also known as a loosely coupled system. Контракт данных похож на интерфейс в том, что контракт указывает, каким образом должны подаваться данные, чтобы они могли быть обработаны приложением.A data contract is also similar to an interface in that the contract specifies how data must be delivered so that it can be processed by an application. Например, контракт данных может вызвать тип данных "Person", имеющий два текстовых поля "FirstName" и "LastName".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Чтобы создать контракт данных, примените атрибут DataContractAttribute к классу и атрибут DataMemberAttribute ко всем полям или свойствам, которые требуется сериализовать.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. После сериализации данные соответствуют контракту данных, неявно встроенному в этот тип.When serialized, the data conforms to the data contract that is implicitly built into the type.

Примечание

Поведение контракта данных при наследовании существенно отличается от поведения реального интерфейса.A data contract differs significantly from an actual interface in its inheritance behavior. Интерфейсы наследуются любыми производными типами.Interfaces are inherited by any derived types. Если применить атрибут DataContractAttribute к базовому классу, производные типы не будут наследовать атрибут или поведение.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Но если у производного типа есть контракт данных, элементы данных базового класса сериализуются.However, if a derived type has a data contract, the data members of the base class are serialized. Однако необходимо применить атрибут DataMemberAttribute к новым членам производного класса, чтобы сделать их сериализуемыми.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Документы схемы XML и средство SvcUtilXML Schema Documents and the SvcUtil Tool

При обмене данными с другими службами необходимо описать контракт данных.If you are exchanging data with other services, you must describe the data contract. Чтобы определить контракты данных для текущей версии DataContractSerializer, можно использовать схему XML.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (Для этой же цели могут использоваться другие формы описания/метаданных.) Чтобы создать схему XML из приложения, используйте средство служебной программы метаданных ServiceModel (Svcutil. exe) с параметром командной строки /дконли .(Other forms of metadata/description could be used for the same purpose.) To create an XML schema from your application, use the ServiceModel Metadata Utility Tool (Svcutil.exe) with the /dconly command line option. Если на вход средства передана сборка, по умолчанию средство создает набор схем XML, определяющий все типы контрактов данных этой сборки.When the input to the tool is an assembly, by default, the tool generates a set of XML schemas that define all the data contract types found in that assembly. И наоборот, можно использовать средство Svcutil.exe для создания определений классов Visual Basic или C#, соответствующих требованиям схем XML, использующих конструкторы, которые могут быть выражены посредством контрактов данных.Conversely, you can also use the Svcutil.exe tool to create Visual Basic or C# class definitions that conform to the requirements of XML schemas that use constructs that can be expressed by data contracts. В этом случае параметр командной строки /дконли не требуется.In this case, the /dconly command line option is not required.

Если на вход средства Svcutil.exe передана схема XML, по умолчанию средство создает набор классов.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. При рассмотрении этих классов можно заметить, что был применен атрибут DataContractAttribute.If you examine those classes, you find that the DataContractAttribute has been applied. Эти классы можно использовать для создания нового приложения обработки данных, которыми требуется обмениваться с другими службами.You can use those classes to create a new application to process data that must be exchanged with other services.

Также можно запустить средство для конечной точки, возвращающей документ языка описания веб-служб (WSDL), который автоматически создает код и конфигурацию для создания клиента Windows Communication Foundation (WCF).You can also run the tool against an endpoint that returns a Web Services Description Language (WSDL) document to automatically generate the code and configuration to create an Windows Communication Foundation (WCF) client. Созданный код включает типы, отмеченные атрибутом DataContractAttribute.The generated code includes types that are marked with the DataContractAttribute.

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

Существует два основных требования контракта данных: наличие постоянного имени и наличие списка элементов.A data contract has two basic requirements: a stable name and a list of members. Постоянное имя состоит из универсального кода ресурса (URI) пространства имен и локального имени контракта.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. По умолчанию при применении DataContractAttribute к классу используется имя класса в качестве локального имени и пространства имен класса (с "http://schemas.datacontract.org/2004/07/"префиксом) в качестве URI пространства имен.By default, when you apply the DataContractAttribute to a class, it uses the class name as the local name and the class's namespace (prefixed with "http://schemas.datacontract.org/2004/07/") as the namespace URI. Значения по умолчанию можно переопределить, задав свойства Name и Namespace.You can override the defaults by setting the Name and Namespace properties. Можно также изменить пространство имен, применив атрибут ContractNamespaceAttribute к пространству имен.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Используйте эту возможность, когда существует тип, обрабатывающий данные необходимым образом, но его пространство имен и имя класса отличаются от контракта данных.Use this capability when you have an existing type that processes data exactly as you require but has a different namespace and class name from the data contract. Переопределив значения по умолчанию, можно повторно использовать этот существующий тип и обеспечить соответствие сериализованных данных контракту данных.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Примечание

В любом коде можно использовать слово DataContract вместо длинного DataContractAttribute.In any code, you can use the word DataContract instead of the longer DataContractAttribute.

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

Контракт данных также может размещать свои более поздние версии.A data contract can also accommodate later versions of itself. То есть в случае, когда более поздняя версия контракта включает дополнительные данные, эти данные хранятся и возвращаются отправителю без изменений.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. Для этого реализуйте интерфейс IExtensibleDataObject.To do this, implement the IExtensibleDataObject interface.

Дополнительные сведения об управлении версиями см. в разделе Управление версиями контракта данных.For more information about versioning, see Data Contract Versioning.

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

DataContractAttribute() DataContractAttribute() DataContractAttribute() DataContractAttribute()

Инициализирует новый экземпляр класса DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Свойства

IsNameSetExplicitly IsNameSetExplicitly IsNameSetExplicitly IsNameSetExplicitly

Получает значение, указывающее, был ли объект Name задан явно.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly IsNamespaceSetExplicitly IsNamespaceSetExplicitly IsNamespaceSetExplicitly

Получает значение, указывающее, был ли объект Namespace задан явно.Gets whether Namespace has been explicitly set.

IsReference IsReference IsReference IsReference

Возвращает или задает значение, указывающее, следует ли сохранять данные ссылки на объект.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly IsReferenceSetExplicitly IsReferenceSetExplicitly IsReferenceSetExplicitly

Получает значение, указывающее, был ли объект IsReference задан явно.Gets whether IsReference has been explicitly set.

Name Name Name Name

Возвращает или задает имя для контракта данных типа.Gets or sets the name of the data contract for the type.

Namespace Namespace Namespace Namespace

Возвращает или задает пространство имен для контракта данных типа.Gets or sets the namespace for the data contract for the type.

TypeId TypeId TypeId TypeId

При реализации в производном классе возвращает уникальный идентификатор для этого Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Inherited from Attribute)

Методы

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Возвращает значение, показывающее, равен ли экземпляр указанному объекту.Returns a value that indicates whether this instance is equal to a specified object.

(Inherited from Attribute)
GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Возвращает хэш-код данного экземпляра.Returns the hash code for this instance.

(Inherited from Attribute)
GetType() GetType() GetType() GetType()

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

(Inherited from Object)
IsDefaultAttribute() IsDefaultAttribute() IsDefaultAttribute() IsDefaultAttribute()

При переопределении в производном классе указывает, является ли значение этого экземпляра значением по умолчанию для производного класса.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Inherited from Attribute)
Match(Object) Match(Object) Match(Object) Match(Object)

При переопределении в производном классе возвращает значение, указывающее, является ли этот экземпляр равным заданному объекту.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Inherited from Attribute)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

(Inherited from Object)
ToString() ToString() ToString() ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

(Inherited from Object)

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

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

Сопоставляет набор имен соответствующему набору идентификаторов диспетчеризации.Maps a set of names to a corresponding set of dispatch identifiers.

(Inherited from Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Возвращает сведения о типе объекта, которые можно использовать для получения сведений о типе интерфейса.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Inherited from Attribute)
_Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32)

Возвращает количество предоставляемых объектом интерфейсов для доступа к сведениям о типе (0 или 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Inherited from Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Предоставляет доступ к открытым свойствам и методам объекта.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

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

Дополнительно