DiffGram

Artikel
03/02/2024

DiffGram adalah format XML yang mengidentifikasi versi elemen data saat ini dan asli. DataSet menggunakan format DiffGram untuk memuat dan menyimpan kontennya, dan membuat serial kontennya untuk diangkut melalui koneksi jaringan. Ketika ditulis sebagai DiffGram, diisi DiffGram dengan semua informasi yang DataSet diperlukan untuk membuat ulang konten secara akurat, meskipun bukan skema, dari DataSet, termasuk nilai kolom dari versi baris Asli dan Saat Ini, informasi kesalahan baris, dan urutan baris.

Saat mengirim dan mengambil DataSet dari layanan Web XML, format DiffGram digunakan secara implisit. Selain itu, saat memuat konten DataSet xml dari menggunakan metode ReadXml, atau saat menulis konten DataSet dalam XML menggunakan metode WriteXml, Anda dapat menentukan bahwa konten dibaca atau ditulis sebagai DiffGram. Untuk informasi selengkapnya, lihat Memuat Himpunan Data dari XML dan Menulis Konten Himpunan Data sebagai Data XML.

Meskipun format DiffGram terutama digunakan oleh .NET Framework sebagai format serialisasi untuk konten DataSet, Anda juga dapat menggunakan DiffGrams untuk memodifikasi data dalam tabel dalam database Microsoft SQL Server.

Diffgram dihasilkan dengan menulis konten semua tabel ke elemen <diffgram>.

Untuk menghasilkan Diffgram

Buat daftar tabel Akar (yaitu, tabel tanpa induk).
Untuk setiap tabel dan turunannya dalam daftar, tuliskan versi saat ini dari semua baris di bagian Diffgram pertama.
Untuk setiap tabel di DataSet, tuliskan versi asli semua baris, jika ada, di bagian <sebelum> Diffgram.
Untuk baris yang memiliki kesalahan, tulis konten kesalahan di bagian <kesalahan> Diffgram.

Diffgram diproses secara berurutan dari awal file XML hingga akhir.

Untuk memproses Diffgram

Proses bagian pertama Diffgram yang berisi versi baris saat ini.
Proses bagian kedua atau <sebelum> yang berisi versi baris asli dari baris yang diubah dan dihapus.

Catatan

Jika baris ditandai dihapus, operasi penghapusan juga dapat menghapus turunan baris, tergantung pada properti Cascade dari DataSet saat ini.
Proses bagian <kesalahan>. Atur informasi kesalahan untuk baris dan kolom yang ditentukan untuk setiap item di bagian ini.

Catatan

Jika Anda mengatur ke XmlWriteMode Diffgram, konten target DataSet dan DataSet aslinya mungkin berbeda.

Format DiffGram

Format DiffGram dibagi menjadi tiga bagian: data saat ini, data asli (atau "sebelum"), dan bagian kesalahan, seperti yang ditunjukkan dalam contoh berikut.

<?xml version="1.0"?>  
<diffgr:diffgram
         xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"  
         xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1"  
         xmlns:xsd="http://www.w3.org/2001/XMLSchema">  
  
   <DataInstance>  
   </DataInstance>  
  
  <diffgr:before>  
  </diffgr:before>  
  
  <diffgr:errors>  
  </diffgr:errors>  
</diffgr:diffgram>

Format DiffGram terdiri dari blok data berikut:

<DataInstance>
Nama elemen ini, DataInstance, digunakan untuk tujuan penjelasan dalam dokumentasi ini. Elemen DataInstance merepresentasikan DataSet atau baris dari DataTable. Daripada DataInstance, elemen akan berisi nama DataSet atau DataTable. Blok format DiffGram ini berisi data saat ini, baik telah dimodifikasi atau belum. Elemen, atau baris, yang telah dimodifikasi diidentifikasi dengan anotasi diffgr:hasChanges.

<diffgr:before>
Blok format DiffGram ini berisi versi asli baris. Elemen dalam blok ini dicocokkan dengan elemen di blok DataInstance menggunakan anotasi diffgr:id.

<diffgr:errors>
Blok format DiffGram ini berisi informasi kesalahan untuk baris tertentu di blok DataInstance. Elemen dalam blok ini dicocokkan dengan elemen di blok DataInstance menggunakan anotasi diffgr:id.

Anotasi DiffGram

DiffGrams menggunakan beberapa anotasi untuk menghubungkan elemen dari blok DiffGram berbeda yang mewakili versi baris atau informasi kesalahan yang berbeda di DataSet.

Tabel berikut ini menjelaskan anotasi DiffGram yang ditentukan dalam namespace layanan diffGram urn:schemas-microsoft-com:xml-diffgram-v1.

Anotasi	Deskripsi
id	Digunakan untuk memasangkan elemen dalam blok diffgr<:before> dan <diffgr:errors> ke elemen di blok <DataInstance>. Nilai dengan anotasi diffgr:id berada dalam formulir `[TableName][RowIdentifier]`. Sebagai contoh: `<Customers diffgr:id="Customers1">`.
parentId	Mengidentifikasi elemen mana dari < blok DataInstance> yang merupakan elemen induk dari elemen saat ini. Nilai dengan anotasi diffgr:parentId berada dalam formulir `[TableName][RowIdentifier]`. Sebagai contoh: `<Orders diffgr:parentId="Customers1">`.
hasChanges	Mengidentifikasi baris di blok <DataInstance> sebagai dimodifikasi. Anotasi hasChanges dapat memiliki salah satu dari dua nilai berikut: dimasukkan Mengidentifikasi baris Ditambahkan. dimodifikasi Mengidentifikasi baris Yang Dimodifikasi yang berisi versi baris Asli di blok diffgr<:before>. Perhatikan bahwa Baris yang Dihapus akan memiliki versi baris Asli di blok <diffgr:before>, tetapi tidak akan ada elemen anotasi di < blok DataInstance>.
hasErrors	Mengidentifikasi baris di blok <DataInstance> dengan RowError. Elemen kesalahan ditempatkan di blok <diffgr:errors>.
Kesalahan	Berisi teks RowError untuk elemen tertentu di blok <diffgr:errors>.

DataSet menyertakan anotasi tambahan saat membaca atau menulis kontennya sebagai DiffGram. Tabel berikut ini menjelaskan anotasi tambahan ini, yang ditentukan dalam namespace layanan urn:schemas-microsoft-com:xml-msdata.

Anotasi	Deskripsi
RowOrder	Mempertahankan urutan baris data asli dan mengidentifikasi indeks baris dalam tertentu DataTable.
Tersembunyi	Mengidentifikasi kolom karena properti ColumnMapping diatur ke MappingType.Hidden. Atribut ditulis dalam format msdata:hidden[ColumnName]="value". Sebagai contoh: `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">`. Perhatikan bahwa kolom tersembunyi hanya ditulis sebagai atribut DiffGram jika berisi data. Jika tidak, bobot diabaikan.

Sampel DiffGram

Contoh format DiffGram diperlihatkan di bawah ini. Contoh ini memperlihatkan hasil pembaruan ke baris dalam tabel sebelum perubahan diterapkan. Baris dengan CustomerID "ALFKI" telah dimodifikasi, tetapi tidak diperbarui. Akibatnya, ada baris Saat Ini dengan diffgr:id "Customers1" di < blok DataInstance>, dan baris Asli dengan diffgr:id "Customers1" di <blok diffgr:before>. Baris dengan ID Pelanggan "ANATR" menyertakan RowError, sehingga dianotasi dengan diffgr:hasErrors="true" dan ada elemen terkait di blok <diffgr:errors>.

<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">  
  <CustomerDataSet>  
    <Customers diffgr:id="Customers1" msdata:rowOrder="0" diffgr:hasChanges="modified">  
      <CustomerID>ALFKI</CustomerID>  
      <CompanyName>New Company</CompanyName>  
    </Customers>  
    <Customers diffgr:id="Customers2" msdata:rowOrder="1" diffgram:hasErrors="true">  
      <CustomerID>ANATR</CustomerID>  
      <CompanyName>Ana Trujillo Emparedados y Helados</CompanyName>  
    </Customers>  
    <Customers diffgr:id="Customers3" msdata:rowOrder="2">  
      <CustomerID>ANTON</CustomerID>  
      <CompanyName>Antonio Moreno Taquera</CompanyName>  
    </Customers>  
    <Customers diffgr:id="Customers4" msdata:rowOrder="3">  
      <CustomerID>AROUT</CustomerID>  
      <CompanyName>Around the Horn</CompanyName>  
    </Customers>  
  </CustomerDataSet>  
  <diffgr:before>  
    <Customers diffgr:id="Customers1" msdata:rowOrder="0">  
      <CustomerID>ALFKI</CustomerID>  
      <CompanyName>Alfreds Futterkiste</CompanyName>  
    </Customers>  
  </diffgr:before>  
  <diffgr:errors>  
    <Customers diffgr:id="Customers2" diffgr:Error="An optimistic concurrency violation has occurred for this row."/>  
  </diffgr:errors>  
</diffgr:diffgram>

Share via