属性を使用した XML シリアル化の制御Controlling XML Serialization Using Attributes

属性を使用すると、オブジェクトの XML シリアル化を制御したり、同じ一連のクラスから代替 XML ストリームを作成したりできます。Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. 代替 XML ストリームを作成する方法の詳細については、次を参照してください。方法。XML Stream の代替要素名を指定します。For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

注意

XML が生成される必要があります、World Wide Web Consortium (W3C) ドキュメントのセクション 5 に準拠しているかどうかは簡易オブジェクト アクセス プロトコル (SOAP) 1.1に記載の属性を使用して属性をコントロールでエンコードされた SOAPシリアル化します。If the XML generated must conform to section 5 of the World Wide Web Consortium (W3C) document titled Simple Object Access Protocol (SOAP) 1.1, use the attributes listed in Attributes That Control Encoded SOAP Serialization.

既定では、クラス名またはメンバー名によって XML 要素名が決まります。By default, an XML element name is determined by the class or member name. 次の例に示すように、Book という名前の単純なクラスでは、ISBN という名前のフィールドから <ISBN> という XML 要素タグが生成されます。In a simple class named Book, a field named ISBN will produce an XML element tag <ISBN>, as shown in the following example.

Public Class Book
    Public ISBN As String
End Class
' When an instance of the Book class is serialized, it might
' produce this XML:
' <ISBN>1234567890</ISBN>.
public class Book
{
    public string ISBN;
}
// When an instance of the Book class is serialized, it might
// produce this XML:
// <ISBN>1234567890</ISBN>.

この既定の動作を変更して、要素に新しい名前を付けることもできます。This default behavior can be changed if you want to give the element a new name. 次のコードでは、ElementNameXmlElementAttribute プロパティを設定することにより、属性でこの変更を実現する方法を示します。The following code shows how an attribute enables this by setting the ElementName property of a XmlElementAttribute.

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class
public class TaxRates {
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

属性の詳細については、「属性」を参照してください。For more information about attributes, see Attributes. XML シリアル化を制御する属性の一覧については、「Attributes That Control XML Serialization」(XML シリアル化を制御する属性) を参照してください。For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

配列のシリアル化の制御Controlling Array Serialization

XmlArrayAttribute 属性および XmlArrayItemAttribute 属性は、配列のシリアル化を制御できるようにデザインされています。The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. これらの属性を使用して制御できます要素名、名前空間、および XML スキーマ (XSD) データ型 (「World Wide Web Consortium [www.w3.org] ドキュメントで定義されている"XML Schema Part 2。データ型")。Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). また、配列に挿入できる型も指定できます。You can also specify the types that can be included in an array.

XmlArrayAttribute は、配列をシリアル化すると生成される外側の XML 要素のプロパティを決定します。The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. たとえば、次に示す配列をシリアル化すると、既定で Employees という名前の XML 要素が生成されます。For example, by default, serializing the array below will result in an XML element named Employees. この Employees 要素は、Employee 配列型に基づいた名前の一連の要素で構成されます。The Employees element will contain a series of elements named after the array type Employee.

Public Class Group
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class
public class Group {
    public Employee[] Employees;
}
public class Employee {
    public string Name;
}

シリアル化されたインスタンスは次のようになります。A serialized instance might resemble the following.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</Employees>
</Group>

XmlArrayAttribute を適用すると、この XML 要素の名前を次のように変更できます。By applying a XmlArrayAttribute, you can change the name of the XML element, as follows.

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class
public class Group {
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

その結果、次のような XML が生成されます。The resulting XML might resemble the following.

<Group>
<TeamMembers>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</TeamMembers>
</Group>

一方、XmlArrayItemAttribute は、配列内の項目をシリアル化する方法を制御します。The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. この属性は、配列を返すフィールドに適用されます。Note that the attribute is applied to the field returning the array.

Public Class Group
    <XmlArrayItem("MemberName")> _
    Public Employee() As Employees
End Class
public class Group {
    [XmlArrayItem("MemberName")]
    public Employee[] Employees;
}

その結果、次のような XML が生成されます。The resulting XML might resemble the following.

<Group>
<Employees>
    <MemberName>Haley</MemberName>
</Employees>
</Group>

派生クラスのシリアル化Serializing Derived Classes

XmlArrayItemAttribute のもう 1 つの用途は、派生クラスをシリアル化することです。Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. たとえば、Manager から派生した Employee という名前の別のクラスを、前の例に追加できます。For example, another class named Manager that derives from Employee can be added to the previous example. XmlArrayItemAttribute を適用しないと、この派生クラス型が認識されないため、実行時にコードが失敗します。If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. これを回避するには、この属性を 2 回適用し、受け入れ可能な各型 (基本型と派生型) の Type プロパティをそれぞれ設定します。To remedy this, apply the attribute twice, each time setting the Type property for each acceptable type (base and derived).

Public Class Group
    <XmlArrayItem(Type:=GetType(Employee)), _
    XmlArrayItem(Type:=GetType(Manager))> _
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class
Public Class Manager
Inherits Employee
    Public Level As Integer
End Class
public class Group {
    [XmlArrayItem(Type = typeof(Employee)),
    XmlArrayItem(Type = typeof(Manager))]
    public Employee[] Employees;
}
public class Employee {
    public string Name;
}
public class Manager:Employee {
    public int Level;
}

シリアル化されたインスタンスは次のようになります。A serialized instance might resemble the following.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
    <Employee xsi:type = "Manager">
        <Name>Ann</Name>
        <Level>3</Level>
    <Employee>
</Employees>
</Group>

要素のシーケンスとしての配列のシリアル化Serializing an Array as a Sequence of Elements

次の例に示すように、配列を返すフィールドに XmlElementAttribute を適用して、配列を XML 要素のフラットなシーケンスとしてシリアル化することもできます。You can also serialize an array as a flat sequence of XML elements by applying a XmlElementAttribute to the field returning the array as follows.

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class
public class Group {
    [XmlElement]
    public Employee[] Employees;
}

シリアル化されたインスタンスは次のようになります。A serialized instance might resemble the following.

<Group>
<Employees>
    <Name>Haley</Name>
</Employees>
<Employees>
    <Name>Noriko</Name>
</Employees>
<Employees>
    <Name>Marco</Name>
</Employees>
</Group>

2 つの XML ストリームを区別するもう 1 つの方法は、XML スキーマ定義ツールを使用して、コンパイル済みのコードから XML スキーマ (XSD) ドキュメント ファイルを生成することです Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (ツールの使用の詳細については、「The XML Schema Definition Tool and XML Serialization」(XML スキーマ定義ツールと XML シリアル化) を参照してください)。フィールドに属性を適用しないと、スキーマには次のように要素が記述されます。(For more details on using the tool, see The XML Schema Definition Tool and XML Serialization.) When no attribute is applied to the field, the schema describes the element in the following manner.

<xs:element minOccurs="0" maxOccurs ="1" name="Employees" type="ArrayOfEmployee" />

フィールドに XmlElementAttribute を適用すると、生成されたスキーマには次のように要素が記述されます。When the XmlElementAttribute is applied to the field, the resulting schema describes the element as follows.

<xs:element minOccurs="0" maxOccurs="unbounded" name="Employees" type="Employee" /> 

ArrayList のシリアル化Serializing an ArrayList

ArrayList クラスには、さまざまなオブジェクトのコレクションを含めることができます。The ArrayList class can contain a collection of diverse objects. このため、ArrayList は配列とほとんど同じように使用できます。You can therefore use a ArrayList much as you use an array. 型指定されたオブジェクトの配列を返すフィールドを作成する代わりに、単一の ArrayList を返すフィールドを作成することもできます。Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. ただし、配列の場合と同様に、XmlSerializer に含まれるオブジェクトの型を ArrayList に通知する必要があります。However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. そのためには、次の例に示すように、XmlElementAttribute の複数のインスタンスをフィールドに割り当てます。To accomplish this, assign multiple instances of the XmlElementAttribute to the field, as shown in the following example.

Public Class Group
    <XmlElement(Type:=GetType(Employee)), _
    XmlElement(Type:=GetType(Manager))> _
    Public Info As ArrayList
End Class
public class Group {
    [XmlElement(Type = typeof(Employee)), 
    XmlElement(Type = typeof(Manager))]
    public ArrayList Info;
}

XmlRootAttribute と XmlTypeAttribute を使用したクラスのシリアル化の制御Controlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

クラスのみに適用できる、XmlRootAttributeXmlTypeAttribute という属性があります。There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. この 2 つの属性は非常に似ています。These attributes are very similar. XmlRootAttribute は、シリアル化されたときに XML ドキュメントの開始要素と終了要素、つまりルート要素を表す 1 つのクラスにのみ適用できます。The XmlRootAttribute can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. 一方 XmlTypeAttribute は、ルート クラスを含む任意のクラスに適用できます。The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

たとえば、前の例では、Group クラスがルート クラスであり、そのすべてのパブリック フィールドとパブリック プロパティは、XML ドキュメント内の XML 要素になります。For example, in the previous examples, the Group class is the root class, and all its public fields and properties become the XML elements found in the XML document. したがって、存在するルート クラスは 1 つだけです。Therefore, there can be only one root class. XmlRootAttribute を適用することで、XmlSerializer によって生成される XML ストリームを制御できます。By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. たとえば、要素名や名前空間を変更できます。For example, you can change the element name and namespace.

XmlTypeAttribute を使用すると、生成される XML のスキーマを制御できます。The XmlTypeAttribute allows you to control the schema of the generated XML. この機能は、XML Web サービスを通じてスキーマを公開する必要がある場合に役立ちます。This capability is useful when you need to publish the schema through an XML Web service. 次の例では、XmlTypeAttributeXmlRootAttribute の両方を同じクラスに適用しています。The following example applies both the XmlTypeAttribute and the XmlRootAttribute to the same class.

<XmlRoot("NewGroupName"), _
XmlType("NewTypeName")> _
Public Class Group
    Public Employees() As Employee
End Class
[XmlRoot("NewGroupName")]
[XmlType("NewTypeName")]
public class Group {
    public Employee[] Employees;
}

このクラスをコンパイルし、XML スキーマ定義ツールを使用してそのスキーマを生成すると、Group を記述する次の XML が生成されます。If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing Group.

<xs:element name="NewGroupName" type="NewTypeName">

これに対し、クラスのインスタンスをシリアル化した場合は、XML ドキュメントに NewGroupName のみが生成されます。In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

XmlIgnoreAttribute によるシリアル化の回避Preventing Serialization with the XmlIgnoreAttribute

パブリック プロパティやパブリック フィールドをシリアル化する必要がない場合があります。There might be situations when a public property or field does not need to be serialized. たとえば、メタデータの格納に使用しているフィールドまたはプロパティの場合、For example, a field or property could be used to contain metadata. XmlIgnoreAttribute を適用すると、XmlSerializer がそのフィールドまたはプロパティをスキップします。In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

関連項目See also