DiffGram

發行項
07/15/2024

DiffGram 是 XML 格式，可用來識別資料項目的目前和原始版本。 DataSet 使用 DiffGram 格式以載入保存內容，並將內容序列化以透過網路連接傳輸。將 DataSet 寫為 DiffGram 時，會把所有必要資訊填入 DiffGram，以正確重新建立 DataSet 的內容 (而非結構描述)，包括來自 Original 與 Current 資料列版本的資料行值、資料列錯誤資訊及資料列順序。

從 XML Web Service 傳送和擷取 DataSet 時，會隱含使用 DiffGram 格式。此外，使用 ReadXml 方法從 XML 載入 DataSet 的內容，或使用 WriteXml 方法在 XML 中寫入 DataSet 的內容時，您可以指定將內容當做 DiffGram 來讀取或寫入。如需詳細資訊，請參閱從 XML 載入資料集與將資料集內容寫入為 XML 資料。

雖然 DiffGram 格式在 .NET Framework 中主要是用來當做 DataSet 內容的序列化格式，您也可以使用 DiffGrams 修改 Microsoft SQL Server 資料庫中的資料表資料。

Diffgram 是藉由將所有資料表的內容寫入至 <diffgram> 元素而產生。

若要產生 Diffgram

產生根資料表 (即不具任何父項目的資料表) 的清單。
針對清單中的每個資料表及其子代 (Descendant)，在 Diffgram 的第一個區段中寫出所有資料列的目前版本。
針對 DataSet 的每個資料表，在 Diffgram 的 <before> 區段寫出所有資料列的原始版本 (若有)。
針對有錯誤的資料列，在 Diffgram 的 <errors> 區段寫入錯誤內容。

Diffgram 會從 XML 檔案的開頭依序處理到結尾。

若要處理 Diffgram

處理 Diffgram 的第一個區段，其中包含資料列的目前版本。
處理第二個或 <before> 區段，這些區段包含已修改與已刪除資料列的原始資料列版本。

注意

如果資料列標示為已刪除，則刪除作業可能也會刪除該資料列的子代，根據目前 Cascade 的 DataSet 屬性而定。
處理 <errors> 區段。針對此區段中每個項目的指定資料列和資料行設定錯誤資訊。

注意

如果將 XmlWriteMode 設定為 Diffgram，則目標 DataSet 和原始 DataSet 的內容可能不同。

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 的資料列。項目會包含 DataSet 或 DataTable 的名稱 (而非 DataInstance)。無論這個 DiffGram 格式區塊是否經過修改，都會包含目前的資料。已修改過的項目或資料列是以 diffgr:hasChanges 註釋來識別。

<diffgr:before>
這個 DiffGram 格式的區塊包含資料列的原始版本。此區塊的項目會使用 diffgr:id 註釋，對應至 DataInstance 區塊的元素。

<diffgr:errors>
這個 DiffGram 格式的區塊包含 DataInstance 區塊特定資料列的錯誤資訊。此區塊的項目會使用 diffgr:id 註釋，對應至 DataInstance 區塊的元素。

DiffGram 註釋

DiffGram 使用數種註釋，將來自不同 DiffGram 區塊的項目關聯起來，這些 DiffGram 區塊分別代表 DataSet 中的不同資料列版本或錯誤訊息。

下列表格說明 DiffGram 命名空間 urn:schemas-microsoft-com:xml-diffgram-v1 定義的 DiffGram 註釋。

註釋	描述
id	作用是將 <DataInstance> 區塊的元素與 <diffgr:before> 與 <diffgr:errors> 區塊的元素進行配對。具有 diffgr:id 註釋的值使用 `[TableName][RowIdentifier]` 格式。例如： `<Customers diffgr:id="Customers1">` 。
parentId	識別 <DataInstance> 區塊哪個元素是目前元素的父元素。具有 diffgr:parentId 註釋的值使用 `[TableName][RowIdentifier]` 格式。例如： `<Orders diffgr:parentId="Customers1">` 。
hasChanges	將 <DataInstance> 區塊的資料列識別為已修改。 hasChanges 註釋可以具有以下兩個值的其中之一： inserted 識別 Added 資料列。 modified 識別 <diffgr:before> 區塊包含 Original 資料列版本的 Modified 資料列。請注意，Deleted 資料列會有 <diffgr:before> 區塊的 Original 資料列版本，但不會有 <DataInstance> 區塊的標註元素。
hasErrors	使用 RowError 識別 <DataInstance> 區塊的資料列。錯誤元素會置於 <diffgr:errors> 區塊。
錯誤	包含 <diffgr:errors> 區塊特定元素的 RowError 文字。

DataSet 將其內容讀取或寫為 DiffGram 時，亦會包含其他附註。下列表格說明這些在命名空間 urn:schemas-microsoft-com:xml-msdata 定義的其他註釋。

註釋	描述
RowOrder	保留原始資料的資料列順序，並識別特定 DataTable 中資料列的索引。
Hidden	識別 ColumnMapping 屬性設定為 MappingType.Hidden 的資料行。屬性是以 msdata:hidden[ColumnName]="value" 的格式所撰寫。例如： `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">` 。請注意，隱藏的資料行只有在包含資料時才會寫為 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>

共用方式為