Controllo della serializzazione XML mediante attributiControlling XML Serialization Using Attributes

Gli attributi possono essere utilizzati per controllare la serializzazione XML di un oggetto o per creare un flusso XML alternativo dallo stesso set di classi.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. Per altri dettagli sulla creazione di un flusso XML alternativo, vedere Procedura: Specificare un nome di elemento alternativo per un flusso XML.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

Nota

Se il codice XML generato deve essere conforme alla sezione 5 del documento World Wide Web Consortium (W3C) denominato Simple Object Access Protocol (SOAP) 1,1, utilizzare gli attributi elencati negli attributi che controllano la serializzazione SOAP codificata.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.

Per impostazione predefinita, un nome di elemento XML è determinato dal nome della classe o del membro.By default, an XML element name is determined by the class or member name. In una classe semplice denominata Book un campo denominato ISBN produrrà un tag di elemento XML <ISBN>, come illustra l'esempio riportato di seguito.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>.

Questo comportamento predefinito può essere modificato se si vuole assegnare un nuovo nome all'elemento.This default behavior can be changed if you want to give the element a new name. Il codice riportato di seguito mostra il modo in cui un attributo svolge tale funzione impostando la proprietà ElementName di una classe XmlElementAttribute.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;
}

Per altre informazioni sugli attributi, vedere Attributi.For more information about attributes, see Attributes. Per l'elenco degli attributi che controllano la serializzazione XML, vedere Attributi per il controllo della serializzazione XML.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Controllo della serializzazione di matriceControlling Array Serialization

Gli attributi XmlArrayAttribute e XmlArrayItemAttribute sono progettati per controllare la serializzazione delle matrici.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. Tramite l'utilizzo di questi attributi, è possibile controllare il nome dell'elemento, lo spazio dei nomi e tipo di dati XML Schema (XSD) (come definito nel documento intitolato "XML Schema Part 2: Datatypes" del World Wide Web Consortium [www.w3.org]).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"). È inoltre possibile specificare i tipi che possono essere inclusi in una matrice.You can also specify the types that can be included in an array.

XmlArrayAttribute determinerà le proprietà dell'elemento XML di inclusione risultante dalla serializzazione di una matrice.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. Ad esempio, la serializzazione della matrice riportata di seguito, per impostazione predefinita comporterà la creazione di un elemento XML denominato Employees.For example, by default, serializing the array below will result in an XML element named Employees. L'elemento Employees conterrà una serie di elementi denominati dopo il tipo di matrice 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;
}

Un'istanza serializzata potrebbe assomigliare agli elementi seguenti.A serialized instance might resemble the following.

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

Tramite l'applicazione di un attributo XmlArrayAttribute, è possibile modificare il nome dell'elemento XML, come segue.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;
}

L'XML risultante potrebbe assomigliare agli elementi seguenti.The resulting XML might resemble the following.

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

XmlArrayItemAttribute, d'altra parte, controlla il modo in cui vengono serializzati gli elementi contenuti nella matrice.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Notare che l'attributo viene applicato al campo che restituisce la matrice.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;
}

L'XML risultante potrebbe assomigliare agli elementi seguenti.The resulting XML might resemble the following.

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

Serializzazione delle classi derivateSerializing Derived Classes

Un altro utilizzo di XmlArrayItemAttribute è quello di consentire la serializzazione di classi derivate.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Ad esempio, al precedente esempio è possibile aggiungere un'altra classe denominata Manager che deriva da Employee.For example, another class named Manager that derives from Employee can be added to the previous example. Se non si applica XmlArrayItemAttribute, il codice provocherà un errore in fase di esecuzione perché il tipo di classe derivata non verrà riconosciuto.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. Per risolvere questo problema, applicare due volte l'attributo, impostando ogni volta la proprietà Type per ogni tipo accettabile (base e derivato).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;
}

Un'istanza serializzata potrebbe assomigliare agli elementi seguenti.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>

Serializzazione di una matrice come sequenza di elementiSerializing an Array as a Sequence of Elements

È possibile anche serializzare una matrice come un'unica sequenza di elementi XML applicando un attributo XmlElementAttribute al campo che restituisce la matrice nel modo riportato di seguito.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;
}

Un'istanza serializzata potrebbe assomigliare agli elementi seguenti.A serialized instance might resemble the following.

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

Un altro modo per differenziare i due flussi XML è quello di utilizzare lo strumento XML Schema Definition per generare i file del documento XML Schema (XSD) dal codice compilato.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. Per ulteriori informazioni sull'utilizzo dello strumento, vedere lo strumento XML Schema Definition e la serializzazione XML. Quando al campo non viene applicato alcun attributo, lo schema descrive l'elemento nel modo seguente.(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" />

Se al campo è applicato l'attributo XmlElementAttribute, lo schema risultante descrive l'elemento nel modo riportato di seguito.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" /> 

Serializzazione di un ArrayListSerializing an ArrayList

La classe ArrayList contiene una raccolta di oggetti diversi.The ArrayList class can contain a collection of diverse objects. È quindi possibile utilizzare una classe ArrayList allo stesso modo con cui si utilizza una matrice.You can therefore use a ArrayList much as you use an array. Anziché creare un campo che restituisca una matrice di oggetti tipizzati, è tuttavia possibile creare un campo che restituisca un solo ArrayList.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. Tuttavia, così come avviene con le matrici, è necessario informare XmlSerializer dei tipi di oggetti contenuti in ArrayList.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. A tale scopo, assegnare più istanze di XmlElementAttribute al campo, come illustrato nell'esempio riportato di seguito.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;
}

Controllo della serializzazione di classi tramite XmlRootAttribute e XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

Esistono due attributi applicabili a una classe (e solo a una classe): XmlRootAttribute e XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Questi attributi sono molto simili.These attributes are very similar. XmlRootAttribute può essere applicato a una sola classe, ovvero alla classe che, se serializzata, rappresenta l'elemento di apertura e chiusura del documento XML, in altre parole, l'elemento principale.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, invece, può essere applicato a qualsiasi classe, inclusa la classe radice.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

Ad esempio, negli esempi precedenti, la classe Group è la classe radice e tutte le sue proprietà e i campi pubblici diventano gli elementi XML trovati nel documento 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. Pertanto, può essere presente un solo nodo radice.Therefore, there can be only one root class. Tramite l'applicazione di XmlRootAttribute, è possibile controllare il flusso XML generato da XmlSerializer.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Ad esempio, è possibile modificare il nome dell'elemento e lo spazio dei nomi.For example, you can change the element name and namespace.

XmlTypeAttribute consente di controllare lo schema dell'XML generato.The XmlTypeAttribute allows you to control the schema of the generated XML. Questa funzionalità risulta utile quando è necessario pubblicare lo schema tramite un servizio Web XML.This capability is useful when you need to publish the schema through an XML Web service. Nell'esempio riportato di seguito, viene applicato sia XmlTypeAttribute che XmlRootAttribute alla stessa classe.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;
}

Se questa classe è compilata e viene utilizzato lo strumento XML Schema Definition per generare lo schema, viene creato il seguente XML che descrive Group.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">

Al contrario, se si fosse dovuta serializzare un'istanza della classe, nel documento XML si sarebbe trovato solo NewGroupName.In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

Come impedire la serializzazione con XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Potrebbero presentarsi delle situazioni in cui un campo o una proprietà pubblica non necessitano della serializzazione.There might be situations when a public property or field does not need to be serialized. Ad esempio, un campo o una proprietà possono essere utilizzati per contenere metadati.For example, a field or property could be used to contain metadata. In tali casi, applicare XmlIgnoreAttribute al campo o alla proprietà e XmlSerializer permetterà di ignorarli.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

Vedere ancheSee also