DiffGrams

Article
05/10/2023

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 alimente 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 les valeurs de colonne provenant des versions de ligne Original et Current, les informations relatives aux erreurs de ligne et l’ordre des lignes.

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 DataSet à partir de XML à l’aide de la méthode ReadXml, ou lorsque vous écrivez le contenu d’un DataSet en XML à l’aide de la méthode WriteXml, vous pouvez spécifier que le contenu doit être lu ou écrit sous la forme d’un DiffGram. Pour plus d’informations, consultez Chargement d’un DataSet à partir de XML et Écriture du contenu d’un DataSet en tant que 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.

Un DiffGram est généré en écrivant le contenu de toutes les tables dans un élément <diffgram>.

Pour générer un Diffgram

Générez une liste des tables racine (autrement dit, les tables sans parent).
Pour chaque table et ses descendants dans la liste, écrivez la version actuelle de toutes les lignes dans la première section Diffgram.
Pour chaque table du DataSet, écrivez la version d’origine de toutes les lignes (le cas échéant) dans la section <before> du Diffgram.
Pour les lignes qui comportent des erreurs, écrivez le contenu des erreurs dans la section <errors> du DiffGram.

Un DiffGram est traité dans l'ordre du début du fichier XML à la fin.

Pour traiter un Diffgram

Traitez la première section du DiffGram qui contient la version actuelle des lignes.
Traitez la deuxième section ou la section <before> qui contient la version d’origine des lignes modifiées et supprimées.

Notes

Si une ligne est marquée comme supprimée, l'opération de suppression peut aussi supprimer les descendants de la ligne, en fonction de la propriété Cascade du DataSet en cours.
Traitez la section <errors>. Définissez les informations d'erreur pour la ligne et la colonne spécifiées pour chaque élément dans cette section.

Notes

Si vous affectez XmlWriteMode à DiffGram, le contenu du DataSet cible et du DataSet d'origine peut être différent.

Format DiffGram

Le format DiffGram est divisé en trois sections : les données actuelles, les données d'origine (ou « avant ») et une section d'erreurs, comme indiqué dans 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 d’une DataTable. À la place de DataInstance devrait figurer le nom du DataSet ou de la DataTable. Ce bloc du format DiffGram contient les données actuelles, qu'elles aient ou non été modifiées. Un élément, ou une 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 : `<Customers diffgr:id="Customers1">`.
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 : `<Orders diffgr:parentId="Customers1">`.
hasChanges	Identifie une ligne du bloc <DataInstance> comme ayant été modifiée. L’annotation hasChanges peut avoir l’une des deux valeurs suivantes : inserted Identifie une ligne ajoutée (Added). a modifié Identifie une ligne modifiée (Modified) qui contient une version de la ligne d’origine (Original) dans le bloc <diffgr:before>. Notez que les lignes supprimées (Deleted) auront une version de la ligne d’origine (Original) dans le bloc <diffgr:before>, mais qu’il n’y aura pas d’élément annoté dans le bloc <DataInstance>.
hasErrors	Identifie une ligne du bloc <DataInstance> comportant un élément RowError. L’élément d’erreur est placé dans le bloc <diffgr:errors>.
Error	Contient le texte RowError d’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, qui sont 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 définie sur MappingType.Hidden. L’attribut est écrit sous la forme msdata:hidden[ColumnName]="value". Par exemple : <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">.

Notez que les colonnes masquées ne sont écrites sous la forme d'un attribut DiffGram que si elles contiennent des données. Autrement, elles sont ignorées.

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 définie sur MappingType.Hidden. L’attribut est écrit sous la forme msdata:hidden[ColumnName]="value". Par exemple : `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">`. Notez que les colonnes masquées ne sont écrites sous la forme d'un attribut DiffGram que si elles contiennent des données. Autrement, 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 paramètre CustomerID est défini sur « ANATR » comprend un élément RowError. Elle porte donc l’annotation diffgr:hasErrors="true" et un élément associé 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>

Partager via