System.Xml.Serialization.XmlSerializer – třída

  • Článek

Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.

Serializace XML je proces převodu veřejných vlastností a polí objektu do sériového formátu (v tomto případě XML) pro ukládání nebo přenos. Deserializace znovu vytvoří objekt v původním stavu z výstupu XML. Serializace si můžete představit jako způsob uložení stavu objektu do datového proudu nebo vyrovnávací paměti. Například ASP.NET používá XmlSerializer třídu ke kódování zpráv webové služby XML.

Data v objekty je popsána pomocí konstrukcí programovací jazyk jako třídy, pole, vlastnosti, primitivní typy, pole a dokonce i vloženého XML ve formě XmlElement nebo XmlAttribute objekty. Máte možnost vytvořit vlastní třídy, anotovat s atributy nebo pomocí nástroje pro definici schématu XML (Xsd.exe) vygenerovat třídy založené na existujícím dokumentu definice schématu XML (XSD). Pokud máte schéma XML, můžete spustit Xsd.exe vytvořit sadu tříd, které jsou silně typovány schématu a anotovány s atributy, aby se při serializaci dodržoval schéma.

Pro přenos dat mezi objekty a XML vyžaduje mapování z konstruktorů programovacího jazyka na schéma XML a ze schématu XML do konstruktorů programovacího jazyka. Nástroje XmlSerializer a související nástroje, jako je Xsd.exe poskytují most mezi těmito dvěma technologiemi v době návrhu i za běhu. V době návrhu použijte Xsd.exe k vytvoření dokumentu schématu XML (.xsd) z vlastních tříd nebo k vytvoření tříd z daného schématu. V obou případech jsou třídy opatřeny poznámkami vlastními atributy, které instruují XmlSerializer , jak mapovat mezi systémem schémat XML a modulem CLR (Common Language Runtime). Za běhu lze instance tříd serializovat do dokumentů XML, které následují za daným schématem. Podobně lze tyto dokumenty XML deserializovat do objektů modulu runtime. Všimněte si, že schéma XML je volitelné a nevyžaduje se v době návrhu nebo za běhu.

Vygenerovaný ovládací prvek XML

Pokud chcete řídit vygenerovaný KÓD XML, můžete použít speciální atributy na třídy a členy. Chcete-li například zadat jiný název elementu XML, použijte XmlElementAttribute na veřejné pole nebo vlastnost a nastavte ElementName vlastnost. Úplný seznam podobných atributů naleznete v části Atributy, které řídí serializaci XML. Můžete také implementovat IXmlSerializable rozhraní pro řízení výstupu XML.

Pokud vygenerovaný kód XML musí odpovídat oddílu 5 dokumentu World Wide Consortium, protokol SOAP (Simple Object Access Protocol) 1.1, musíte vytvořit XmlSerializer pomocí XmlTypeMapping. Chcete-li dále řídit kódovaný kód SOAP XML, použijte atributy uvedené v atributech, které řídí kódované serializace SOAP.

XmlSerializer Díky tomu můžete využít výhod práce se silnými třídami a stále máte flexibilitu XML. Pomocí polí nebo vlastností typu XmlElementnebo XmlAttributeXmlNode ve třídách silného typu můžete číst části dokumentu XML přímo do objektů XML.

Pokud pracujete s rozšiřitelnými schématy XML, můžete také použít XmlAnyElementAttribute atributy k serializaci a XmlAnyAttributeAttribute deserializaci elementů nebo atributů, které nejsou nalezeny v původním schématu. Chcete-li použít objekty, použijte XmlAnyElementAttribute u pole, které vrací pole XmlElement objektů, nebo použijte XmlAnyAttributeAttribute pole, které vrací pole XmlAttribute objektů.

Pokud vlastnost nebo pole vrátí komplexního objektu (například pole nebo instanci třídy), XmlSerializer převede ho na prvek vnořené hlavní dokument XML. Například první třída v následujícím kódu vrátí instanci druhé třídy.

Public Class MyClass
    Public MyObjectProperty As MyObject
End Class

Public Class MyObject
    Public ObjectName As String
End Class

public class MyClass
{
    public MyObject MyObjectProperty;
}
public class MyObject
{
    public string ObjectName;
}

Serializovaný výstup XML vypadá takto:

<MyClass>
  <MyObjectProperty>
  <ObjectName>My String</ObjectName>
  </MyObjectProperty>
</MyClass>

Pokud schéma obsahuje volitelný prvek (minOccurs = '0'), nebo pokud schéma obsahuje výchozí hodnotu, máte dvě možnosti. Jednou z možností je System.ComponentModel.DefaultValueAttribute zadat výchozí hodnotu, jak je znázorněno v následujícím kódu.

Public Class PurchaseOrder
    <System.ComponentModel.DefaultValueAttribute ("2002")> _
    Public Year As String
End Class

public class PurchaseOrder
{
    [System.ComponentModel.DefaultValueAttribute ("2002")]
    public string Year;
}

Další možností je použití speciálního vzoru k vytvoření logického pole rozpoznané operátorem XmlSerializera použití XmlIgnoreAttribute pole. Vzor je vytvořen ve formě propertyNameSpecified. Pokud je například pole s názvem "MyFirstName", vytvořili byste také pole s názvem "MyFirstNameSpecified", které dává pokyn, zda má vygenerovat XmlSerializer element XML s názvem "MyFirstName". To je ukázáno v následujícím příkladu.

Public Class OptionalOrder
    ' This field's value should not be serialized
    ' if it is uninitialized.
    Public FirstOrder As String

    ' Use the XmlIgnoreAttribute to ignore the
    ' special field named "FirstOrderSpecified".
    <System.Xml.Serialization.XmlIgnoreAttribute> _
    Public FirstOrderSpecified As Boolean
End Class

public class OptionalOrder
{
    // This field should not be serialized
    // if it is uninitialized.
    public string FirstOrder;

    // Use the XmlIgnoreAttribute to ignore the
    // special field named "FirstOrderSpecified".
    [System.Xml.Serialization.XmlIgnoreAttribute]
    public bool FirstOrderSpecified;
}

Přepsání výchozí serializace

Serializaci libovolné sady objektů a jejich vlastností můžete také přepsat tak, že vytvoříte jeden z příslušných atributů a přidáte ho do instance XmlAttributes třídy. Přepsání serializace tímto způsobem má dvě použití: nejprve můžete řídit a rozšířit serializaci objektů nalezených v knihovně DLL, i když nemáte přístup ke zdroji; zadruhé, můžete vytvořit jednu sadu serializovatelných tříd, ale serializovat objekty několika způsoby. Další podrobnosti naleznete v XmlAttributeOverrides třídě a postupy: Řízení serializace odvozených tříd.

Chcete-li serializovat objekt, zavolejte metodu Serialize . Chcete-li deserializovat objekt, zavolejte metodu Deserialize .

Pokud chcete do dokumentu XML přidat obory názvů XML, přečtěte si téma XmlSerializerNamespaces.

Poznámka:

Dává XmlSerializer zvláštní zacházení třídám, které implementují IEnumerable nebo ICollection. Třídu, která implementuje IEnumerable musí implementovat veřejné Add metodu, která přebírá jediný parametr. Parametr Add metody musí být stejného typu, jako je vrácen z Current vlastnosti u hodnoty vrácené z GetEnumerator, nebo jedné ze základu tohoto typu. Třída, která implementuje ICollection (například CollectionBase) navíc IEnumerable musí mít veřejnou Item indexovanou vlastnost (indexer v jazyce C#), která přebírá celé číslo a musí mít veřejnou Count vlastnost typu integer. Parametr Add metody musí být stejný typ, jako je vrácen z Item vlastnosti, nebo jeden ze základů tohoto typu. Pro třídy, které implementují ICollection, hodnoty, které mají být serializovány jsou načteny z indexované Item vlastnosti, nikoli voláním GetEnumerator.

K deserializaci objektu musíte mít oprávnění k zápisu do dočasného adresáře (jak je definováno proměnnou prostředí TEMP).

Dynamicky generovaná sestavení

Aby se zvýšil výkon, infrastruktura serializace XML dynamicky generuje sestavení pro serializaci a deserializaci zadaných typů. Infrastruktura vyhledá a znovu použije tato sestavení. K tomuto chování dochází pouze při použití následujících konstruktorů:

XmlSerializer.XmlSerializer(Type)

XmlSerializer.XmlSerializer(Type, String)

Pokud použijete některý z dalších konstruktorů, vygeneruje se více verzí stejného sestavení a nikdy se neodloží, což vede k nevracení paměti a nízkému výkonu. Nejjednodušším řešením je použít jeden z dříve zmíněných dvou konstruktorů. V opačném případě je nutné ukládat sestavení do mezipaměti , Hashtablejak je znázorněno v následujícím příkladu.

Hashtable serializers = new Hashtable();

// Use the constructor that takes a type and XmlRootAttribute.
XmlSerializer s = new XmlSerializer(typeof(MyClass), myRoot);

// Implement a method named GenerateKey that creates unique keys
// for each instance of the XmlSerializer. The code should take
// into account all parameters passed to the XmlSerializer
// constructor.
object key = GenerateKey(typeof(MyClass), myRoot);

// Check the local cache for a matching serializer.
XmlSerializer ser = (XmlSerializer)serializers[key];
if (ser == null)
{
    ser = new XmlSerializer(typeof(MyClass), myRoot);
    // Cache the serializer.
    serializers[key] = ser;
}

// Use the serializer to serialize or deserialize.

Dim serializers As New Hashtable()

' Use the constructor that takes a type and XmlRootAttribute.
Dim s As New XmlSerializer(GetType([MyClass]), myRoot)

' Implement a method named GenerateKey that creates unique keys
' for each instance of the XmlSerializer. The code should take
' into account all parameters passed to the XmlSerializer
' constructor.
Dim key As Object = GenerateKey(GetType([MyClass]), myRoot)

' Check the local cache for a matching serializer.
Dim ser As XmlSerializer = CType(serializers(key), XmlSerializer)

If ser Is Nothing Then
    ser = New XmlSerializer(GetType([MyClass]), myRoot)
    ' Cache the serializer.
    serializers(key) = ser
End If

' Use the serializer to serialize or deserialize.

Serializace ArrayList a obecného seznamu

Nelze XmlSerializer serializovat nebo deserializovat následující:

Serializace výčtů unsigned Long

Nelze XmlSerializer vytvořit instanci pro serializaci výčtu, pokud jsou splněny následující podmínky: Výčet je typu unsigned long (ulong v jazyce C#) a výčet obsahuje libovolný člen s hodnotou větší než 9 223 372 036 854 775 807. Například následující nelze serializovat.

public enum LargeNumbers: ulong
{
    a = 9223372036854775808
}
// At run time, the following code will fail.
xmlSerializer mySerializer=new XmlSerializer(typeof(LargeNumbers));

Zastaralé typy

Třída XmlSerializer serializuje objekty, které jsou označeny jako [Obsolete].