System.Xml.XmlWriter sınıfı

  • Makale

XmlWriter sınıfı XML verilerini bir akışa, dosyaya, metin okuyucuya veya dizeye yazar. XML 1.0 (üçüncü sürüm) önerilerinde W3C Genişletilebilir Biçimlendirme Dili (XML) 1.0 (dördüncü sürüm) ve Ad Alanları'nı 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

Örnek XmlWriter oluşturmak için yöntemini kullanın XmlWriter.Create . XML yazıcıda etkinleştirmek istediğiniz özellik kümesini belirtmek için yöntemine Create bir XmlWriterSettings 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:

Özellik Açıklama
Encoding Kullanılacak metin kodlamasını belirtir. Varsayılan değer: Encoding.UTF8.
Indent Öğelerin girintilenip girintili 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. Unix dışı platformlar için varsayılan değer (satır başı, satır beslemesi) ve \n Unix platformları için (satır besleme) şeklindedir \r\n .
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 olarak true 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)

Ek bir girinti düzeyine sahip yeni bir satıra her özniteliği yazmak için öğesini NewLineOnAttributes kullanı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 özelliğine XmlWriterSettings.ConformanceLevel ve numaralandırmaya System.Xml.ConformanceLevel bakın.

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

Öğe yazma

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

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

öğesini kapatmak için veya WriteFullEndElement yöntemini çağırırsınızWriteEndElement.
WriteNode Bir veya XPathNavigator nesnesinin geçerli konumunda bulunan bir XmlReader öğ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.

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

öğesini kapatmak için yöntemini çağırırsınız WriteEndAttribute .
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 ve öğe kapanış etiketine kadar özniteliklerin geri kalanını yazar.
- 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öntemi bir özel durum oluşturur.

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.

geçerli XmlWriter 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, xml şema tanımı dili (XSD) veri türü dönüştürme kurallarına göre giriş değerini dize gösterimine WriteString dönüştürür ve yöntemini kullanarak bunu 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.

Metne yazarken, yazılan değer, bu şema türü için kurallar kullanılarak metne XmlConvert 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 kullanabileceği şema bilgileri varsa, WriteValue izin verilmeyen bir türe dönüştürmeye çalışırsanız yöntem bir özel durum oluşturur. 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

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

Zaman uyumsuz programlama

Yöntemlerin ç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.

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

Güvenlik konuları

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

  • tarafından XmlWriter oluşan özel durumlar, uygulamaya kabarmasını istemediğiniz yol bilgilerini açıklayabilir. Uygulamanızın özel durumları yakalaması ve uygun şekilde işlemesi gerekir.

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