DiffGram (ADO.NET)

更新：November 2007

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

当从 XML Web 服务发送和检索 DataSet 时，将隐式地使用 DiffGram 格式。 此外，当使用 ReadXml 方法从 XML 加载 DataSet 的内容时，或当使用 WriteXml 方法以 XML 编写 DataSet 的内容时，可以指定内容作为 DiffGram 读取或写入。有关更多信息，请参见从 XML 中加载数据集 (ADO.NET) 和以 XML 数据形式编写数据集内容 (ADO.NET)。

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

通过将所有表的内容写入到 <diffgram> 元素中可生成 Diffgram。

生成 Diffgram

1. 生成根表（即没有任何父级的表）的列表。

2. 对于列表中每个表及其子代，在 Diffgram 的第一部分中写出所有行的当前版本。

3. 对于 DataSet 中的每个表，在 Diffgram 的 <before> 部分中写出所有行的原始版本（如果有）。

4. 对于有错误的行，在 Diffgram 的 <errors> 部分中写入错误内容。

将按照从 XML 文件的开头到结尾的顺序处理 Diffgram。

处理 Diffgram

1. 处理包含行当前版本的 Diffgram 的第一部分。

2. 处理包含已修改行和已删除行的原始行版本的第二部分或 <before> 部分。

   说明：
   如果某行标记为已删除，则删除操作还可删除该行的子代，具体取决于当前 DataSet 的 Cascade 属性。

3. 处理 <errors> 部分。 为本部分中各项的指定行和列设置错误信息。

说明：
如果将 XmlWriteMode 设置为 Diffgram，则目标 DataSet 和原始 DataSet 的内容可能会不同。

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>

请参见

概念

从 XML 中加载数据集 (ADO.NET)

以 XML 数据形式编写数据集内容 (ADO.NET)

其他资源

在数据集中使用 XML (ADO.NET)

DataSet、DataTable 和 DataView (ADO.NET)