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 obiekty opisano przy użyciu narzędzi programistycznych języka, takich jak klasy, pola, właściwości, typy pierwotne, tablice i XML nawet osadzone w formie XmlElement lub XmlAttribute obiektów. Istnieje możliwość tworzenia własnych klas, dodawania adnotacji do atrybutów lub używania narzędzia definicji schematu XML (Xsd.exe) do generowania 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 i oznaczone atrybutami, aby stosować się do schematu podczas serializacji.

Aby transferować dane między obiektami i xml, wymaga mapowania z konstrukcji języka programowania na schemat XML i ze schematu XML do konstrukcji 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, aby poinstruować XmlSerializer sposób mapowania między systemem schematu XML a środowiskiem uruchomieniowym języka wspólnego. W czasie wykonywania wystąpienia klas można serializować w dokumentach XML, które są zgodne z danym 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.

Kontrolka wygenerowana 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 element do pola publicznego lub właściwości i ustaw ElementName właściwość . Aby uzyskać pełną listę podobnych atrybutów, zobacz Atrybuty kontrolujące serializacji XML. Można również zaimplementować IXmlSerializable interfejs w celu sterowania danymi wyjściowymi 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 kodowany kod XML protokołu SOAP, użyj atrybutów wymienionych w temacie Attributes That Control Encoded SOAP Serialization (Atrybuty, które steruje serializacją protokołu SOAP).

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 również użyć XmlAnyElementAttribute atrybutów i XmlAnyAttributeAttribute do serializacji i deserializacji elementów lub atrybutów, które nie znajdują się 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 XmlSerializerrozpoznanego przez element i zastosowania XmlIgnoreAttribute elementu 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 następującym 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ępowanie domyślnej serializacji

Można również zastąpić serializacji dowolnego zestawu obiektów i ich pól i właściwości, tworząc jeden z odpowiednich atrybutów i dodając go do wystąpienia XmlAttributes klasy. 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.

Uwaga

Element XmlSerializer zapewnia specjalne traktowanie klas, które implementują IEnumerable lub ICollection. Klasa, która implementuje IEnumerable , musi implementować publiczną Add metodę, która przyjmuje jeden parametr. Add Parametr metody musi być tego samego typu, co jest zwracany z właściwości zwracanej z wartości zwracanej z CurrentGetEnumeratorklasy lub jednej z baz tego typu. Klasa, która implementuje ICollection (np CollectionBase. ) oprócz IEnumerable właściwości indeksowanej publicznej Item (indeksator w języku C#), która przyjmuje liczbę całkowitą, i musi mieć właściwość publiczną Count typu liczba całkowita. Parametr Add metody musi być tym samym typem, co jest zwracany z Item właściwości lub jedną z baz tego typu. W przypadku klas implementujących ICollectionwartości do serializacji są pobierane z właściwości indeksowanej Item , a nie przez wywołanie metody GetEnumerator.

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 dowolnego z innych konstruktorów, wiele wersji tego samego zestawu jest generowanych i nigdy nie zwalnianych, co powoduje przeciek pamięci i niską wydajność. Najprostszym rozwiązaniem jest użycie jednego z wcześniej wymienionych dwóch konstruktorów. W przeciwnym razie należy buforować zestawy w obiekcie 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 tabliclisty i listy ogólnej

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

• Tablice ArrayList
• Tablice List<T>

Serializacja wyliczeń niepodpisanych długich

Nie XmlSerializer można utworzyć wystąpienia w celu serializacji wyliczenia, jeśli spełnione są następujące warunki: Wyliczenie jest typu niepodpisane (ulong w języku C#), a wyliczenie zawiera dowolny element członkowski o wartości większej niż 9223 372 036 854 775 807. Na przykład nie można serializować następujących elementów.

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

Przestarzałe typy

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