發行項
11/17/2011

DataContractAttribute Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Specifies that the type defines or implements a data contract and can be serialized by a serializer, such as the DataContractSerializer.

Inheritance Hierarchy

System.Object
System.Attribute
System.Runtime.Serialization.DataContractAttribute

Namespace: System.Runtime.Serialization
Assembly: System.Runtime.Serialization (in System.Runtime.Serialization.dll)

Syntax

'Declaration
<AttributeUsageAttribute(AttributeTargets.Class Or AttributeTargets.Struct Or AttributeTargets.Enum, Inherited := False,  _
    AllowMultiple := False)> _
Public NotInheritable Class DataContractAttribute _
    Inherits Attribute

[AttributeUsageAttribute(AttributeTargets.Class|AttributeTargets.Struct|AttributeTargets.Enum, Inherited = false, 
    AllowMultiple = false)]
public sealed class DataContractAttribute : Attribute

The DataContractAttribute type exposes the following members.

Constructors

	Name	Description
	DataContractAttribute	Initializes a new instance of the DataContractAttribute class.

Top

Properties

	Name	Description
	IsReference	Gets or sets a value that indicates whether to preserve object reference data.
	Name	Gets or sets the name of the data contract for the type.
	Namespace	Gets or sets the namespace for the data contract for the type.

Top

Methods

	Name	Description
	Equals	Infrastructure. Returns a value that indicates whether this instance is equal to a specified object. (Inherited from Attribute.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Returns the hash code for this instance. (Inherited from Attribute.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Match	When overridden in a derived class, returns a value that indicates whether this instance equals a specified object. (Inherited from Attribute.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. If you send or receive messages by using the Silverlight 5 infrastructure, you can also apply the DataContractAttribute to any classes that hold and manipulate data sent in messages.

You should also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Silverlight 5 also supports a simplified opt-out model for serialization, where these attributes can be omitted from the type and the members of the type to be serialized. The data contract is implicit in the sense that the visibility modifiers (public, private) used by the type determines whether it and its members are included in the data contract. In this model, the name of a member is used to identify it in the serialized representation. A new IgnoreDataMemberAttribute attribute can be used to opt-out a member that is public when required.

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. For example, the data contract might call for a data type named Person that has two text fields, named FirstName and LastName. 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.

Note:
A data contract differs significantly from an actual interface in its inheritance behavior. Interfaces are inherited by any derived types. 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. However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

A data contract differs significantly from an actual interface in its inheritance behavior. Interfaces are inherited by any derived types. 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. However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Reusing Existing Types

A data contract has two basic requirements:

A stable name.
A list of members.

The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. 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. You can override the defaults by setting the Name and Namespace properties. 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.

Note:
In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Examples

    ' Define the data contract.
    <DataContract(Name := "Customer", Namespace := "https://www.contoso.com", IsReference := True)> _
    Public Class User
        Private privateName As String
        <DataMember(Name := "Last", EmitDefaultValue := True, IsRequired := True, Order := 2)> _
        Public Property Name() As String
            Get
                Return privateName
            End Get
            Set(ByVal value As String)
                privateName = value
            End Set
        End Property

        Private privateAge As Integer
        <DataMember(Order := 1)> _
        Public Property Age() As Integer
            Get
                Return privateAge
            End Get
            Set(ByVal value As Integer)
                privateAge = value
            End Set
        End Property

        Public Sub New()
        End Sub

        Public Sub New(ByVal newName As String, ByVal newAge As Integer)
            Name = newName
            Age = newAge
        End Sub
    End Class

// Define the data contract.
[DataContract(Name = "Customer", Namespace = "https://www.contoso.com", IsReference = true)]
public class User
{
    [DataMember(Name = "Last", EmitDefaultValue = true, IsRequired = true, Order = 2)]
    public string Name { get; set; }

    [DataMember(Order = 1)]
    public int Age { get; set; }

    public User() { }

    public User(string newName, int newAge)
    {
        Name = newName;
        Age = newAge;
    }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

共用方式為