Share via

2.3.2.1 DataInstance Element

The DataInstance element contains one first-level child element per DataRow object of data in the DataSet object’s tables (hereafter, first-level child elements of the DataInstance element are referred to as "DataRow elements"). Each DataRow in the DataSet MUST be serialized by using the XML element (defined in the <schema> element of the DiffGram) that corresponds to its DataTable object.

The DataRow values in the DataInstance element MUST be the current DataRow values in the DataSet at the time the DataSet is serialized into the DiffGram structure. That is, the DataInstance element MUST reflect all changes made to the DataRow values within the DataSet and the new rows that were added after the DataSet was last synchronized with its data source. Rows that were deleted from the DataSet MUST NOT appear in the DataInstance element.

The following is an example of a DataInstance element that can appear in a DiffGram.

 <SalesDS>
 <Customers diffgr:id="Customers1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
   <CustId>A</CustId>
   <CustName>C1</CustName>
 </Customers>
 <Customers diffgr:id="Customers2" msdata:rowOrder="1">
   <CustId>B</CustId>
   <CustName>C2</CustName>
 </Customers>
 <Customers diffgr:id="Customers3" msdata:rowOrder="2" diffgr:hasChanges="modified">
   <CustId>C</CustId>
   <CustName>C3</CustName>
 </Customers>
 <Customers diffgr:id="Customers5" msdata:rowOrder="4" diffgr:hasErrors="true">
   <CustId>E</CustId>
   <CustName>C5</CustName>
 </Customers>
 </SalesDS>

The following rules apply to the DataRow elements within the DataInstance element:

  • Each DataRow element MUST have a urn:schemas-microsoft-com:xml-diffgram-v1:id attribute. The string value of this attribute acts as the DataRow identifier within the scope of the DiffGram Data element. The DataInstance element MUST NOT have two DataRow elements with the same value for the urn:schemas-microsoft-com:xml-diffgram-v1:id attribute.

  • Each DataRow element MUST have a urn:schemas-microsoft-com:xml-msdata:rowOrder attribute whose value MUST be an integer that specifies the 0-based ordinal position of the DataRow that the element represents within its DataTable.

  • Row elements that represent rows that were added or modified in the DataSet after it was last synchronized with its data source MUST have the urn:schemas-microsoft-com:xml-diffgram-v1:hasChanges attribute. This attribute’s value MUST be "inserted" for rows that were added to the DataSet after it was last synchronized with its data source, and the value MUST be "modified" for rows that were changed after the DataSet was last synchronized with its data source.

  • Only DataRow elements that represent rows that are associated with error information that is included in the <errors> element of the DiffGram MUST have the urn:schemas-microsoft-com:xml-diffgram-v1:hasErrors attribute set to "true".

  • Each DataRow element that is in a DataRelation as a child MUST have a urn:schemas-microsoft-com:xml-diffgram-v1:parentId attribute where the value is equal to the id attribute of the parent DataRow.

  • All DataColumn objects for which the ColumnMapping property equals Attribute MUST write out the name of the DataColumn as the attribute name and the value of that DataColumn within the DataRow element.

  • All DataColumn objects for which the ColumnMapping property equals Element MUST write out the name of the DataColumn as the child element of the DataRow element along with the corresponding value of that DataColumn within the DataRow element.

  • For all DataColumn objects for which the ColumnMapping property equals Hidden, the msdata:hidden[ColumnName] attribute MUST be used. For example, <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner"> would specify a hidden column named ContactTitle.

  • Only if the schema for this data instance is nested MUST the data instance be nested as well. The following is an example of this.

     <Orders diffgr:id="Orders3" msdata:rowOrder="2" diffgr:hasChanges="inserted">
         <Id>1</Id>
            <OrderDetails diffgr:id="OrderDetails4" msdata:rowOrder="3" diffgr:hasChanges="inserted">
         <Id>10</Id>
           <OrdersId>1</OrdersId>
         </OrderDetails>
  </Orders>