Aracılığıyla paylaş

System.Xml.XmlWriter sınıfı

XmlWriter sınıfı XML verilerini bir akışa, dosyaya, metin okuyucuya veya dizeye yazar. W3C Genişletilebilir Biçimlendirme Dili (XML) 1.0 (dördüncü sürüm) ve XML'deki Ad Alanları 1.0 (üçüncü sürüm) önerilerini destekler.

Sınıfın XmlWriter üyeleri aşağıdakileri yapmanızı sağlar:

  • Karakterlerin yasal XML karakterleri olduğunu ve öğe ve öznitelik adlarının geçerli XML adları olduğunu doğrulayın.
  • XML belgesinin düzgün biçimlendirilmiş olduğunu doğrulayın.
  • İkili baytları Base64 veya BinHex olarak kodlayın ve sonuçta elde edilen metni yazın.
  • Değer dönüştürmelerini el ile gerçekleştirmek zorunda kalmamak için dizeler yerine ortak dil çalışma zamanı türlerini kullanarak değerleri geçirin.
  • Bir çıkış akışına birden çok belge yazın.
  • Geçerli adlar, nitelenmiş adlar ve ad belirteçleri yazın.

XML yazıcısı oluşturma

XmlWriter örneğini oluşturmak için XmlWriter.Create yöntemini kullanın. XML yazıcıda etkinleştirmek istediğiniz özellik kümesini belirtmek için XmlWriterSettings'yi Create yöntemine geçirin. Aksi takdirde, varsayılan ayarlar kullanılır. Create Ayrıntılar için başvuru sayfalarına bakın.

Çıkış biçimini belirtin

sınıfı, XmlWriterSettings çıkışın nasıl XmlWriter biçimlendirildiğini denetleyen çeşitli özellikler içerir:

Mülkiyet Açıklama
Encoding Kullanılacak metin kodlamasını belirtir. Varsayılan değer: Encoding.UTF8.
Indent Öğelerin girintili olup olmayacağını gösterir. Varsayılan değerdir false (girinti yok).
IndentChars Girintileme sırasında kullanılacak karakter dizesini belirtir. Varsayılan değer iki boşlukdur.
NewLineChars Satır sonları için kullanılacak karakter dizesini belirtir. \r\n (satır başı, satır beslemesi) Unix dışı platformlar için varsayılan değerdir ve \n (satır besleme) Unix platformları için varsayılan değerdir.
NewLineHandling Yeni satır karakterlerinin nasıl işleneceğini belirtir.
NewLineOnAttributes Özniteliklerin yeni bir satıra yazılıp yazılmayacağını gösterir. Indent bu özellik kullanılırken true olarak ayarlanmalıdır. Varsayılan değer: false.
OmitXmlDeclaration XML bildirimi yazıp yazmayacağını gösterir. Varsayılan değer: false.

Indent ve IndentChars özellikleri, önemsiz boşlukların nasıl biçimlendirildiğini denetler. Örneğin, öğe düğümlerini girintili yapmak için:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

NewLineOnAttributes öğesini kullanarak her özelliğini bir sonraki satıra bir seviye daha girintili olarak yazın.

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

Veri uyumluluğu

XML yazıcısı, veri uyumluluğu olup olmadığını denetlemek için sınıfından XmlWriterSettings iki özellik kullanır:

  • özelliği, CheckCharacters XML yazıcısına karakterleri denetlemesini ve W3C tarafından tanımlandığı gibi herhangi bir karakter yasal aralığın dışındaysa bir XmlException özel durum oluşturmasını bildirir.

  • ConformanceLevel özelliği, YAZıLAN akışın, W3C tarafından tanımlandığı gibi iyi biçimlendirilmiş bir XML 1.0 belgesi veya belge parçasının kurallarına uygun olup olmadığını denetlemek için XML yazıcısını yapılandırmaktadır. Üç uyumluluk düzeyi aşağıdaki tabloda açıklanmıştır. Varsayılan değer: Document. Ayrıntılar için XmlWriterSettings.ConformanceLevel özelliği ve System.Xml.ConformanceLevel numaralandırmasına bakın.

    Seviye Açıklama
    Document XML çıkışı, iyi biçimlendirilmiş bir XML 1.0 belgesinin kurallarına uygundur ve uyumlu işlemciler tarafından işlenebilir.
    Fragment XML çıkışı, iyi biçimlendirilmiş xml 1.0 belge parçasının kurallarına uygundur.
    Auto XML yazıcısı, gelen verilere göre hangi uyumluluk denetimi düzeyinin uygulanacağını (belge veya parça) belirler.

Öğeleri yaz

Öğe düğümleri yazmak için aşağıdaki XmlWriter yöntemleri kullanabilirsiniz. Örnekler için listelenen yöntemlere bakın.

Kullan İçin
WriteElementString Dize değeri de dahil olmak üzere tüm öğe düğümünü yazın.
WriteStartElement Bir öğe değerini birden çok yöntem çağrısı kullanarak yazmak için. Örneğin, yazılı bir değer yazmak için WriteValue, bir karakter varlığı yazmak için WriteCharEntity, bir öznitelik yazmak için WriteAttributeString çağırabilir veya bir alt öğe yazabilirsiniz. Bu, yöntemin daha gelişmiş bir sürümüdür WriteElementString .

elementi kapatmak için WriteEndElement veya WriteFullEndElement yöntemini çağırırsınız.
WriteNode XmlReader veya XPathNavigator nesnesinin geçerli konumundaki bir öğe düğümünü kopyalamak için. Çağrıldığında, kaynak nesnedeki her şeyi örneğe XmlWriter kopyalar.

Öznitelikleri yazma

Öğe düğümlerine öznitelik yazmak için aşağıdaki XmlWriter yöntemleri kullanabilirsiniz. Bu yöntemler, sonraki bölümde açıklandığı gibi bir öğede ad alanı bildirimleri oluşturmak için de kullanılabilir.

Kullan İçin
WriteAttributeString Bir metin değeri de dahil olmak üzere tüm öznitelik düğümünü yazmak.
WriteStartAttribute Öznitelik değerini birden çok yöntem çağrısı kullanarak yazmak için. Örneğin, tipli bir değeri yazmak için WriteValue öğesini çağırabilirsiniz. Bu, yöntemin daha gelişmiş bir sürümüdür WriteElementString .

Öğeyi kapatmak için WriteEndAttribute yöntemini çağırırsınız.
WriteAttributes Bir XmlReader nesnenin geçerli konumunda bulunan tüm öznitelikleri kopyalamak için. Yazılan öznitelikler, okuyucunun şu anda konumlandırılmış olduğu düğümün türüne bağlıdır:

- Bir öznitelik düğümü için geçerli özniteliği yazar, ardından öğe kapanış etiketine kadar geri kalan öznitelikleri de ekler.
- Bir öğe düğümü için, öğesinin içerdiği tüm öznitelikleri yazar.
- BIR XML bildirim düğümü için bildirimdeki tüm öznitelikleri yazar.
- Diğer tüm düğüm türleri için yöntem bir istisna fırlatır.

Ad alanlarını işleme

Ad alanları, xml belgesindeki öğe ve öznitelik adlarını nitelemek için kullanılır. Ad alanı ön ekleri, öğeleri ve öznitelikleri ad alanlarıyla ilişkilendirir ve bu da URI başvuruları ile ilişkilidir. Ad alanları, xml belgesinde öğe ve öznitelik adı benzersizliği oluşturur.

XmlWriter geçerli ad alanı kapsamında tanımlanan tüm ad alanlarına karşılık gelen bir ad alanı yığını tutar. Öğeleri ve öznitelikleri yazarken ad alanlarını aşağıdaki yollarla kullanabilirsiniz:

  • yöntemini kullanarak ad alanlarını el ile bildirin WriteAttributeString . Bu, ad alanı bildirim sayısını en iyi şekilde nasıl iyileştirebileceğinizi bildiğinizde yararlı olabilir. Bir örnek için yöntemine WriteAttributeString(String, String, String, String) bakın.

  • Geçerli ad alanı bildirimini yeni bir ad alanıyla geçersiz kılın. Aşağıdaki kodda WriteAttributeString yöntemi, ön ekin ad alanı URI'sini "x" olarak "123""abc"değiştirir.

    writer.WriteStartElement("x", "root", "123");
writer.WriteStartElement("item");
writer.WriteAttributeString("xmlns", "x", null, "abc");
writer.WriteEndElement();
writer.WriteEndElement();

    writer.WriteStartElement("x", "root", "123")
writer.WriteStartElement("item")
writer.WriteAttributeString("xmlns", "x", Nothing, "abc")
writer.WriteEndElement()
writer.WriteEndElement()

    Kod aşağıdaki XML dizesini oluşturur:

    <x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

  • Öznitelikleri veya öğeleri yazarken bir ad alanı ön eki belirtin. Öğe ve öznitelik yazmak için kullanılan yöntemlerin çoğu bunu yapmanıza olanak tanır. Örneğin, WriteStartElement(String, String, String) yöntemi bir başlangıç etiketi yazar ve bunu belirtilen ad alanı ve ön ek ile ilişkilendirir.

Yazılan verileri yazma

WriteValue yöntemi, ortak dil çalışma zamanı (CLR) nesnesini kabul eder, giriş değerini XML Şema Tanımı Dili (XSD) veri türü dönüştürme kurallarına göre dize gösterimine dönüştürür ve WriteString yöntemini kullanarak çıktı olarak yazar. Bu, yazılan verileri yazmadan önce dize değerine dönüştürmek için sınıfındaki XmlConvert yöntemleri kullanmaktan daha kolaydır.

Metin yazılırken, girilen değer, bu şema türü için XmlConvert kuralları kullanılarak metne serileştirilir.

CLR türlerine karşılık gelen varsayılan XSD veri türleri için yöntemine WriteValue bakın.

bir XmlWriter XML veri deposuna yazmak için de kullanılabilir. Örneğin, XPathNavigator sınıfı bir XmlWriter nesne için düğüm oluşturmak üzere bir XmlDocument nesnesi oluşturabilir. Veri deposunun elinde şema bilgileri varsa, WriteValue izin verilmeyen bir türe dönüştürmeye çalıştığınızda yöntem bir hata fırlatır. Veri deposunda şema bilgileri yoksa, WriteValue yöntemi tüm değerleri bir xsd:anySimpleType tür olarak değerlendirir.

XML yazıcısını kapatma

XmlWriter yöntemlerini XML çıkışı için kullandığınızda, siz Close yöntemini çağırana kadar öğeler ve öznitelikler yazılmaz. Örneğin, XmlWriter bir XmlDocument nesneyi doldurmak için kullanıyorsanız, XmlWriter örneğini kapatana kadar hedef belgedeki yazılı öğeleri ve öznitelikleri göremezsiniz.

Zaman uyumsuz programlama

Çoğu XmlWriter yöntem, adlarının sonunda "Async" olan zaman uyumsuz karşılıklarına sahiptir. Örneğin, zaman uyumsuz eşdeğeri WriteAttributeString şeklindedir WriteAttributeStringAsync.

Asenkron karşılığı olmayan WriteValue yöntemi için dönüş değerini bir dizeye dönüştürün ve bunun yerine WriteStringAsync yöntemini kullanın.

Güvenlikle ilgili dikkat edilmesi gerekenler

sınıfıyla XmlWriter çalışırken aşağıdakileri göz önünde bulundurun:

  • XmlWriter tarafından atılan istisnalar, uygulamanıza yukarıya çıkmasını istemediğiniz yol bilgilerini açıklayabilir. Uygulamanızın özel durumları yakalaması ve uygun şekilde işlemesi gerekir.

  • XmlWriterveya WriteDocType yöntemine WriteRaw geçirilen verileri doğrulamaz. Bu yöntemlere rastgele veriler geçirmemelisiniz.