DiffGrams
Un DiffGram est un format XML qui identifie la version actuelle et la version d'origine d'éléments de données. L'objet DataSet utilise le format DiffGram pour charger son contenu et le rendre persistent, ainsi que pour le sérialiser en vue de son transport via une connexion réseau. Lorsqu'un objet DataSet est écrit en tant que DiffGram, il remplit le DiffGram en y plaçant toutes les informations requises pour recréer précisément le contenu, mais pas le schéma, de l'objet DataSet, y compris des valeurs de colonne provenant des versions de la ligne, des informations d'erreur de ligne et de l'ordre des lignes Original et Current.
Lors de l'envoi et de l'extraction d'un objet DataSet à partir d'un service Web XML, le format DiffGram est implicitement utilisé. En outre, lorsque vous chargez le contenu d'un objet DataSet à partir de XML à l'aide de la méthode ReadXml ou lorsque vous écrivez le contenu d'un objet DataSet en XML à l'aide de la méthode WriteXml, vous pouvez indiquer que le contenu sera lu ou écrit sous la forme d'un DiffGram. Pour plus d'informations, voir Chargement d'un DataSet à partir de XML et Écriture d'un DataSet sous forme de données XML.
Si le format DiffGram est principalement utilisé par le .NET Framework en tant que format de sérialisation pour le contenu d'un objet DataSet, vous pouvez aussi l'utiliser pour modifier des données dans les tables d'une base de données Microsoft SQL Server.
Format DiffGram
Le format DiffGram est divisé en trois sections : les données actuelles, les données d'origine (« before ») et la section des erreurs (« errors »), comme le montre l'exemple suivant.
<?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>
Le format DiffGram est constitué des blocs de données suivants :
- <DataInstance>
Le nom de cet élément, DataInstance, est utilisé à des fins d'explication dans cette documentation. Un élément DataInstance représente un DataSet ou une ligne dans un DataTable. À la place de DataInstance devrait figurer le nom du DataSet ou du DataTable. Ce bloc du format DiffGram contient les données actuelles, qu'elles aient ou non été modifiées. Un élément, ou ligne, ayant subi une modification est reconnaissable à l'annotation diffgr:hasChanges.
- <diffgr:before>
Ce bloc du format DiffGram contient la version d'origine d'une ligne. Les éléments de ce bloc sont mis en correspondance avec les éléments du bloc DataInstance à l'aide de l'annotation diffgr:id.
- <diffgr:errors>
Ce bloc du format DiffGram contient les informations d'erreur concernant une ligne donnée du bloc DataInstance. Les éléments de ce bloc sont mis en correspondance avec les éléments du bloc DataInstance à l'aide de l'annotation diffgr:id.
Annotations DiffGram
Les DiffGrams utilisent plusieurs annotations pour relier les éléments des différents blocs DiffGram qui représentent différentes versions d'une ligne ou des informations d'erreur dans le DataSet.
Le tableau suivant décrit les annotations DiffGram définies dans l'espace de noms DiffGram urn:schemas-microsoft-com:xml-diffgram-v1.
| Annotation | Description |
|---|---|
id |
Sert à apparier les éléments des blocs <diffgr:before> et <diffgr:errors> avec ceux du bloc <DataInstance>. Les valeurs de l'annotation diffgr:id se présentent sous la forme [TableName][RowIdentifier]. Par exemple : |
parentId |
Identifie l'élément du bloc <DataInstance> qui est le parent de l'élément en cours. Les valeurs de l'annotation diffgr:parentId se présentent sous la forme [TableName][RowIdentifier]. Par exemple : |
hasChanges |
Identifie une ligne du bloc <DataInstance> comme ayant été modifiée. L'annotation hasChanges peut avoir l'une des trois valeurs suivantes :
|
hasErrors |
Identifie une ligne du bloc <DataInstance> avec un RowError. L'élément porteur de l'erreur est placé dans le bloc <diffgr:errors>. |
Error |
Contient le texte du RowError relatif à un élément donné du bloc <diffgr:errors>. |
Le DataSet inclut annotations supplémentaires lors de la lecture ou de l'écriture de son contenu en tant que DiffGram. Le tableau suivant décrit ces annotations supplémentaires, définies dans l'espace de noms urn:schemas-microsoft-com:xml-msdata.
| Annotation | Description |
|---|---|
RowOrder |
Conserve l'ordre des lignes des données d'origine et identifie l'index d'une ligne dans un DataTable donné. |
Hidden |
Identifie une colonne comme ayant une propriété ColumnMapping avec pour valeur MappingType.Hidden. L'attribut est écrit sous la forme msdata:hidden[ColumnName]="value". Par exemple : Notez que les colonnes masquées ne sont écrites sous la forme d'un attribut DiffGram que si elles contiennent des données. Sinon, elles sont ignorées. |
Exemple de DiffGram
Un exemple du format DiffGram vous est proposé ci-après. Cet exemple illustre le résultat d'une mise à jour effectuée sur une ligne d'une table avant validation des modifications. La ligne dont le CustomerID est « ALFKI » a été modifiée, mais pas mise à jour. En conséquence, il y a une ligne Current avec une annotation diffgr:id « Customers1 » dans le bloc <DataInstance> et une ligne Original avec une annotation diffgr:id « Customers1 » dans le bloc <diffgr:before>. La ligne dont le CustomerID est « ANATR » comprend un RowError. Elle porte donc l'annotation diffgr:hasErrors="true" et un élément connexe figure dans le bloc <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>
Voir aussi
Concepts
Chargement d'un DataSet à partir de XML
Écriture d'un DataSet sous forme de données XML
Autres ressources
Utilisation de XML dans un DataSet
Utilisation de DataSets dans ADO.NET