what is diffgram in asp.net

DiffGram:

The DiffGram is one of the two XML formats that you can use to render DataSet object contents to XML. A good use is reading database data to an XML file to be sent to a Web Service.
ADO.NET introduced the DataSet class to support the disconnected, distributed data-access scenarios. With DataSet, the data retrieved from the database is cached in-memory, in addition to the constraints and relationships among the tables. When the ADO.NET DataSet is serialized as XML (for example, when returning a DataSet from an ASP.NET XML Web service method), the XML format used for DataSet serialization is known as DiffGram. Like Updategrams, DiffGrams also contains the tags that specify the original and new state of data. SQLXML and .NET Managed classes can be used to execute DiffGrams to perform the database updates, however there are many things that are supported by Updategrams and not by DiffGrams (ability to pass parameters being one example).


DiffGrams and DataSet

There are occasions when you want to compare the original data with the current data to get the changes made to the original data. One of the common example is saving data on Web Forms applications. When working with Web based data driven applications, you read data using a DataSet, make some changes to the data and sends data back to the database to save final data. Sending entire DataSet may be a costly affair specially when there are thousands of records in a DataSet. In this scenario, the best practice is to find out the updated rows of a DataSet and send only updated rows back to the database instead of the entire DataSet. This is where the DiffGrams are useful.

Note: Do you remember GetChanges method of DataSet? This method returns the rows that have been modified in the current version in a form of DataSet. This is how a DataSet knows the modified rows.

A DiffGram is an XML format that is used to identify current and original versions of data elements. Since the DataSet uses XML format to store and transfer data, it also use DiffGrams to keep track of the original data and the current data. When a DataSet is written as a DiffGram, not only a DiffGram stores original and current data, it also stores row versions, error information, and their orders.

DiffGram XML Format

The XML format for a DiffGram has three parts - data instance, diffgram before and diffgram errors. The tag represents the data instance part of a diffgram, which represents the current data. The diffgram before is represented by the tag, which represents the original version of the data. The tag represents the diffgram errors part, which stores the errors and related information. The diffgram itself is represented by tag . The XML listed in Listing 1 represents the skeleton of a 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">








Listing 1. A DiffGram format

The sections only store the changed rows and the section only stores the rows that had errors. Each row in a DiffGram is identified with an id and these three sections communicate through this id. For example, if id of a row is "Id1" and it has been modified and had errors,

Besides above discussed three sections, a DiffGram uses other elements. These are described in Table 1.

Table 1 describes the DiffGram elements that are defined in the DiffGram namespace urn:schemas-microsoft-com:xml-diffgram-v1.

Element Description
id
DiffGram id. Normally in the format of [TableName][RowIdentifier]. For example: .
parentId
Parent row of the current row. Normally in the format of [TableName][RowIdentifier]. For example: .
hasChanges Identifies a row in the block as modified. The hasChanges can have one of the three values - inserted, modified, or descent. Value inserted means an Added row, modified means modified row, and descent means children of a parent row have been modified.
hasErrors
Identifies a row in the block with a RowError. The error element is placed in the block.

Error
Contains the text of the RowError for a particular element in the block.


There are two more elements a DataSet generated DiffGrams can have and these elements are RowOrder and Hidden. The RowOrder is the row order of the original data and identifies the index of a row in a particular DataTable. The Hidden identifies a column as having a ColumnMapping property set to MappingType.Hidden.

Now let's see an example of DiffGrams. The code listed in Listing 1 reads data from Employees tables and write in an XML document in DiffGram format.

Dim connectionString As String = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\Northwind.mdb"
Dim sql As String = "SELECT EmployeeID, FirstName, LastName, Title FROM Employees"
Dim conn As OleDbConnection = Nothing
Dim ds As DataSet = Nothing
' Create and open connection
conn = New OleDbConnection(connectionString)
If conn.State <> ConnectionState.Open Then
conn.Open()
End If ' Create a data adapter
Dim adapter As New OleDbDataAdapter(sql, conn)
' Create and fill a DataSet
ds = New DataSet("TempDtSet")
adapter.Fill(ds, "DtSet")
' Write XML in DiffGram format
ds.WriteXml("DiffGramFile.xml", XmlWriteMode.DiffGram)
' Close connection
If conn.State = ConnectionState.Open Then
conn.Close()
End If