Partager via

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 DataSet est écrit en tant que DiffGram, il remplit le DiffGram avec toutes les informations nécessaires pour recréer avec précision le contenu, mais pas le schéma, de DataSet, y compris les valeurs de colonne des versions de lignes Original et Current, les informations d'erreur 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, lors du chargement du contenu d’un DataSet xml à l’aide de la ReadXml méthode, ou lors de l’écriture du contenu d’un DataSet fichier XML à l’aide de la WriteXml méthode, vous pouvez spécifier que le contenu doit être lu ou écrit en tant que 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 <diffgram> élément.

Pour générer un Diffgram

  1. Générez une liste des tables racine (autrement dit, les tables sans parent).

  2. Pour chaque table et ses descendants dans la liste, écrivez la version actuelle de toutes les lignes dans la première section Diffgram.

  3. Pour chaque table du DataSet, écrivez la version d’origine de toutes les lignes, le cas échéant, dans la <before> section de la Diffgram.

  4. Pour les lignes qui ont des erreurs, écrivez le contenu de l’erreur dans la <errors> section du Diffgram.

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

Pour traiter un Diffgram

  1. Traitez la première section du DiffGram qui contient la version actuelle des lignes.

  2. Traitez la deuxième ou la <before> section qui contient la version de ligne 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.

  3. 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 originale 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 des informations d'erreur pour une ligne particulière dans le 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 Descriptif
id Utilisé pour associer les éléments des blocs <diffgr:before> et <diffgr:errors> aux éléments 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 :

Inséré
Identifie une Added ligne.

a modifié
Identifie une ligne Modified qui contient une version de ligne Original dans le bloc <diffgr:before>. Notez que Deleted les lignes auront une version de ligne Original dans le bloc <diffgr:before>, mais qu’aucun élément annoté n’est présent 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 <diffgr:errors> bloc.
Error Contient le texte du RowError d’un élément particulier dans un 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 Descriptif
RowOrder Conserve l'ordre des lignes des données d'origine et identifie l'index d'une ligne dans un DataTable donné.
Caché Identifie une colonne comme ayant une ColumnMapping propriété 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. Par conséquent, il existe une Current ligne avec un diffgr :id de « Customers1 » dans le < bloc DataInstance>, et une Original ligne avec un diffgr :id de « Customers1 » dans le <diffgr:before> bloc. La ligne avec un CustomerID de « ANATR » inclut une RowError, elle est donc annotée avec diffgr:hasErrors="true", et il y a un élément associé dans <diffgr:errors> bloc.

<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

  • Last updated on