シリアル化のガイドラインSerialization guidelines

このドキュメントには、シリアル化できるように API をデザインする際に考慮すべきガイドラインを示します。This document lists the guidelines to consider when designing an API to be serialized.

警告

バイナリ シリアル化は危険です。Binary serialization can be dangerous. 信頼できないソースからのデータの逆シリアル化、および管理下にないシステムへのラウンドトリップのシリアル化をしてはいけません。Never deserialize data from an untrusted source and never round-trip serialized data to systems not under your control.

.NET には、さまざまなシリアル化シナリオに合わせて最適化できる 3 つの主なシリアル化テクノロジがあります。.NET offers three main serialization technologies that are optimized for various serialization scenarios. これらのテクノロジ、およびテクノロジに関連した主な .NET 型を次の表に示します。The following table lists these technologies and the main .NET types related to these technologies.

テクノロジTechnology 関連するクラスRelevant Classes メモNotes
データ コントラクトのシリアル化Data Contract Serialization DataContractAttribute

DataMemberAttribute

DataContractSerializer

NetDataContractSerializer

DataContractJsonSerializer

ISerializable
永続化全般General persistence

Web サービスWeb Services

JSONJSON
XML シリアル化XML Serialization XmlSerializer XML 形式XML format
フル コントロールwith full control
ランタイム シリアル化 (バイナリおよび SOAP)Runtime -Serialization (Binary and SOAP) SerializableAttribute

ISerializable

BinaryFormatter

SoapFormatter
.NET リモート処理.NET Remoting

新しい型をデザインする際は、新しい型でどのテクノロジをサポートするかを決める必要があります。When you design new types, you should decide which, if any, of these technologies those types need to support. 次のガイドラインでその選択方法とサポートの提供方法について説明します。The following guidelines describe how to make that choice and how to provide such support. このガイドラインは、アプリケーションまたはライブラリの実装時に使用するシリアル化テクノロジを決定するためのものではありません。These guidelines are not meant to help you choose which serialization technology you should use in the implementation of your application or library. そのようなガイドラインは API のデザインには直接関係ないため、このトピックのスコープの範囲外となります。Such guidelines are not directly related to API design and thus are not within the scope of this topic.

ガイドラインGuidelines

  • 新しい型をデザインする際にはシリアル化について考えてください。DO think about serialization when you design new types.

    シリアル化は、プログラムで型のインスタンスを永続化または変換しなければならないことがあるため、どのような型においてもデザイン上の重要な考慮事項です。Serialization is an important design consideration for any type, because programs might need to persist or transmit instances of the type.

サポートする適切なシリアル化テクノロジの選択Choosing the right serialization technology to support

任意の型で 0、または 1 つ以上のシリアル化テクノロジをサポートできます。Any given type can support none, one, or more of the serialization technologies.

  • 使用する型のインスタンスを Web サービスで永続化させる、または使用する必要がある場合は、データ コントラクトのシリアル化をサポートすることを検討してください。CONSIDER supporting data contract serialization if instances of your type might need to be persisted or used in Web Services.

  • 型をシリアル化したときに作成される XML 形式の制御を強化する必要がある場合は、データ コントラクトのシリアル化の代わり、またはこれに加えて XML シリアル化をサポートすることを検討してください。CONSIDER supporting the XML serialization instead of or in addition to data contract serialization if you need more control over the XML format that is produced when the type is serialized.

    これは、データ コントラクトのシリアル化でサポートされていない XML 構築を使用して XML 属性を作成するような一部の相互運用シナリオで必要になることがあります。This may be necessary in some interoperability scenarios where you need to use an XML construct that is not supported by data contract serialization, for example, to produce XML attributes.

  • 使用する型のインスタンスが .NET リモート処理境界を超えて移動する必要がある場合は、ランタイムのシリアル化をサポートすることを検討してください。CONSIDER supporting runtime serialization if instances of your type need to travel across .NET Remoting boundaries.

  • 一般的な永続化のためにランタイムのシリアル化や XML のシリアル化をサポートしないでください。AVOID supporting runtime serialization or XML serialization just for general persistence reasons. データ コントラクトのシリアル化を優先的に使用してください。Prefer data contract serialization instead

データ コントラクトのシリアル化のサポートSupporting data contract serialization

DataContractAttribute を型に適用し、DataMemberAttribute をその型のメンバー (フィールドおよびプロパティ) に適用することによって、型でデータ コントラクトのシリアル化をサポートすることができます。Types can support data contract serialization by applying the DataContractAttribute to the type and the DataMemberAttribute to the members (fields and properties) of the type.

[DataContract]
class Person
{

    [DataMember]
    string LastName { get; set; }
    [DataMember]
    string FirstName { get; set; }

    public Person(string firstNameValue, string lastNameValue)
    {
        FirstName = firstNameValue;
        LastName = lastNameValue;
    }
}

<DataContract()> Public Class Person
    <DataMember()> Public Property LastName As String
    <DataMember()> Public Property FirstName As String

    Public Sub New(ByVal firstNameValue As String, ByVal lastNameValue As String)
        FirstName = firstNameValue
        LastName = lastNameValue
    End Sub

End Class
  1. 型を部分信頼で使用する場合は、型のデータ メンバーをパブリックにすることを検討してください。CONSIDER marking data members of your type public if the type can be used in partial trust. 完全な信頼では、データ コントラクト シリアライザーでパブリックではない型とメンバーのシリアル化と逆シリアル化を行うことが可能ですが、部分信頼の場合、パブリック メンバーのみをシリアル化および逆シリアル化できます。In full trust, data contract serializers can serialize and deserialize nonpublic types and members, but only public members can be serialized and deserialized in partial trust.

  2. Data-MemberAttribute を持つすべてのプロパティに getter と setter を実装してください。DO implement a getter and setter on all properties that have Data-MemberAttribute. データ コントラクト シリアライザーでは、この型の getter と setter の両方がシリアル化可能と見なされる必要があります。Data contract serializers require both the getter and the setter for the type to be considered serializable. 型を部分信頼で使用しない場合は、1 つまたは両方のプロパティ アクセサーを非パブリックにできます。If the type won’t be used in partial trust, one or both of the property accessors can be nonpublic.

    [DataContract]
    class Person2
    {
    
        string lastName;
        string firstName;
    
        public Person2(string firstName, string lastName)
        {
            this.lastName = lastName;
            this.firstName = firstName;
        }
    
        [DataMember]
        public string LastName
        { 
            // Implement get and set.
            get { return lastName; }
            private set { lastName = value; }
    
        }
    
        [DataMember]
        public string FirstName
        {
            // Implement get and set.
            get { return firstName; }
            private set { firstName = value; }
        }
    }
    
    <DataContract()> Class Person2
        Private lastNameValue As String
        Private firstNameValue As String
    
        Public Sub New(ByVal firstName As String, ByVal lastName As String)
            Me.lastNameValue = lastName
            Me.firstNameValue = firstName
        End Sub
    
        <DataMember()> Property LastName As String
            Get
                Return lastNameValue
            End Get
    
            Set(ByVal value As String)
                lastNameValue = value
            End Set
    
        End Property
    
        <DataMember()> Property FirstName As String
            Get
                Return firstNameValue
    
            End Get
            Set(ByVal value As String)
                firstNameValue = value
            End Set
        End Property
    
    End Class
    
  3. 逆シリアル化されたインスタンスの初期化には、シリアル化コールバックを使用することを検討してください。CONSIDER using the serialization callbacks for initialization of deserialized instances.

    オブジェクトの逆シリアル化時にはコンストラクターは呼び出されません。Constructors are not called when objects are deserialized. このため、通常の構築時に実行されるすべてのロジックは、シリアル化のコールバックの 1 つとして実装する必要があります。Therefore, any logic that executes during normal construction needs to be implemented as one of the serialization callbacks.

    [DataContract]
    class Person3
    {
        [DataMember]
        string lastName;
        [DataMember]
        string firstName;
        string fullName;
    
        public Person3(string firstName, string lastName)
        {
            // This constructor is not called during deserialization.
            this.lastName = lastName;
            this.firstName = firstName;
            fullName = firstName + " " + lastName;
        }
    
        public string FullName
        {
            get { return fullName; }
        }
    
        // This method is called after the object 
        // is completely deserialized. Use it instead of the
        // constructror.
        [OnDeserialized] 
        void OnDeserialized(StreamingContext context)
        {
            fullName = firstName + " " + lastName;
        }
    }
    
    <DataContract()> _
    Class Person3
        <DataMember()> Private lastNameValue As String
        <DataMember()> Private firstNameValue As String
        Dim fullNameValue As String
    
        Public Sub New(ByVal firstName As String, ByVal lastName As String)
            lastNameValue = lastName
            firstNameValue = firstName
            fullNameValue = firstName & " " & lastName
        End Sub
    
        Public ReadOnly Property FullName As String
            Get
                Return fullNameValue
            End Get
        End Property
    
        <OnDeserialized()> Sub OnDeserialized(ByVal context As StreamingContext)
            fullNameValue = firstNameValue & " " & lastNameValue
        End Sub
    End Class
    

    OnDeserializedAttribute 属性は最もよく使用されるコールバック属性です。The OnDeserializedAttribute attribute is the most commonly used callback attribute. ファミリの他の属性には、OnDeserializingAttributeThe other attributes in the family are OnDeserializingAttribute,
    OnSerializingAttribute、およびOnSerializedAttributeします。OnSerializingAttribute, and OnSerializedAttribute. これらを使用して、逆シリアル化前、シリアル化前、およびシリアル化後に実行されるコールバックをマークすることができます。They can be used to mark callbacks that get executed before deserialization, before serialization, and finally, after serialization, respectively.

  4. 複雑なオブジェクト グラフを逆シリアル化する場合は、使用する具象型を示す KnownTypeAttribute を使用することを検討してください。CONSIDER using the KnownTypeAttribute to indicate concrete types that should be used when deserializing a complex object graph.

    たとえば、逆シリアル化されたデータ メンバーの型を抽象クラスで表す場合、シリアライザーはインスタンス化してメンバーに割り当てる具象型を判断するために、既知の型の情報が必要になります。For example, if a type of a deserialized data member is represented by an abstract class, the serializer will need the known type information to decide what concrete type to instantiate and assign to the member. 属性を使用して既知の型を指定しない場合、明示的にシリアライザーに渡す (既知の型をシリアライザーのコンストラクターに渡します) か、構成ファイルで指定する必要があります。If the known type is not specified using the attribute, it will need to be passed to the serializer explicitly (you can do it by passing known types to the serializer constructor) or it will need to be specified in the configuration file.

    // The KnownTypeAttribute specifies types to be
    // used during serialization.
    [KnownType(typeof(USAddress))]
    [DataContract]
    class Person4
    {
    
        [DataMember]
        string fullNameValue;
        [DataMember]
        Address address; // Address is abstract
    
        public Person4(string fullName, Address address)
        {
            this.fullNameValue = fullName;
            this.address = address;
        }
    
        public string FullName
        {
            get { return fullNameValue; }
        }
    }
    
    [DataContract]
    public abstract class Address
    {
        public abstract string FullAddress { get; }
    }
    
    [DataContract]
    public class USAddress : Address
    {
    
        [DataMember]
        public string Street { get; set; }
        [DataMember]
        public string City { get; set; }
        [DataMember]
        public string State { get; set; }
        [DataMember]
        public string ZipCode { get; set; }
    
        public override string FullAddress
        {
            get
            {
                return Street + "\n" + City + ", " + State + " " + ZipCode;
            }
        }
    }
    
    <KnownType(GetType(USAddress)), _
    DataContract()> Class Person4
        <DataMember()> Property fullNameValue As String
        <DataMember()> Property addressValue As USAddress ' Address is abstract
    
        Public Sub New(ByVal fullName As String, ByVal address As Address)
            fullNameValue = fullName
            addressValue = address
        End Sub
    
        Public ReadOnly Property FullName() As String
            Get
                Return fullNameValue
            End Get
    
        End Property
    End Class
    
    <DataContract()> Public MustInherit Class Address
        Public MustOverride Function FullAddress() As String
    End Class
    
    <DataContract()> Public Class USAddress
        Inherits Address
        <DataMember()> Public Property Street As String
        <DataMember()> Public City As String
        <DataMember()> Public State As String
        <DataMember()> Public ZipCode As String
    
        Public Overrides Function FullAddress() As String
            Return Street & "\n" & City & ", " & State & " " & ZipCode
        End Function
    End Class
    

    既知の型のリストが静的にわからない場合 (Person クラスをコンパイルした場合)、KnownTypeAttribute で実行時に既知の型の一覧を返すメソッドを指すこともできます。In cases where the list of known types is not known statically (when the Person class is compiled), the KnownTypeAttribute can also point to a method that returns a list of known types at runtime.

  5. シリアル化可能な型を作成または変更する場合は、上位互換性と下位互換性を考慮してください。DO consider backward and forward compatibility when creating or changing serializable types.

    シリアル化した型の将来のバージョンは、現在のバージョンの型に逆シリアル化でき、その逆も可能であることを念頭に置いてください。Keep in mind that serialized streams of future versions of your type can be deserialized into the current version of the type, and vice versa. 明示的なパラメーターを使用してデータ コントラクト属性にコントラクトを保存する特別な措置を取らない限り、データ メンバーはプライベートで内部データであっても、型の将来のバージョンで名前、型、順序を変更することはできないことを理解しておいてください。シリアル化可能な型に変更を加えるときは、シリアル化の互換性をテストしてください。Make sure you understand that data members, even private and internal, cannot change their names, types, or even their order in future versions of the type unless special care is taken to preserve the contract using explicit parameters to the data contract attributes.Test compatibility of serialization when making changes to serializable types. 新しいバージョンを古いバージョンに逆シリアル化したり、その逆も試してみてください。Try deserializing the new version into an old version, and vice versa.

  6. 異なるバージョンの型の間でラウンドトリッピングができるように、IExtensibleDataObject インターフェイスを実装することを検討してください。CONSIDER implementing IExtensibleDataObject interface to allow round-tripping between different versions of the type.

    インターフェイスを使用すると、ラウンドトリッピングの間にデータが失われないようにシリアライザーで確認することができます。The interface allows the serializer to ensure that no data is lost during round-tripping. ExtensionData プロパティにより、現在のバージョンでは未知の、将来使用される型の任意のデータが格納されます。The ExtensionData property stores any data from the future version of the type that is unknown to the current version. 現在のバージョンを後で将来のバージョンにシリアル化または逆シリアル化するときに、ExtensionData プロパティ値を通じて、シリアル化されたストリーム内で追加データを使用できます。When the current version is subsequently serialized and deserialized into a future version, the additional data will be available in the serialized stream through the ExtensionData property value.

    // Implement the IExtensibleDataObject interface.
    [DataContract]
    class Person5 : IExtensibleDataObject
    {
        ExtensionDataObject serializationData;
        [DataMember]
        string fullNameValue;
    
        public Person5(string fullName)
        {
            this.fullNameValue = fullName;
        }
    
        public string FullName
        {
            get { return fullNameValue; }
        }
                
        ExtensionDataObject IExtensibleDataObject.ExtensionData
        {
            get 
            {                 
                return serializationData; 
            }
            set { serializationData = value; }
        }
    }
    
    <DataContract()> Class Person5
        Implements IExtensibleDataObject
        <DataMember()> Dim fullNameValue As String
    
        Public Sub New(ByVal fullName As String)
            fullName = fullName
        End Sub
    
        Public ReadOnly Property FullName
            Get
                Return fullNameValue
            End Get
        End Property
        Private serializationData As ExtensionDataObject
        Public Property ExtensionData As ExtensionDataObject Implements IExtensibleDataObject.ExtensionData
            Get
                Return serializationData
            End Get
            Set(ByVal value As ExtensionDataObject)
                serializationData = value
            End Set
        End Property
    End Class
    

    詳細については、「上位互換性のあるデータ コントラクト」を参照してください。For more information, see Forward-Compatible Data Contracts.

XML シリアル化のサポートSupporting XML serialization

データ コントラクトのシリアル化は .NET Framework の主な (既定の) シリアル化テクノロジですが、データ コントラクトのシリアル化ではサポートされないシリアル化シナリオがあります。Data contract serialization is the main (default) serialization technology in the .NET Framework, but there are serialization scenarios that data contract serialization does not support. たとえば、シリアライザーによって作成または使用された XML の形状は完全に制御できません。For example, it does not give you full control over the shape of XML produced or consumed by the serializer. そのような微調整が必要な場合は、XML シリアル化を使用する必要があり、このシリアル化テクノロジをサポートする型を自分でデザインする必要があります。If such fine control is required, XML serialization has to be used, and you need to design your types to support this serialization technology.

  1. 作成された XML の形状を制御しなければならない強力な理由がない限り、XML シリアル化のために特別に型をデザインすることは避けてください。AVOID designing your types specifically for XML Serialization, unless you have a very strong reason to control the shape of the XML produced. このシリアル化テクノロジは、前のセクションで説明したデータ コントラクトのシリアル化よりも優先されます。This serialization technology has been superseded by the Data Contract Serialization discussed in the previous section.

    言い換えれば、XML シリアル化で使用する型であることがわかっている場合を除き、System.Xml.Serialization 名前空間の属性を新しい型に適用しないでください。In other words, don’t apply attributes from the System.Xml.Serialization namespace to new types, unless you know that the type will be used with XML Serialization. System.Xml.Serialization を使用して、作成された XML の形状を制御する方法を次の例に示します。The following example shows how System.Xml.Serialization can be used to control the shape of the XML -produced.

    public class Address2
    {
        [System.Xml.Serialization.XmlAttribute] // Serialize as XML attribute, instead of an element.
        public string Name { get { return "Poe, Toni"; } set { } }
        [System.Xml.Serialization.XmlElement(ElementName = "StreetLine")] // Explicitly name the element.
        public string Street = "1 Main Street";        
    }
    
    Public Class Address2
        ' Supports XML Serialization.
        <System.Xml.Serialization.XmlAttribute()> _
        Public ReadOnly Property Name As String ' Serialize as XML attribute, instead of an element.
            Get
                Return "Poe, Toni"
            End Get
        End Property
        <System.Xml.Serialization.XmlElement(ElementName:="StreetLine")> _
        Public Street As String = "1 Main Street"  ' Explicitly names the element 'StreetLine'.
    End Class
    
  2. XML シリアル化属性を適用することで提供される、シリアル化された XML の形状をより細かく制御する場合は、IXmlSerializable インターフェイスを実装することを検討してください。CONSIDER implementing the IXmlSerializable interface if you want even more control over the shape of the serialized XML than what’s offered by applying the XML Serialization attributes. 2 つのメソッド、インターフェイスのReadXmlWriteXmlを使用するシリアル化された XML ストリームを完全に制御できます。Two methods of the interface, ReadXml and WriteXml, allow you to fully control the serialized XML stream. また、XmlSchemaProviderAttribute 属性を適用することで、その型用に生成される XML スキーマを制御することもできます。You can also control the XML schema that gets generated for the type by applying the XmlSchemaProviderAttribute attribute.

ランタイム シリアル化のサポートSupporting runtime serialization

ランタイム シリアル化は .NET リモート処理で使用されるテクノロジです。Runtime serialization is a technology used by .NET Remoting. .NET リモート処理を使用して型を変換する場合、ランタイム シリアル化がサポートされていることを確認する必要があります。If you think your types will be transported using .NET Remoting, you need to make sure they support runtime serialization.

ランタイム シリアル化の基本的なサポートは SerializableAttribute 属性を適用して提供できますが、より高度なシナリオでは単純なランタイム シリアル化可能パターンの実装 (-ISerializable を実装してシリアル化コンストラクターを指定) が必要になります。The basic support for runtime serialization can be provided by applying the SerializableAttribute attribute, and more advanced scenarios involve implementing a simple runtime serializable pattern (implement -ISerializable and provide a serialization constructor).

  1. 使用する型で .NET リモート処理を使用する場合は、ランタイムのシリアル化をサポートすることを検討してください。CONSIDER supporting runtime serialization if your types will be used with .NET Remoting. たとえば、System.AddIn 名前空間は .NET リモート処理を使用するため、System.AddIn アドイン間で交換されるすべての型でランタイム シリアル化をサポートする必要があります。For example, the System.AddIn namespace uses .NET Remoting, and so all types exchanged between System.AddIn add-ins need to support runtime serialization.

    // Apply SerializableAttribute to support runtime serialization.
    [Serializable]
    public class Person6 
    {
        // Code not shown.
    }
    
    <Serializable()> Public Class Person6 ' Support runtime serialization with the SerializableAttribute.
    
        ' Code not shown.
    End Class
    
  2. シリアル化プロセスを完全制御する場合は、ランタイム シリアル化可能パターンを実装することを検討してください。CONSIDER implementing the runtime serializable pattern if you want complete control over the serialization process. たとえば、シリアル化または逆シリアル化されたデータを変換したいとします。For example, if you want to transform data as it gets serialized or deserialized.

    パターンは単純です。The pattern is very simple. 必要な作業は、ISerializable インターフェイスを実装し、オブジェクトを逆シリアル化するときに使用する特別なコンストラクターを指定するだけです。All you need to do is implement the ISerializable interface and provide a special constructor that is used when the object is deserialized.

    // Implement the ISerializable interface for more control.
    [Serializable]
    public class Person_Runtime_Serializable : ISerializable
    {
        string fullName;
    
        public Person_Runtime_Serializable() { }
        protected Person_Runtime_Serializable(SerializationInfo info, StreamingContext context){
            if (info == null) throw new System.ArgumentNullException("info");
            fullName = (string)info.GetValue("name", typeof(string));
        }
        [SecurityPermission(SecurityAction.LinkDemand,
        Flags = SecurityPermissionFlag.SerializationFormatter)]
        void ISerializable.GetObjectData(SerializationInfo info,
                StreamingContext context) {
            if (info == null) throw new System.ArgumentNullException("info");
            info.AddValue("name", fullName);
        }
    
        public string FullName
        {
            get { return fullName; }
            set { fullName = value; }
        }
    }
    
    ' Implement the ISerializable interface for more control.
    <Serializable()> Public Class Person_Runtime_Serializable
        Implements ISerializable
    
        Private fullNameValue As String
    
        Public Sub New()
            ' empty constructor.
        End Sub
        Protected Sub New(ByVal info As SerializationInfo, _
                          ByVal context As StreamingContext)
            If info Is Nothing Then
                Throw New System.ArgumentNullException("info")
                FullName = CType(info.GetValue("name", GetType(String)), String)
            End If
        End Sub
    
        Private Sub GetObjectData(ByVal info As SerializationInfo, _
                                  ByVal context As StreamingContext) _
                              Implements ISerializable.GetObjectData
            If info Is Nothing Then
                Throw New System.ArgumentNullException("info")
                info.AddValue("name", FullName)
            End If
        End Sub
    
        Public Property FullName As String
    
            Get
                Return fullNameValue
            End Get
            Set(ByVal value As String)
                fullNameValue = value
    
            End Set
        End Property
    
    End Class
    
    
  3. このサンプルに示すように、シリアル化コンストラクターを保護し、型と名前を指定した 2 つのパラメーターを用意してください。DO make the serialization constructor protected and provide two parameters typed and named exactly as shown in the sample here.

    protected Person_Runtime_Serializable(SerializationInfo info, StreamingContext context){
    
    Protected Sub New(ByVal info As SerializationInfo, _
                      ByVal context As StreamingContext)
    
  4. ISerializable メンバーを明示的に実装してください。DO implement the ISerializable members explicitly.

    void ISerializable.GetObjectData(SerializationInfo info,
            StreamingContext context) {
    
    Private Sub GetObjectData(ByVal info As SerializationInfo, _
                              ByVal context As StreamingContext) _
                          Implements ISerializable.GetObjectData
    
  5. ISerializable.GetObjectData の実装にはリンク確認要求を適用してください。DO apply a link demand to ISerializable.GetObjectData implementation. こうすることで、完全に信頼できるコア、およびランタイムのシリアライザーだけがメンバーにアクセスできるようになります。This ensures that only fully trusted core and the runtime serializer have access to the member.

    [SecurityPermission(SecurityAction.LinkDemand,
    Flags = SecurityPermissionFlag.SerializationFormatter)]
    
    <Serializable()> Public Class Person_Runtime_Serializable2
        Implements ISerializable
        <SecurityPermission(SecurityAction.LinkDemand, Flags:=SecurityPermissionFlag.SerializationFormatter)> _
        Private Sub GetObjectData(ByVal info As System.Runtime.Serialization.SerializationInfo, _
                                 ByVal context As System.Runtime.Serialization.StreamingContext) _
                             Implements System.Runtime.Serialization.ISerializable.GetObjectData
            ' Code not shown.
        End Sub
    End Class
    

関連項目See also