Bagikan melalui

Kelas System.Xml.Serialization.XmlSerializer

  • Artikel

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Serialisasi XML adalah proses mengonversi properti dan bidang publik objek ke format serial (dalam hal ini, XML) untuk penyimpanan atau transportasi. Deserialisasi membuat ulang objek dalam status aslinya dari output XML. Anda dapat menganggap serialisasi sebagai cara menyimpan status objek ke dalam aliran atau buffer. Misalnya, ASP.NET menggunakan XmlSerializer kelas untuk mengodekan pesan layanan Web XML.

Data dalam objek Anda dijelaskan menggunakan konstruksi bahasa pemrograman seperti kelas, bidang, properti, jenis primitif, array, dan bahkan XML yang disematkan dalam bentuk XmlElement objek atau XmlAttribute . Anda memiliki opsi untuk membuat kelas Anda sendiri, diannotasi dengan atribut, atau menggunakan Xml Schema Definition Tool (Xsd.exe) untuk menghasilkan kelas berdasarkan dokumen definisi Skema XML (XSD) yang ada. Jika Anda memiliki Skema XML, Anda dapat menjalankan Xsd.exe untuk menghasilkan sekumpulan kelas yang sangat diketik ke skema dan diannotasi dengan atribut untuk mematuhi skema saat diserialisasikan.

Untuk mentransfer data antara objek dan XML memerlukan pemetaan dari konstruksi bahasa pemrograman ke skema XML dan dari skema XML ke konstruksi bahasa pemrograman. Alat XmlSerializer terkait dan seperti Xsd.exe menyediakan jembatan antara kedua teknologi ini pada waktu desain dan runtime. Pada waktu desain, gunakan Xsd.exe untuk menghasilkan dokumen skema XML (.xsd) dari kelas kustom Anda atau untuk menghasilkan kelas dari skema tertentu. Dalam kedua kasus, kelas diannotasikan dengan atribut kustom untuk menginstruksikan XmlSerializer cara memetakan antara sistem skema XML dan runtime bahasa umum. Pada runtime, instans kelas dapat diserialisasikan ke dalam dokumen XML yang mengikuti skema yang diberikan. Demikian juga, dokumen XML ini dapat dideserialisasi ke dalam objek runtime. Perhatikan bahwa skema XML bersifat opsional, dan tidak diperlukan pada waktu desain atau runtime.

Kontrol XML yang dihasilkan

Untuk mengontrol XML yang dihasilkan, Anda dapat menerapkan atribut khusus ke kelas dan anggota. Misalnya, untuk menentukan nama elemen XML yang berbeda, terapkan XmlElementAttribute ke bidang atau properti publik, dan atur ElementName properti . Untuk daftar lengkap atribut serupa, lihat Atribut yang Mengontrol Serialisasi XML. Anda juga dapat menerapkan IXmlSerializable antarmuka untuk mengontrol output XML.

Jika XML yang dihasilkan harus sesuai dengan bagian 5 dari dokumen World Wide Consortium, Simple Object Access Protocol (SOAP) 1.1, Anda harus membuat XmlSerializer dengan XmlTypeMapping. Untuk lebih mengontrol XML SOAP yang dikodekan, gunakan atribut yang tercantum dalam Atribut yang Mengontrol Serialisasi SOAP yang Dikodekan.

XmlSerializer Dengan Anda dapat memanfaatkan bekerja dengan kelas yang ditik dengan kuat dan masih memiliki fleksibilitas XML. Dengan menggunakan bidang atau properti jenis XmlElement, XmlAttribute atau XmlNode di kelas yang ditik dengan kuat, Anda dapat membaca bagian dokumen XML langsung ke objek XML.

Jika Anda bekerja dengan skema XML yang dapat diperluas, Anda juga dapat menggunakan XmlAnyElementAttribute atribut dan XmlAnyAttributeAttribute untuk menserialisasikan dan mendeserialisasi elemen atau atribut yang tidak ditemukan dalam skema asli. Untuk menggunakan objek, terapkan XmlAnyElementAttribute ke bidang yang mengembalikan array XmlElement objek, atau menerapkan XmlAnyAttributeAttribute ke bidang yang mengembalikan array XmlAttribute objek.

Jika properti atau bidang mengembalikan objek kompleks (seperti array atau instans kelas), maka XmlSerializer akan mengonversinya menjadi elemen yang ditumpuk dalam dokumen XML utama. Misalnya, kelas pertama dalam kode berikut mengembalikan instans kelas kedua.

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

Output XML yang diserialisasikan terlihat seperti ini:

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

Jika skema menyertakan elemen yang opsional (minOccurs = '0'), atau jika skema menyertakan nilai default, Anda memiliki dua opsi. Salah satu opsinya adalah menggunakan System.ComponentModel.DefaultValueAttribute untuk menentukan nilai default, seperti yang ditunjukkan dalam kode berikut.

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

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

Opsi lain adalah menggunakan pola khusus untuk membuat bidang Boolean yang dikenali oleh XmlSerializer, dan untuk menerapkan ke XmlIgnoreAttribute bidang . Pola dibuat dalam bentuk propertyNameSpecified. Misalnya, jika ada bidang bernama "MyFirstName" Anda juga akan membuat bidang bernama "MyFirstNameSpecified" yang menginstruksikan XmlSerializer apakah akan menghasilkan elemen XML bernama "MyFirstName". Hal ini ditunjukkan di contoh berikut.

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

Mengesampingkan serialisasi default

Anda juga dapat mengambil alih serialisasi sekumpulan objek dan bidang dan propertinya dengan membuat salah satu atribut yang sesuai, dan menambahkannya ke instans XmlAttributes kelas. Mengambil alih serialisasi dengan cara ini memiliki dua kegunaan: pertama, Anda dapat mengontrol dan menambah serialisasi objek yang ditemukan dalam DLL, bahkan jika Anda tidak memiliki akses ke sumber; kedua, Anda dapat membuat satu set kelas yang dapat diserialisasikan, tetapi menserialisasikan objek dengan berbagai cara. Untuk detail selengkapnya, lihat XmlAttributeOverrides kelas dan Cara: Mengontrol Serialisasi Kelas Turunan.

Untuk membuat serialisasi objek, panggil Serialize metode . Untuk mendeserialisasi objek, panggil Deserialize metode .

Untuk menambahkan namespace XML ke dokumen XML, lihat XmlSerializerNamespaces.

Catatan

memberikan XmlSerializer perlakuan khusus pada kelas yang mengimplementasikan IEnumerable atau ICollection. Kelas yang menerapkan IEnumerable harus menerapkan metode publik Add yang mengambil satu parameter. Parameter Add metode harus berjenis sama seperti yang dikembalikan dari Current properti pada nilai yang dikembalikan dari GetEnumerator, atau salah satu basis jenis tersebut. Kelas yang mengimplementasikan ICollection (seperti CollectionBase) selain IEnumerable harus memiliki properti terindeks publik Item (pengindeks di C#) yang mengambil bilangan bulat, dan harus memiliki properti publik Count dengan bilangan bulat jenis. Parameter ke Add metode harus berjenis yang sama seperti yang dikembalikan dari Item properti , atau salah satu basis jenis tersebut. Untuk kelas yang mengimplementasikan ICollection, nilai yang akan diserialisasikan diambil dari properti terindeks Item , bukan dengan memanggil GetEnumerator.

Anda harus memiliki izin untuk menulis ke direktori sementara (seperti yang ditentukan oleh variabel lingkungan TEMP) untuk mendeserialisasi objek.

Rakitan yang dihasilkan secara dinamis

Untuk meningkatkan performa, infrastruktur serialisasi XML secara dinamis menghasilkan rakitan untuk menserialisasikan dan mendeserialisasi jenis yang ditentukan. Infrastruktur menemukan dan menggunakan kembali rakitan tersebut. Perilaku ini hanya terjadi saat menggunakan konstruktor berikut:

XmlSerializer.XmlSerializer(Type)

XmlSerializer.XmlSerializer(Type, String)

Jika Anda menggunakan salah satu konstruktor lain, beberapa versi rakitan yang sama dihasilkan dan tidak pernah dibongkar, yang menghasilkan kebocoran memori dan performa yang buruk. Solusi termudah adalah menggunakan salah satu dari dua konstruktor yang disebutkan sebelumnya. Jika tidak, Anda harus menyimpan rakitan dalam , seperti yang Hashtableditunjukkan dalam contoh berikut.

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.

Serialisasi ArrayList dan daftar generik

Tidak XmlSerializer dapat membuat serialisasi atau mendeserialisasi hal berikut:

Serialisasi enumerasi panjang yang tidak ditandatangani

XmlSerializer tidak dapat diinstansiasi untuk membuat serial enumerasi jika kondisi berikut ini benar: Enumerasi berjenis unsigned long (ulong dalam C#) dan enumerasi berisi anggota mana pun dengan nilai yang lebih besar dari 9.223.372.036.854.775.807. Misalnya, berikut ini tidak dapat diserialisasikan.

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

Jenis kedaluwarsa

Kelas XmlSerializer tidak menserialisasikan objek yang ditandai sebagai [Obsolete].