DiffGram
DiffGram 是 XML 格式，可用來識別資料項目的目前和原始版本。DataSet 使用 DiffGram 格式來載入和保存其內容，並將其內容序列化以透過網路連接傳輸。將 DataSet 寫為 DiffGram 時，會把所有必要資訊填入 DiffGram，以正確地重新建立 DataSet 的內容 (而非結構描述)，包括來自原始和目前資料列版本的資料行值、資料列錯誤資訊和資料列順序。
從 XML Web Service 傳送和擷取 DataSet 時，會隱含使用 DiffGram 格式。此外，使用 ReadXml 方法從 XML 載入 DataSet 的內容，或使用 WriteXml 方法在 XML 中寫入 DataSet 的內容時，您可以選擇將內容當做 DiffGram 來讀取或寫入。如需詳細資訊，請參閱從 XML 載入 DataSet 和將 DataSet 寫為 XML 資料。
雖然 DiffGram 格式在 .NET Framework 中主要是用來當做 DataSet 內容的序列化格式，您也可以使用 DiffGrams 來修改 Microsoft SQL Server 資料庫中的資料表資料。
DiffGram 格式
DiffGram 格式分成三個區段：目前資料、原始 (或「過去」) 資料和錯誤區段，如下列範例所示。
<?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>
DiffGram 格式由下列資料區塊組成：
- <DataInstance>
項目的名稱 DataInstance，是用來在這份文件中作為解釋之用。DataInstance 項目代表 DataSet 或 DataTable 的資料列。除了 DataInstance 之外，項目還會包含 DataSet 或 DataTable 的名稱。無論這個 DiffGram 格式區塊是否經過修改，此區塊都會包含目前的資料。已修改過的項目或資料列是以 diffgr:hasChanges 註釋來識別。
- <diffgr:before>
這個 DiffGram 格式的區塊包含資料列的原始版本。此區塊中的項目會使用 diffgr:id 註釋對應至 DataInstance 區塊中的項目。
- <diffgr:errors>
這個 DiffGram 格式的區塊包含 DataInstance 區塊中特定資料列的錯誤資訊。此區塊中的項目會使用 diffgr:id 註釋對應至 DataInstance 區塊中的項目。
DiffGram 註釋
DiffGrams 使用數種註釋，將來自不同 DiffGram 區塊的項目關聯起來，這些 DiffGram 區塊分別代表 DataSet 中的不同資料列版本或錯誤訊息。
下列表格說明 DiffGram 命名空間 urn:schemas-microsoft-com:xml-diffgram-v1 中定義的 DiffGram 註釋。
| 註釋 | 說明 |
|---|---|
id |
作用是將 <DataInstance> 區塊中的項目與 <diffgr:before> 和 <diffgr:errors> 區塊中的項目進行配對。具有 diffgr:id 註釋的值使用 [TableName][RowIdentifier] 格式。例如： |
parentId |
識別 <DataInstance> 區塊中哪個項目是目前項目的父項目。具有 diffgr:parentId 註釋的值使用 [TableName][RowIdentifier] 格式。例如： |
hasChanges |
將 <DataInstance> 區塊中的資料識別為已修改。hasChanges 註釋可以具有以下三個值之一：
|
hasErrors |
用 RowError 識別 <DataInstance> 區塊中的資料列。會將錯誤項目置於 <diffgr:errors> 區塊中。 |
Error |
包含 <diffgr:errors> 區塊中特定項目的 RowError 文字。 |
DataSet 將其內容讀取或寫為 DiffGram 時，亦會包含其他註釋。下列表格說明這些在命名空間 urn:schemas-microsoft-com:xml-msdata 中定義的其他註釋。
| 註釋 | 說明 |
|---|---|
RowOrder |
保留原始資料的資料列順序，並識別特定 DataTable 中資料列的索引。 |
Hidden |
識別 ColumnMapping 屬性設定為 MappingType.Hidden 的資料行。屬性是以格式 msdata:hidden[ColumnName]="value" 撰寫的。例如： 請注意，隱藏的資料行只有在包含資料時才會寫為 DiffGram 屬性。否則便會予以忽略。 |
範例 DiffGram
以下是 DiffGram 格式的範例。這個範例顯示在確認變更前，資料表中資料列的更新結果。CustomerID 為 "ALFKI" 的資料列已經被修改，但尚未更新。這樣一來，<DataInstance> 區塊中會有具 "Customers1" 之 diffgr:id 的 Current 資料列，而 <diffgr:before> 區塊中則會有具 "Customers1" 之 diffgr:id 的 Original 資料列。CustomerID 為 "ANATR" 的資料列包括 RowError，所以它會加上 diffgr:hasErrors="true" 的註釋且在 <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>
請參閱
概念
從 XML 載入 DataSet
將 DataSet 寫為 XML 資料