System.Xml.Serialization.XmlSerializer, klasa

Ten artykuł zawiera dodatkowe uwagi dotyczące dokumentacji referencyjnej dla tego interfejsu API.

Serializacja XML to proces konwertowania właściwości publicznych i pól obiektu na format seryjny (w tym przypadku XML) dla magazynu lub transportu. Deserializacja ponownie tworzy obiekt w oryginalnym stanie na podstawie danych wyjściowych XML. Serializacji można traktować jako sposób zapisywania stanu obiektu w strumieniu lub buforze. Na przykład ASP.NET używa XmlSerializer klasy do kodowania komunikatów usługi sieci Web XML.

Dane w obiektach są opisywane przy użyciu konstrukcji języka programowania, takich jak klasy, pola, właściwości, typy pierwotne, tablice, a nawet osadzony kod XML w postaci XmlElement obiektów lub XmlAttribute . Istnieje możliwość tworzenia własnych klas, dodawania adnotacji do atrybutów lub używania narzędzia definicji schematu XML (Xsd.exe) w celu wygenerowania klas na podstawie istniejącego dokumentu definicji schematu XML (XSD). Jeśli masz schemat XML, możesz uruchomić Xsd.exe, aby utworzyć zestaw klas, które są silnie typizowane do schematu oraz oznaczone atrybutami, aby były zgodne z tym schematem podczas serializacji.

Aby transferować dane między obiektami a XML, konieczne jest przekształcenie konstrukcji języka programowania w schemat XML i ze schematu XML z powrotem w konstrukcje języka programowania. Narzędzia XmlSerializer i powiązane, takie jak Xsd.exe zapewniają most między tymi dwiema technologiami zarówno w czasie projektowania, jak i w czasie wykonywania. W czasie projektowania użyj Xsd.exe, aby utworzyć dokument schematu XML (xsd) z klas niestandardowych lub utworzyć klasy z danego schematu. W obu przypadkach klasy są oznaczone adnotacjami z atrybutami niestandardowymi, by poinstruować XmlSerializer, jak mapować między systemem schematu XML a środowiskiem uruchomieniowym języka wspólnego. W czasie wykonywania instancje klas można serializować do dokumentów XML zgodnie z podanym schematem. Podobnie te dokumenty XML można deserializować w obiektach środowiska uruchomieniowego. Należy pamiętać, że schemat XML jest opcjonalny i nie jest wymagany w czasie projektowania ani w czasie wykonywania.

Kontrola wygenerowanego XML

Aby kontrolować wygenerowany kod XML, można zastosować specjalne atrybuty do klas i składowych. Aby na przykład określić inną nazwę elementu XML, zastosuj XmlElementAttribute do pola publicznego lub właściwości, a następnie ustaw właściwość ElementName. Aby uzyskać pełną listę podobnych atrybutów, zobacz Atrybuty kontrolujące serializacji XML. Można również zaimplementować IXmlSerializable interfejs, aby sterować wyjściem XML.

Jeśli wygenerowany kod XML musi być zgodny z sekcją 5 dokumentu World Wide Consortium, Simple Object Access Protocol (SOAP) 1.1, należy skonstruować element XmlSerializer za pomocą elementu XmlTypeMapping. Aby dokładniej kontrolować zakodowany XML protokołu SOAP, użyj atrybutów wymienionych w Attributes That Control Encoded SOAP Serialization.

XmlSerializer Dzięki funkcji można korzystać z pracy z silnie typizowanymi klasami i nadal mieć elastyczność kodu XML. Używając pól lub właściwości typu XmlElement, XmlAttribute lub XmlNode w silnie typowanych klasach, można odczytać części dokumentu XML bezpośrednio do obiektów XML.

Jeśli pracujesz z rozszerzalnymi schematami XML, możesz użyć atrybutów XmlAnyElementAttribute i XmlAnyAttributeAttribute do serializacji i deserializacji elementów lub atrybutów, które nie występują w oryginalnym schemacie. Aby użyć obiektów, zastosuj element XmlAnyElementAttribute do pola zwracającego tablicę XmlElement obiektów lub zastosuj obiekt XmlAnyAttributeAttribute do pola zwracającego tablicę XmlAttribute obiektów.

Jeśli właściwość lub pole zwraca obiekt złożony (taki jak tablica lub wystąpienie klasy), XmlSerializer konwertuje go na element zagnieżdżony w głównym dokumencie XML. Na przykład pierwsza klasa w poniższym kodzie zwraca wystąpienie drugiej klasy.

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

Serializowane dane wyjściowe XML wyglądają następująco:

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

Jeśli schemat zawiera element opcjonalny (minOccurs = '0'), lub jeśli schemat zawiera wartość domyślną, masz dwie opcje. Jedną z System.ComponentModel.DefaultValueAttribute opcji jest określenie wartości domyślnej, jak pokazano w poniższym kodzie.

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

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

Inną opcją jest użycie specjalnego wzorca w celu utworzenia pola logicznego, rozpoznanego przez XmlSerializer, i zastosowania XmlIgnoreAttribute do pola. Wzorzec jest tworzony w postaci propertyNameSpecified. Jeśli na przykład istnieje pole o nazwie "MyFirstName", należy również utworzyć pole o nazwie "MyFirstNameSpecified", które instruuje XmlSerializer , czy wygenerować element XML o nazwie "MyFirstName". Jest to pokazane w poniższym przykładzie.

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

Zastąp domyślną serializację

Można również zastąpić serializację dowolnego zestawu obiektów oraz ich pól i właściwości, tworząc odpowiadający atrybut i dodając go do wystąpienia klasy XmlAttributes. Zastępowanie serializacji w ten sposób ma dwa zastosowania: najpierw można kontrolować i rozszerzać serializacji obiektów znajdujących się w dll, nawet jeśli nie masz dostępu do źródła; po drugie, można utworzyć jeden zestaw klas możliwych do serializacji, ale serializować obiekty na wiele sposobów. Aby uzyskać więcej informacji, zobacz klasę XmlAttributeOverrides i instrukcje: kontrolowanie serializacji klas pochodnych.

Aby serializować obiekt, wywołaj metodę Serialize . Aby wykonać deserializowanie obiektu, wywołaj metodę Deserialize .

Aby dodać przestrzenie nazw XML do dokumentu XML, zobacz XmlSerializerNamespaces.

Aby deserializować obiekt, musisz mieć uprawnienia do zapisu w katalogu tymczasowym (zgodnie z definicją zmiennej środowiskowej TEMP).

Dynamicznie generowane zestawy

Aby zwiększyć wydajność, infrastruktura serializacji XML dynamicznie generuje zestawy w celu serializacji i deserializacji określonych typów. Infrastruktura odnajduje i ponownie używa tych zestawów. To zachowanie występuje tylko w przypadku używania następujących konstruktorów:

XmlSerializer.XmlSerializer(Type)

XmlSerializer.XmlSerializer(Type, String)

Jeśli używasz któregokolwiek z innych konstruktorów, wiele wersji tego samego zestawu jest generowanych i nigdy nie jest zwalnianych, co prowadzi do przecieku pamięci i obniżenia wydajności. Najprostszym rozwiązaniem jest użycie jednego z wcześniej wymienionych dwóch konstruktorów. W przeciwnym razie należy buforować zestawy w Hashtable, jak pokazano w poniższym przykładzie.

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.

Serializacja ArrayList i listy generycznej

Nie można XmlSerializer serializować ani deserializować następujących:

• Tablice ArrayList
• Tablice List<T>

Serializacja wyliczeń niepodpisanych długich

Nie można utworzyć instancji XmlSerializer, aby zserializować wyliczenie, jeśli spełnione są następujące warunki: Wyliczenie jest typu ulong (ulong w języku C#), a wyliczenie zawiera dowolny element członkowski o wartości przekraczającej 9,223,372,036,854,775,807. Na przykład nie można serializować następujących elementów.

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

Przestarzałe typy

Klasa XmlSerializer nie serializuje obiektów oznaczonych jako [Obsolete].