DiffGram

.NET Framework 开发人员指南

DiffGram

DiffGram 是用于标识数据元素的当前和原始版本的 XML 格式。DataSet 使用 DiffGram 格式来加载和保持其内容，并将其内容序列化，以便通过网络连接来进行传输。当 DataSet 以 DiffGram 形式来编写时，它会为 DiffGram 填充所有必要的信息，以便精确地重新创建 DataSet 的内容（但不包括其架构），其中包括 Original 和 Current 行版本、行错误信息以及行顺序的列值。

当从 XML Web 服务发送和检索 DataSet 时，将隐式地使用 DiffGram 格式。此外，当使用 ReadXml 方法从 XML 中加载 DataSet 的内容，或者使用 WriteXml 方法以 XML 形式编写 DataSet 的内容时，可以选择以 DiffGram 格式来读写其内容。有关更多信息，请参见从 XML 中加载 DataSet 和以 XML 数据形式编写 DataSet。

虽然 DiffGram 格式主要由 .NET Framework 用作 DataSet 内容的序列化格式，但也可以使用 DiffGram 来修改 Microsoft SQL Server 数据库中表的数据。

DiffGram 格式

DiffGram 格式分为三个部分：当前数据、原始（即“before”）数据和错误部分，如以下示例所示。

复制代码

<?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 批注

DiffGram 使用一些批注来使来自不同 DiffGram 块的元素相关，这些块表示 DataSet 中的不同行版本或错误信息。

下表描述在 DiffGram 命名空间 urn:schemas-microsoft-com:xml-diffgram-v1 中定义的 DiffGram 批注。

批注	说明
id	用于将 <diffgr:before> 和 <diffgr:errors> 块中的元素与 <DataInstance> 块中的元素配对。带有 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> 块中将不存在批注元素。 descent 标识其中有一个或多个来自父子关系的子级已被修改的元素。
hasErrors	用 RowError 标识 <DataInstance> 块中的行。错误元素放置在 <diffgr:errors> 块中。
Error	包含 <diffgr:errors> 块中特定元素的 RowError 的文本。

当以 DiffGram 格式读写 DataSet 的内容时，还包含附加的批注。下表描述在 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> 块中有一个 diffgr:id 为“Customers1”的 Current 行，<diffgr:before> 块中有一个 diffgr:id 为“Customers1”的 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>