Kelas System.Xml.XmlWriter

Artikel
01/04/2024

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

XmlWriter Anggota kelas 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 jenis runtime bahasa umum alih-alih string, untuk menghindari harus 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 XmlWriter instans, gunakan XmlWriter.Create metode . Untuk menentukan kumpulan fitur yang ingin Anda aktifkan pada penulis XML, teruskan XmlWriterSettings ke Create metode . 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:

Properti	Deskripsi
Encoding	Menentukan pengodean teks yang akan digunakan. Default 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. Defaultnya adalah `\r\n` (pengembalian gerbong, umpan baris) untuk platform non-Unix, dan `\n` (umpan 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. Default adalah `false`.
OmitXmlDeclaration	Menunjukkan apakah akan menulis deklarasi XML. Default adalah `false`.

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

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. Default adalah Document. Untuk detailnya, lihat XmlWriterSettings.ConformanceLevel properti dan System.Xml.ConformanceLevel enumerasi.

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.

Menulis elemen

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

Menggunakan	Untuk
WriteElementString	Tulis seluruh simpul elemen, termasuk nilai string.
WriteStartElement	Untuk menulis 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 metode yang WriteElementString lebih canggih. 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.

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

Menggunakan	Untuk
WriteAttributeString	Untuk menulis seluruh simpul atribut, termasuk nilai string.
WriteStartAttribute	Untuk menulis nilai atribut menggunakan beberapa panggilan metode. Misalnya, Anda dapat memanggil WriteValue untuk menulis nilai yang ditik. Ini adalah versi metode yang WriteElementString lebih canggih. 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 layanan

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 membuat elemen dan keunikan nama 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 layanan dengan cara berikut:

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

Ambil alih deklarasi namespace saat ini dengan namespace baru. Dalam kode berikut, metode mengubah WriteAttributeString URI namespace layanan untuk awalan "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, WriteStartElement(String, String, String) metode menulis tag mulai dan mengaitkannya dengan namespace dan awalan tertentu.

Menulis data yang dititik

Metode ini 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, lihat WriteValue metode .

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 memperlakukan WriteValue semua nilai sebagai xsd:anySimpleType jenis.

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 XmlWriter besar metode memiliki rekan asinkron yang memiliki "Asinkron" di akhir nama metode mereka. Misalnya, setara WriteAttributeString asinkron 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 XmlWriter kelas :

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 tidak boleh meneruskan data arbitrer ke metode ini.

Share via