Controllo della serializzazione XML mediante attributi

Gli attributi possono essere utilizzati per controllare la serializzazione XML di un oggetto o per creare un flusso XML alternativo dallo stesso gruppo di classi. Per ulteriori informazioni sulla creazione di un flusso XML alternativo, vedere Procedura: specificare un nome di elemento alternativo per un flusso XML.

Nota

Se il codice XML generato deve essere conforme alla sezione 5 del documento sul Simple Object Access Protocol (SOAP), versione 1.1 del World Wide Web Consortium (www.w3.org) (informazioni in lingua inglese), utilizzare gli attributi elencati in Attributi che controllano la serializzazione con codifica SOAP.

Per impostazione predefinita, un nome di elemento XML è determinato dal nome della classe o del membro. In una classe semplice denominata Book, un campo denominato ISBN produrrà un tag dell'elemento XML <ISBN>, come illustrato nell'esempio seguente.

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>.

Se si desidera assegnare un nuovo nome all'elemento, è possibile cambiare questo comportamento predefinito. Nel codice seguente viene illustrato come ciò avviene mediante un attributo, impostando la proprietà ElementName di XmlElementAttribute.

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class

public class TaxRates{
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Per ulteriori informazioni sugli attributi, vedere Extending Metadata Using Attributes. Per un elenco degli attributi che controllano la serializzazione XML, vedere Attributi che controllano la serializzazione XML.

Controllare la serializzazione delle matrici

Gli attributi XmlArrayAttribute e XmlArrayItemAttribute sono progettati per controllare la serializzazione di matrici. Essi consentono di controllare il nome di elemento, lo spazio dei nomi e il tipo di dati dello schema XML (XSD), come definito nel documento del World Wide Web Consortium (www.w3.org) intitolato "XML Schema Part 2: Datatypes" (informazioni in lingua inglese). È inoltre possibile specificare i tipi da includere in una matrice.

XmlArrayAttribute determinerà le proprietà dell'elemento XML di inclusione, ottenuto quando una matrice viene serializzata. Per impostazione predefinita, ad esempio, la serializzazione della matrice seguente genera un elemento XML denominato Employees. L'elemento Employees conterrà una serie di elementi denominati in base al tipo di matrice 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 essere simile a quanto segue.

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

Applicando XmlArrayAttribute, è possibile modificare il nome dell'elemento XML come segue:

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class

public class Group{
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

Il linguaggio XML ottenuto potrebbe essere simile a quanto segue.

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

XmlArrayItemAttribute, d'altra parte, controlla il modo in cui gli elementi contenuti nella matrice vengono serializzati. Si noti che l'attributo viene applicato al campo che restituisce la matrice.

Public Class Group
    <XmlArrayItem("MemberName")> _
    Public Employee() As Employees
End Class

public class Group{
    [XmlArrayItem("MemberName")]
    public Employee[] Employees;
}

Il linguaggio XML ottenuto potrebbe essere simile a quanto segue.

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

Serializzare classi derivate

Un altro utilizzo di XmlArrayItemAttribute è consentire la serializzazione di classi derivate. Un'altra classe denominata Manager che deriva da Employee, ad esempio, può essere aggiunta all'esempio precedente. Se non si applica XmlArrayItemAttribute, il codice non verrà eseguito correttamente in fase di esecuzione in quanto il tipo della classe derivata non sarà riconosciuto. Per risolvere il problema, applicare l'attributo due volte, impostando ogni volta la proprietà Type per ogni tipo accettabile sia di base sia derivato.

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 essere simile a quanto segue.

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

Serializzare una matrice come sequenza di elementi

È inoltre possibile serializzare una matrice come sequenza flat di elementi XML applicando XmlElementAttribute al campo che restituisce la matrice nel modo seguente.

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class

public class Group{
    [XmlElement]
    public Employee[] Employees;
}

Un'istanza serializzata potrebbe essere simile a quanto segue.

<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 consiste nell'utilizzare lo strumento di definizione di schemi XML per generare i file del documento dello schema XML (XSD) dal codice compilato. Per ulteriori informazioni sull'utilizzo dello strumento, vedere Strumento di definizione di schemi XML e serializzazione XML. Quando al campo non viene applicato alcun attributo, lo schema descrive l'elemento nel modo seguente:

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

Quando al campo viene applicato XmlElementAttribute, lo schema risultante descrive l'elemento nel modo seguente:

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

Serializzare una classe ArrayList

La classe ArrayList può contenere un insieme di oggetti diversi. È pertanto possibile utilizzare ArrayList come si utilizzerebbe una matrice. Anziché creare un campo che restituisce una matrice di oggetti tipizzati, tuttavia, è possibile creare un campo che restituisce una singola ArrayList. La gestione delle matrici prevede comunque che XmlSerializer sia a conoscenza dei tipi di oggetti contenuti in ArrayList. A tale scopo, assegnare al campo più istanze di XmlElementAttribute, come illustrato nell'esempio seguente:

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;
}

Controllare la serializzazione di classi mediante XmlRootAttribute e XmlTypeAttribute

È possibile applicare a una classe (e solo a una classe) due attributi, ovvero XmlRootAttribute e XmlTypeAttribute. Questi attributi sono molto simili tra loro. XmlRootAttribute può essere applicato a una sola classe, ovvero quella che, quando viene serializzata, rappresenta l'elemento di apertura e chiusura del documento XML, in altre parole, l'elemento radice. XmlTypeAttribute, invece, può essere applicato a qualsiasi classe, inclusa la classe radice.

Negli esempi precedenti la classe Group è la classe radice e tutte le relative proprietà e campi pubblici diventano gli elementi XML trovati nel documento XML. Può esistere pertanto una sola classe radice. Applicando XmlRootAttribute, è possibile controllare il flusso XML generato da XmlSerializer. Il nome dell'elemento e lo spazio dei nomi, ad esempio, possono essere modificati.

XmlTypeAttribute consente di controllare lo schema del codice XML generato. Questa funzionalità è utile quando è necessario pubblicare lo schema attraverso un servizio Web XML. L'esempio seguente applica sia XmlTypeAttribute che XmlRootAttribute alla stessa classe.

<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 viene compilata, e lo strumento di definizione di schemi XML viene utilizzato per generarne lo schema, il linguaggio XML che descrive Group sarà il seguente:

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

Al contrario, se è necessario serializzare un'istanza della classe, nel documento XML verrà trovato solo NewGroupName.

<NewGroupName>
    . . .
</NewGroupName>

Impedire la serializzazione mediante XmlIgnoreAttribute

Possono verificarsi situazioni in cui non è necessario serializzare un campo o una proprietà pubblica. Un campo o una proprietà possono essere utilizzati, ad esempio, per contenere metadati. In questi casi, applicare XmlIgnoreAttribute al campo o alla proprietà e XmlSerializer lo ignorerà.

Vedere anche

Attività

Procedura: specificare un nome di elemento alternativo per un flusso XML
Procedura: serializzare un oggetto
Procedura: deserializzare un oggetto

Concetti

Attributi che controllano la serializzazione XML
Attributi che controllano la serializzazione con codifica SOAP
Introduzione alla serializzazione XML
Esempi di serializzazione XML