System.Xml.Serialization.XmlSerializer sınıfı

Bu makale, bu API'nin başvuru belgelerine ek açıklamalar sağlar.

XML serileştirme, bir nesnenin ortak özelliklerini ve alanlarını depolama veya aktarım için seri biçime (bu örnekte XML) dönüştürme işlemidir. Seri durumdan çıkarma, nesneyi XML çıkışından özgün durumunda yeniden oluşturur. Serileştirmeyi, bir nesnenin durumunu bir akışa veya arabelleğe kaydetmenin bir yolu olarak düşünebilirsiniz. Örneğin, ASP.NET XML Web hizmeti iletilerini kodlamak için sınıfını XmlSerializer kullanır.

Nesnelerinizdeki veriler, sınıflar, alanlar, özellikler, ilkel türler, diziler ve gömülü XML gibi XmlElement veya XmlAttribute nesneleri biçiminde programlama dili yapıları kullanılarak açıklanmıştır. Var olan bir XML Şema tanımı (XSD) belgesini temel alan sınıfları oluşturmak için kendi sınıflarınızı oluşturma, özniteliklerle açıklama ekleme veya XML Şema Tanımı Aracı'nı (Xsd.exe ) kullanma seçeneğiniz vardır. XML Şemanız varsa, şemaya uygun şekilde güçlü tiplenmiş ve seri hale getirildiğinde şemaya uyması için özniteliklerle anotlanmış bir sınıf kümesi oluşturmak için Xsd.exe çalıştırabilirsiniz.

Nesneler ve XML arasında veri aktarmak için programlama dili yapılarından XML şemasına ve XML şemasından programlama dili yapılarına eşleme gerekir. XmlSerializerXsd.exe gibi ve ilgili araçlar, hem tasarım zamanında hem de çalışma zamanında bu iki teknoloji arasında köprü sağlar. Tasarım zamanında, özel sınıflarınızdan bir XML şema belgesi (.xsd) oluşturmak veya belirli bir şemadan sınıflar oluşturmak için Xsd.exe kullanın. Her iki durumda da, XML şema sistemi ile ortak dil çalışma zamanı arasında nasıl eşleme yapılacağını bildirmek XmlSerializer için sınıflara özel öznitelikler eklenmiştir. Çalışma zamanında, sınıfların örnekleri verilen şemayı izleyen XML belgeleri halinde seri hale getirilebilir. Benzer şekilde, bu XML belgeleri çalışma zamanı nesnelerine seri durumdan çıkarılabilir. XML şemasının isteğe bağlı olduğunu ve tasarım zamanında veya çalışma zamanında gerekli olmadığını unutmayın.

Oluşturulan XML'i denetleme

Oluşturulan XML'yi denetlemek için sınıflara ve üyelere özel öznitelikler uygulayabilirsiniz. Örneğin, farklı bir XML öğesi adı belirtmek için ortak alana veya özelliğe bir XmlElementAttribute uygulayın ve özelliğini ayarlayın ElementName . Benzer özniteliklerin tam listesi için bkz. XML Serileştirmesini Denetleen Öznitelikler. XML çıkışını IXmlSerializable denetlemek için arabirimini de uygulayabilirsiniz.

Oluşturulan XML, World Wide Web Consortium belgesinin Basit Nesne Erişim Protokolü (SOAP) 1.1 5. bölümüne uygun olmalıdır ve XmlSerializer'i XmlTypeMapping ile oluşturmanız gerekir. Kodlanmış SOAP XML'sini daha fazla denetlemek için Kodlanmış SOAP Serileştirmesini Denetleen Öznitelikler'de listelenen öznitelikleri kullanın.

XmlSerializer ile, türü kesin olarak belirlenmiş sınıflarla çalışmaktan yararlanabilir ve yine de XML esnekliğine sahip olabilirsiniz. Kesin olarak yazılmış sınıflarınızda türü XmlElement, XmlAttribute veya XmlNode olan alanları veya özellikleri kullanarak, XML belgesinin bölümlerini doğrudan XML nesnelerine okuyabilirsiniz.

Genişletilebilir XML şemalarıyla çalışıyorsanız, özgün şemada XmlAnyElementAttribute bulunmayan öğeleri veya öznitelikleri seri hale getirmek ve seri durumdan çıkarmak için ve XmlAnyAttributeAttribute özniteliklerini de kullanabilirsiniz. Nesneleri kullanmak için, XmlAnyElementAttribute nesne dizisi döndüren bir alana veya XmlElement nesne dizisi döndüren bir alana uygulayın.

Bir özellik veya alan karmaşık bir nesne (dizi veya sınıf örneği gibi) döndürürse, XmlSerializer bunu ana XML belgesi içinde iç içe yerleştirilmiş bir öğeye dönüştürür. Örneğin, aşağıdaki koddaki ilk sınıf ikinci sınıfın bir örneğini döndürür.

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

Seri hale getirilmiş XML çıktısı şöyle görünür:

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

Şema isteğe bağlı bir öğe içeriyorsa (minOccurs = '0') veya şema varsayılan bir değer içeriyorsa iki seçeneğiniz vardır. Bir seçenek, aşağıdaki kodda gösterildiği gibi varsayılan değeri belirtmek için kullanmaktır System.ComponentModel.DefaultValueAttribute .

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

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

Bir diğer seçenek, XmlSerializer tarafından tanınması için özel bir desen kullanarak bir Boole alanı oluşturmak ve alanda XmlIgnoreAttribute uygulamaktır. Desen, propertyNameSpecified biçiminde oluşturulur. Örneğin, "MyFirstName" adlı bir alan varsa, "MyFirstName" adlı XML öğesinin oluşturulup oluşturulmayacağını belirten XmlSerializer "MyFirstNameSpecified" adlı bir alan da oluşturursunuz. Bu, aşağıdaki örnekte gösterilmiştir.

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

Varsayılan serileştirmeyi geçersiz kıl

Ayrıca, uygun özniteliklerden birini oluşturup sınıfın bir örneğine ekleyerek herhangi bir nesne kümesinin ve bunların alanlarının ve özelliklerinin serileştirmesini XmlAttributes geçersiz kılabilirsiniz. Serileştirmeyi bu şekilde geçersiz kılmanın iki kullanımı vardır: İlk olarak, kaynağa erişiminiz olmasa bile DLL'de bulunan nesnelerin serileştirmesini denetleyebilir ve artırabilirsiniz; ikinci olarak, bir dizi serileştirilebilir sınıf oluşturabilir, ancak nesneleri birden çok şekilde seri hale getirebilirsiniz. Daha fazla ayrıntı için sınıfına XmlAttributeOverrides ve Nasıl yapılır: Türetilmiş Sınıfların Serileştirmesini Denetleme bölümüne bakın.

Bir nesneyi seri hale getirmek için yöntemini çağırın Serialize . Bir nesneyi seri durumdan çıkarmak için yöntemini çağırın Deserialize .

XML belgesine XML ad alanları eklemek için bkz XmlSerializerNamespaces. .

Uyarı

XmlSerializer veya IEnumerable gerçekleştiren ICollection sınıflara özel işlem uygular. Uygulayan IEnumerable bir sınıf, tek bir parametre alan genel Add bir yöntem uygulamalıdır. Add yönteminin parametresi, Current'den döndürülen değerin üzerindeki GetEnumerator özelliğinden dönen değer ile aynı türde ya da bu türün temel sınıflarından biri olmalıdır. ICollection ek olarak CollectionBase uygulayan bir sınıf (örneğin IEnumerable), bir tamsayı alan ortak bir Item dizinli özelliğe (C#'de dizin oluşturucu) sahip olmalı ve tamsayı türünde ortak bir Count özelliğe sahip olmalıdır. Add yönteminin parametresi, Item özelliğinden döndürülen ile aynı türde veya bu türün tabanlarından biri olmalıdır. ICollection sınıflarını uygulayanlar için, serileştirilecek değerler Item çağrılmadan, dizinli GetEnumerator özelliğinden alınır.

Bir nesneyi seri durumdan çıkarmak için geçici dizine (TEMP ortam değişkeni tarafından tanımlandığı gibi) yazma izniniz olmalıdır.

Dinamik olarak oluşturulan derlemeler

Performansı artırmak için XML serileştirme altyapısı, belirtilen türleri seri hale getirmek ve seri durumdan çıkarmak için derlemeleri dinamik olarak oluşturur. Altyapı bu derlemeleri bulur ve yeniden kullanır. Bu davranış yalnızca aşağıdaki oluşturucular kullanılırken oluşur:

XmlSerializer.XmlSerializer(Type)

XmlSerializer.XmlSerializer(Type, String)

Diğer oluşturuculardan herhangi birini kullanırsanız, aynı derlemenin birden çok sürümü oluşturulur ve hiçbir zaman yüklenmez, bu da bellek sızıntısına ve düşük performansa neden olur. En kolay çözüm, daha önce bahsedilen iki oluşturucudan birini kullanmaktır. Aksi takdirde, aşağıdaki örnekte gösterildiği gibi derlemeleri Hashtable içinde önbelleğe almalısınız.

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.

ArrayList ve genel listenin seri hale getirilmesi

, XmlSerializer aşağıdakileri seri hale getiremez veya seri durumdan çıkaramaz:

• Diziler: ArrayList
• Diziler: List<T>

İmzasız Long numaralandırmalarının seri hale getirilmesi

XmlSerializer Aşağıdaki koşullar doğruysa, bir numaralandırmayı seri hale getirmek için örneği oluşturulamaz: Numaralandırma işaretsiz uzun türündedir (ulongC#'de) ve numaralandırma 9.223.372.036.854.775.807'den büyük bir değere sahip herhangi bir üye içerir. Örneğin, aşağıdakiler serileştirilemez.

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

Kullanım dışı türler

XmlSerializer sınıfı olarak [Obsolete]işaretlenmiş nesneleri serileştirmez.