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

  • Makale

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 hatta veya XmlAttribute nesneleri biçiminde XmlElement eklenmiş XML gibi 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, Xsd.exe çalıştırarak şemaya kesin olarak yazılan ve seri hale getirildiğinde şemaya uyması için özniteliklerle açıklama ekleyen bir sınıf kümesi oluşturabilirsiniz.

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. XmlSerializer Xsd.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 Consortium belgesi, Basit Nesne Erişim Protokolü (SOAP) 1.1'in 5. bölümüne uygun olmalıdır, ile XmlTypeMappingoluşturmanız XmlSerializer 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. türündeki XmlElementXmlAttribute alanları veya özellikleri kullanarak veya XmlNode kesin olarak yazılan sınıflarınızda 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 bir nesne dizisi döndüren bir alana veya nesne dizisi XmlElementXmlAttribute döndüren bir alana uygulayınXmlAnyAttributeAttribute.

Bir özellik veya alan (örneğin, bir dizi veya bir sınıf örneği), karmaşık bir nesne döndürür, XmlSerializer bir öğe için iç içe geçmiş ana XML belgesi içindeki 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, tarafından XmlSerializertanınan bir Boole alanı oluşturmak ve alanına uygulamak XmlIgnoreAttribute için özel bir desen kullanmaktır. Desen biçiminde oluşturulur propertyNameSpecified. Ö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österilir.

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. .

Not

, XmlSerializer veya ICollectionuygulayan IEnumerable sınıflara özel işlem sağlar. Uygulayan bir sınıf IEnumerable bir ortak uygulamalıdır Add tek parameTResi alan yöntemi. yönteminin Add parametresi, özelliğinden Current döndürülen değerin GetEnumeratorveya bu türün tabanlarından birinin aynı türde olması gerekir. Ek olarak uygulayan ICollection bir sınıfın (örneğinCollectionBase), tamsayı alan bir ortak Item dizinli özelliği (C#'de dizin oluşturucu) olması ve tamsayı türünde bir ortak Count özelliği olması IEnumerable gerekir. yöntemi parametresi Add , özelliğinden Item döndürülen ile aynı türde veya bu türün temellerinden biri olmalıdır. uygulayan ICollectionsınıflar için, serileştirilecek değerler çağrılarak GetEnumeratordeğil, dizinli Item özellikten 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, derlemeleri aşağıdaki örnekte gösterildiği gibi içinde Hashtableö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:

İ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 run time, the following code will fail.
xmlSerializer mySerializer=new XmlSerializer(typeof(LargeNumbers));

Eski türler

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