Bagikan melalui

Kelas System.Xml.XmlWriter

Kelas XmlWriter menulis data XML ke aliran, file, pembaca teks, atau string. Ini mendukung rekomendasi W3C Extensible Markup Language (XML) 1.0 (edisi keempat) dan Namespace dalam XML 1.0 (edisi ketiga).

Anggota kelas XmlWriter memungkinkan Anda untuk:

  • Verifikasi bahwa karakter adalah karakter XML legal dan bahwa elemen dan nama atribut adalah nama XML yang valid.
  • Verifikasi bahwa dokumen XML terbentuk dengan baik.
  • Kodekan byte biner sebagai Base64 atau BinHex, dan tulis teks yang dihasilkan.
  • Teruskan nilai dengan menggunakan tipe bahasa umum runtime alih-alih string, untuk menghindari melakukan konversi nilai secara manual.
  • Tulis beberapa dokumen ke satu aliran output.
  • Tulis nama yang valid, nama yang memenuhi syarat, dan token nama.

Membuat penulis XML

Untuk membuat instans XmlWriter, gunakan metode XmlWriter.Create. Untuk menentukan fitur yang ingin Anda aktifkan pada penulis XML, masukkan XmlWriterSettings ke Create. Jika tidak, pengaturan default digunakan. Create Lihat halaman referensi untuk detailnya.

Tentukan format output

Kelas XmlWriterSettings ini mencakup beberapa properti yang mengontrol bagaimana XmlWriter output diformat:

Harta benda Deskripsi
Encoding Menentukan pengodean teks yang akan digunakan. Defaultnya adalah Encoding.UTF8.
Indent Menunjukkan apakah akan mengindentasi elemen. Defaultnya adalah false (tidak ada indentasi).
IndentChars Menentukan string karakter yang akan digunakan saat mengindentasi. Defaultnya adalah dua spasi.
NewLineChars Menentukan string karakter yang akan digunakan untuk pemisah baris. Pengaturan bawaan adalah \r\n (pengembalian kursor, ganti baris) untuk platform non-Unix, dan \n (ganti baris) untuk platform Unix.
NewLineHandling Menentukan cara menangani karakter baris baru.
NewLineOnAttributes Menunjukkan apakah akan menulis atribut pada baris baru. Indent harus diatur ke true ketika menggunakan properti ini. Defaultnya adalah false.
OmitXmlDeclaration Menunjukkan apakah akan menulis deklarasi XML. Defaultnya adalah false.

Properti Indent dan IndentChars mengontrol bagaimana spasi putih yang tidak signifikan diformat. Misalnya, untuk mengindentasi node elemen:

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 Gunakan untuk menulis setiap atribut pada baris baru dengan satu tingkat indentasi tambahan:

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)

Kesuaian data

Penulis XML menggunakan dua properti dari XmlWriterSettings kelas untuk memeriksa kesuaian data:

  • Properti CheckCharacters menginstruksikan penulis XML untuk memeriksa karakter dan melempar XmlException pengecualian jika ada karakter di luar rentang hukum, seperti yang didefinisikan oleh W3C.

  • Properti ConformanceLevel mengonfigurasi penulis XML untuk memeriksa apakah aliran yang ditulis mematuhi aturan untuk dokumen XML 1.0 yang terbentuk dengan baik atau fragmen dokumen, seperti yang didefinisikan oleh W3C. Tiga tingkat kesesuaian dijelaskan dalam tabel berikut. Defaultnya adalah Document. Untuk detailnya, lihat properti XmlWriterSettings.ConformanceLevel dan enumerasi System.Xml.ConformanceLevel.

    Tingkat Deskripsi
    Document Output XML sesuai dengan aturan untuk dokumen XML 1.0 yang terbentuk dengan baik dan dapat diproses oleh prosesor yang sesuai.
    Fragment Output XML sesuai dengan aturan untuk fragmen dokumen XML 1.0 yang terbentuk dengan baik.
    Auto Penulis XML menentukan tingkat pemeriksaan konformasi mana yang akan diterapkan (dokumen atau fragmen) berdasarkan data masuk.

Menuliskan elemen-elemen

Anda dapat menggunakan metode berikut XmlWriter untuk menulis simpul elemen. Misalnya, lihat metode yang tercantum.

Gunakan Untuk
WriteElementString Tulis seluruh simpul elemen, termasuk nilai string.
WriteStartElement Untuk menuliskan nilai elemen dengan menggunakan beberapa panggilan metode. Misalnya, Anda dapat memanggil WriteValue untuk menulis nilai yang ditik, WriteCharEntity untuk menulis entitas karakter, WriteAttributeString untuk menulis atribut, atau Anda dapat menulis elemen turunan. Ini adalah versi yang lebih canggih dari metode WriteElementString.

Untuk menutup elemen, Anda memanggil WriteEndElement metode atau WriteFullEndElement .
WriteNode Untuk menyalin simpul elemen yang ditemukan pada posisi objek XmlReader atau XPathNavigator saat ini. Ketika dipanggil, ia menyalin semuanya dari objek sumber ke XmlWriter instans.

Tulis atribut

Anda dapat menggunakan metode berikut XmlWriter untuk menulis atribut pada node elemen. Metode ini juga dapat digunakan untuk membuat deklarasi namespace pada elemen, seperti yang dibahas di bagian berikutnya.

Gunakan Untuk
WriteAttributeString Untuk menulis seluruh simpul atribut, termasuk nilai string.
WriteStartAttribute Untuk menetapkan nilai atribut melalui beberapa panggilan metode. Misalnya, Anda dapat memanggil WriteValue untuk menulis nilai yang ditik. Ini adalah versi yang lebih canggih dari metode WriteElementString.

Untuk menutup elemen , Anda memanggil WriteEndAttribute metode .
WriteAttributes Untuk menyalin semua atribut yang ditemukan pada posisi XmlReader objek saat ini. Atribut yang ditulis tergantung pada jenis simpul yang saat ini diposisikan pembaca:

- Untuk node atribut, ia menulis atribut saat ini, dan kemudian atribut lainnya sampai tag penutup elemen.
- Untuk node elemen, ia menulis semua atribut yang terkandung oleh elemen .
- Untuk simpul deklarasi XML, ia menulis semua atribut dalam deklarasi.
- Untuk semua jenis node lainnya, metode melemparkan pengecualian.

Menangani namespace

Namespace digunakan untuk memenuhi syarat elemen dan nama atribut dalam dokumen XML. Awalan namespace mengaitkan elemen dan atribut dengan namespace, yang pada gilirannya terkait dengan referensi URI. Namespace menciptakan keunikan nama elemen dan atribut dalam dokumen XML.

mempertahankan XmlWriter tumpukan namespace yang sesuai dengan semua namespace yang ditentukan dalam cakupan namespace saat ini. Saat menulis elemen dan atribut, Anda dapat menggunakan namespace dengan cara berikut:

  • Deklarasikan namespace secara manual dengan menggunakan WriteAttributeString metode . Ini dapat berguna ketika Anda tahu cara terbaik mengoptimalkan jumlah deklarasi namespace. Misalnya, lihat metode WriteAttributeString(String, String, String, String).

  • Ambil alih deklarasi namespace saat ini dengan namespace baru. Dalam kode berikut, metode WriteAttributeString mengubah URI namespace untuk prefiks "x" dari "123" menjadi "abc".

    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()

    Kode menghasilkan string XML berikut:

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

  • Tentukan awalan namespace saat menulis atribut atau elemen. Banyak metode yang digunakan untuk menulis elemen dan atribut memungkinkan Anda melakukan ini. Misalnya, metode WriteStartElement(String, String, String) menulis tag mulai dan mengaitkannya dengan namespace serta awalan tertentu.

Menulis data yang dititik

Metode WriteValue menerima objek runtime bahasa umum (CLR), mengonversi nilai input ke representasi stringnya sesuai dengan aturan konversi jenis data bahasa definisi skema XML (XSD), dan menulisnya dengan menggunakan metode WriteString. Ini lebih mudah daripada menggunakan metode di XmlConvert kelas untuk mengonversi data yang diekstrak menjadi nilai string sebelum menulisnya.

Saat menulis ke teks, nilai yang diketik diserialisasikan ke teks dengan menggunakan aturan untuk jenis skema tersebut XmlConvert .

Untuk jenis data XSD default yang sesuai dengan jenis CLR, lihatlah metode WriteValue.

XmlWriter juga dapat digunakan untuk menulis ke penyimpanan data XML. Misalnya, XPathNavigator kelas dapat membuat XmlWriter objek untuk membuat simpul untuk XmlDocument objek. Jika penyimpanan data memiliki informasi skema yang tersedia untuknya, WriteValue metode melemparkan pengecualian jika Anda mencoba mengonversi ke jenis yang tidak diizinkan. Jika penyimpanan data tidak memiliki informasi skema yang tersedia untuknya, metode ini memperlakukan semua nilai sebagai jenis WriteValue.

Tutup penulis XML

Saat Anda menggunakan XmlWriter metode untuk menghasilkan XML, elemen dan atribut tidak ditulis sampai Anda memanggil Close metode . Misalnya, jika Anda menggunakan XmlWriter untuk mengisi XmlDocument objek, Anda tidak akan dapat melihat elemen dan atribut tertulis dalam dokumen target hingga Anda menutup XmlWriter instans.

Pemrograman asinkron

Sebagian besar metode XmlWriter memiliki rekan asinkron yang memiliki "Asinkron" di akhir nama metode mereka. Misalnya, setara asinkron dari WriteAttributeString adalah WriteAttributeStringAsync.

WriteValue Untuk metode , yang tidak memiliki mitra asinkron, konversikan nilai pengembalian ke string dan gunakan metode sebagai gantinyaWriteStringAsync.

Pertimbangan keamanan

Pertimbangkan hal berikut saat bekerja dengan kelas XmlWriter:

  • Pengecualian yang dilemparkan oleh XmlWriter dapat mengungkapkan informasi jalur yang tidak ingin Anda gelembungkan ke aplikasi. Aplikasi Anda harus menangkap pengecualian dan memprosesnya dengan tepat.

  • XmlWriter tidak memvalidasi data apa pun yang diteruskan ke WriteDocType metode atau WriteRaw . Anda sebaiknya jangan meneruskan data sembarang ke metode-metode ini.

  • Last updated on