DiffGram (ADO.NET)

Articolo
05/20/2011

DiffGram è un formato XML che consente di identificare le versioni correnti e originali degli elementi di dati.Il formato DiffGram viene utilizzato dal tipo DataSet per caricare e conservare il contenuto e per serializzare tale contenuto in modo da consentirne il trasporto tramite una connessione di rete.Quando un tipo DataSet viene scritto in formato DiffGram, tale DiffGram viene compilato con tutte le informazioni necessarie per ricreare accuratamente il contenuto, ma non lo schema, del tipo DataSet, inclusi i valori di colonna per le versioni di riga Original e Current, le informazioni relative agli errori delle righe e l'ordine delle righe.

Quando si invia e si recupera un tipo DataSet da un servizio Web XML, il formato DiffGram viene utilizzato implicitamente.Inoltre, quando si carica il contenuto di un oggetto DataSet da XML utilizzando il metodo ReadXml o quando si scrive il contenuto di un oggetto DataSet in XML utilizzando il metodo WriteXml, è possibile specificare che il contenuto deve essere letto o scritto come DiffGram.Per ulteriori informazioni, vedere Caricamento di un DataSet da XML (ADO.NET) e Scrittura del contenuto di DataSet come dati XML (ADO.NET).

Benché il formato DiffGram venga utilizzato principalmente da .NET Framework come formato di serializzazione per il contenuto di un tipo DataSet, è possibile utilizzare i DiffGram per modificare i dati delle tabelle di un database Microsoft SQL Server 2000.

Un Diffgram viene generato scrivendo il contenuto di tutte le tabelle in un elemento <diffgram>.

Per generare un Diffgram

Generare un elenco di tabelle radice, ovvero senza elementi padre.
Per ogni tabella e per i relativi discendenti nell'elenco, scrivere la versione corrente di tutte le righe nella prima sezione del Diffgram.
Per ogni tabella in DataSet, scrivere la versione originale di tutte le righe, se disponibile, nella sezione **<before>**del Diffgram.
Per le righe che contengono errori, scrivere il contenuto dell'errore nella sezione <errors> del Diffgram.

Un Diffgram viene elaborato nell'ordine a partire dal file XML fino alla fine.

Per elaborare un Diffgram

Elaborare la prima sezione del Diffgram che contiene la versione corrente delle righe.

Elaborare la seconda sezione, ovvero**<before>**, che contiene la versione originale delle righe modificate ed eliminate.

Nota
Se una riga è contrassegnata come eliminata, con l'operazione di eliminazione è possibile che vengano rimossi anche i relativi discendenti, a seconda della proprietà Cascade dell'oggetto DataSet corrente.

Elaborare la sezione <errors>.Impostare le informazioni sull'errore per la riga e la colonna specificate per ogni elemento di questa sezione.

Nota
Se si imposta XmlWriteMode su Diffgram, il contenuto dell'oggetto DataSet di destinazione può essere diverso da quello dell'oggetto DataSet originale.

Formato DiffGram

Il formato DiffGram è suddiviso in tre sezioni: i dati correnti, i dati originali (o "precedenti") e una sezione relativa agli errori, come illustrato nell'esempio seguente.

<?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>

Il formato DiffGram è costituito dai seguenti blocchi di dati:

<DataInstance>
Il nome di questo elemento, DataInstance, viene utilizzato a scopo esplicativo nella presente documentazione.Un elemento DataInstance rappresenta un tipo DataSet o una riga di un tipo DataTable.Il termine DataInstance viene sostituito nell'elemento dal nome del tipo DataSet o DataTable.In questo blocco del formato DiffGram sono contenuti i dati correnti, indipendentemente dalle eventuali modifiche a tali dati.L'annotazione diffgr:hasChanges consente di identificare un elemento o una riga a cui sono state apportate modifiche.
<diffgr:before>
In questo blocco del formato DiffGram è contenuta la versione originale di una riga.Gli elementi di questo blocco corrispondono agli elementi del blocco DataInstance mediante l'annotazione diffgr:id .
<diffgr:errors>
In questo blocco del formato DiffGram sono contenute informazioni relative agli errori per una particolare riga del blocco DataInstance.Gli elementi di questo blocco corrispondono agli elementi del blocco DataInstance mediante l'annotazione diffgr:id .

Annotazioni DiffGram

I DiffGram utilizzano diverse annotazioni per correlare elementi presenti nei vari blocchi di DiffGram, che rappresentano diverse versioni di riga o informazioni relative agli errori nel tipo DataSet.

Nella tabella seguente vengono descritte le annotazioni DiffGram definite nello spazio dei nomi DiffGram urn:schemas-microsoft-com:xml-diffgram-v1.

Annotazione	Descrizione
id	Consente di accoppiare gli elementi presenti nei blocchi <diffgr:before> e <diffgr:errors> e gli elementi presenti nel blocco *<DataInstance>.Per i valori dell'annotazione diffgr:id* viene utilizzato il seguente formato: [NomeTabella][IdentificatoreRiga].Ad esempio: <Customers diffgr:id="Customers1">.
parentId	Identifica l'elemento padre dell'elemento corrente nel blocco *<DataInstance>.Per i valori dell'annotazione diffgr:parentId* viene utilizzato il seguente formato: [NomeTabella][IdentificatoreRiga].Ad esempio: <Orders diffgr:parentId="Customers1">.
hasChanges	Identifica come modificata una riga del blocco *<DataInstance>.Per l'annotazione hasChanges* viene utilizzato uno dei due valori seguenti: inserted Identifica una riga Added. modified Identifica una riga Modified contenente una versione di riga Original nel blocco <diffgr:before>.Si noti che alle righe Deleted viene associata una versione di riga Original nel blocco <diffgr:before>, ma nel blocco *<DataInstance>* non è presente alcun elemento annotato.
hasErrors	Identifica una riga nel blocco *<DataInstance>* con un RowError.L'elemento di errore viene inserito nel blocco <diffgr:errors>.
Errore	In questa annotazione è contenuto il testo del RowError per un particolare elemento del blocco <diffgr:errors>.

Quando legge o scrive il proprio contenuto come DiffGram, il tipo DataSet include ulteriori annotazioni.Nella tabella seguente vengono descritte tali annotazioni, definite nello spazio dei nomi urn:schemas-microsoft-com:xml-msdata.

Annotazione	Descrizione
RowOrder	Conserva l'ordine di riga dei dati originali e identifica l'indice di una riga in un oggetto DataTable specifico.
Hidden	Identifica una colonna con una proprietà ColumnMapping impostata su MappingType.Hidden.L'attributo viene scritto nel formato msdata:hidden[NomeColonna]="valore".Ad esempio: <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">. Notare che le colonne nascoste vengono scritte come attributo DiffGram solo se in tali colonne sono presenti dati.In caso contrario, vengono ignorate.

RowOrder

Conserva l'ordine di riga dei dati originali e identifica l'indice di una riga in un oggetto DataTable specifico.

Hidden

Identifica una colonna con una proprietà ColumnMapping impostata su MappingType.Hidden.L'attributo viene scritto nel formato msdata:hidden[NomeColonna]="valore".Ad esempio: <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">.

Notare che le colonne nascoste vengono scritte come attributo DiffGram solo se in tali colonne sono presenti dati.In caso contrario, vengono ignorate.

Esempio di DiffGram

Di seguito viene riportato un esempio di formato DiffGram.In questo esempio viene mostrato il risultato di un aggiornamento a una riga prima della conferma delle modifiche.La riga con CustomerID pari a "ALFKI" è stata modificata, ma non aggiornata.Nel blocco <DataInstance> è quindi presente una riga Current con valore per diffgr:id pari a "Customers1" e nel blocco <diffgr:before> è presente una riga Original con valore per diffgr:id pari a "Customers1".Nella riga con CustomerID "ANATR" è incluso un RowError, quindi nella riga è presente l'annotazione diffgr:hasErrors="true" e nel blocco <diffgr:errors> si trova un elemento correlato.

<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>