DiffGram

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 tipo DataSet da XML utilizzando il metodo ReadXml o quando si scrive il contenuto di un tipo DataSet in XML utilizzando il metodo WriteXml, è possibile scegliere di leggere o scrivere il contenuto come DiffGram. Per ulteriori informazioni, vedere Caricamento di un DataSet da XML e Scrittura di un DataSet sotto forma di dati XML.

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.

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 seguenti tre valori: inserted Identifica una riga Added. modified Identifica una riga Modified contenente una versione di riga Original nel blocco <diffgr:before>. Notare che alle righe Deleted viene associata la versione di riga Original nel blocco <diffgr:before>, ma nel blocco <DataInstance> non è presente alcun elemento con annotazioni. descent Identifica un elemento in cui sono stati modificati più elementi figlio di una relazione padre-figlio.
hasErrors	Identifica una riga nel blocco <DataInstance> con un RowError. L'elemento di errore viene inserito nel blocco <diffgr:errors>.
Error	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 particolare tipo DataTable.
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>

Vedere anche

Concetti

Caricamento di un DataSet da XML
Scrittura di un DataSet sotto forma di dati XML

Altre risorse

Utilizzo di XML in un DataSet
Utilizzo di DataSet in ADO.NET