DiffGramDiffGrams

DiffGram è un formato XML che consente di identificare le versioni correnti e originali degli elementi di dati.A DiffGram is an XML format that identifies current and original versions of data elements. Il formato DiffGram viene usato 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.The DataSet uses the DiffGram format to load and persist its contents, and to serialize its contents for transport across a network connection. Quando un DataSet viene scritto come DiffGram, tale DiffGram viene compilato con tutte le informazioni necessarie per ricreare accuratamente il contenuto, anche se non lo schema, del DataSet, inclusi sia i valori della colonna di originale e corrente versioni delle righe, le informazioni sull'errore di riga e l'ordine delle righe.When a DataSet is written as a DiffGram, it populates the DiffGram with all the necessary information to accurately recreate the contents, though not the schema, of the DataSet, including column values from both the Original and Current row versions, row error information, and row order.

Quando si invia e si recupera un tipo DataSet da un servizio Web XML, il formato DiffGram viene usato implicitamente.When sending and retrieving a DataSet from an XML Web service, the DiffGram format is implicitly used. Inoltre, quando si carica il contenuto di un DataSet da XML usando il ReadXml (metodo), o quando si scrive il contenuto di un DataSet in XML usando il WriteXml metodo, è possibile specificare che il contenuto è essere letto o scritto come DiffGram.Additionally, when loading the contents of a DataSet from XML using the ReadXml method, or when writing the contents of a DataSet in XML using the WriteXml method, you can specify that the contents be read or written as a DiffGram. Per altre informazioni, vedere caricamento di un DataSet da XML e scrittura di contenuti di DataSet come dati XML.For more information, see Loading a DataSet from XML and Writing DataSet Contents as XML Data.

Benché il formato DiffGram venga usato principalmente da .NET Framework come formato di serializzazione per il contenuto di un tipo DataSet, è possibile usare i DiffGram per modificare i dati delle tabelle di un database Microsoft SQL Server.While the DiffGram format is primarily used by the .NET Framework as a serialization format for the contents of a DataSet, you can also use DiffGrams to modify data in tables in a Microsoft SQL Server database.

Un Diffgram viene generato scrivendo il contenuto di tutte le tabelle in un <diffgram > elemento.A Diffgram is generated by writing the contents of all tables to a <diffgram> element.

Per generare un DiffgramTo generate a Diffgram

  1. Generare un elenco di tabelle radice, ovvero senza elementi padre.Generate a list of Root tables (that is, tables without any parent).

  2. Per ogni tabella e per i relativi discendenti nell'elenco, scrivere la versione corrente di tutte le righe nella prima sezione del Diffgram.For each table and its descendants in the list, write out the current version of all rows in the first Diffgram section.

  3. Per ogni tabella nel DataSet, scrivere la versione originale di tutte le righe, se disponibile, nella <prima > sezione del Diffgram.For each table in the DataSet, write out the original version of all rows, if any, in the <before> section of the Diffgram.

  4. Per le righe che contengono errori, scrivere il contenuto dell'errore nella <errori > sezione del Diffgram.For rows that have errors, write the error content in the <errors> section of the Diffgram.

Un Diffgram viene elaborato nell'ordine a partire dal file XML fino alla fine.A Diffgram is processed in order from beginning of the XML file to the end.

Per elaborare un DiffgramTo process a Diffgram

  1. Elaborare la prima sezione del Diffgram che contiene la versione corrente delle righe.Process the first section of the Diffgram that contains the current version of the rows.

  2. Elaborare la seconda o le <prima di > sezione che contiene la versione originale delle righe modificate ed eliminate.Process the second or the <before> section that contains the original row version of modified and deleted rows.

    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.If a row is marked deleted, the delete operation can delete the row's descendants as well, depending on the Cascade property of the current DataSet.

  3. Processo di <errori > sezione.Process the <errors> section. Impostare le informazioni sull'errore per la riga e la colonna specificate per ogni elemento di questa sezione.Set the error information for the specified row and column for each item in this section.

Nota

Se si imposta XmlWriteMode su Diffgram, il contenuto dell'oggetto DataSet di destinazione può essere diverso da quello dell'oggetto DataSet originale.If you set the XmlWriteMode to Diffgram, the content of the target DataSet and the original DataSet may differ.

Formato DiffGramDiffGram Format

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.The DiffGram format is divided into three sections: the current data, the original (or "before") data, and an errors section, as shown in the following example.

<?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:The DiffGram format consists of the following blocks of data:

< DataInstance >< DataInstance >
Il nome di questo elemento DataInstance, viene usato a scopo esplicativo nella presente documentazione.The name of this element, DataInstance, is used for explanation purposes in this documentation. Oggetto DataInstance elemento rappresenta un DataSet o una riga di un DataTable.A DataInstance element represents a DataSet or a row of a DataTable. Invece di DataInstance, l'elemento contiene il nome delle DataSet o DataTable.Instead of DataInstance, the element would contain the name of the DataSet or DataTable. In questo blocco del formato DiffGram sono contenuti i dati correnti, indipendentemente dalle eventuali modifiche a tali dati.This block of the DiffGram format contains the current data, whether it has been modified or not. Un elemento o una riga, che è stato modificato viene identificato con il diffgr: HasChanges annotazione.An element, or row, that has been modified is identified with the diffgr:hasChanges annotation.

<diffgr:before><diffgr:before>
In questo blocco del formato DiffGram è contenuta la versione originale di una riga.This block of the DiffGram format contains the original version of a row. Gli elementi in questo blocco corrispondono agli elementi nel DataInstance bloccato tramite il diffgr: ID annotazione.Elements in this block are matched to elements in the DataInstance block using the diffgr:id annotation.

<diffgr:errors><diffgr:errors>
Questo blocco del formato DiffGram contiene informazioni sull'errore per una determinata riga nella DataInstance blocco.This block of the DiffGram format contains error information for a particular row in the DataInstance block. Gli elementi in questo blocco corrispondono agli elementi nel DataInstance bloccato tramite il diffgr: ID annotazione.Elements in this block are matched to elements in the DataInstance block using the diffgr:id annotation.

Annotazioni DiffGramDiffGram Annotations

I DiffGram usano 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.DiffGrams use several annotations to relate elements from the different DiffGram blocks that represent different row versions or error information in the DataSet.

Nella tabella seguente vengono descritte le annotazioni DiffGram definite nello spazio dei nomi DiffGram urn: schemas-microsoft-com: xml-diffgram-v1.The following table describes the DiffGram annotations that are defined in the DiffGram namespace urn:schemas-microsoft-com:xml-diffgram-v1.

AnnotazioneAnnotation DescrizioneDescription
IDid Consente di accoppiare gli elementi nel <diffgr: prima > e <diffgr: Errors > blocchi agli elementi nel < DataInstance > blocco.Used to pair the elements in the <diffgr:before> and <diffgr:errors> blocks to elements in the < DataInstance > block. I valori con il diffgr: ID annotazione sono nel formato [NomeTabella] [IdentificatoreRiga] .Values with the diffgr:id annotation are in the form [TableName][RowIdentifier]. Ad esempio: <Customers diffgr:id="Customers1">.For example: <Customers diffgr:id="Customers1">.
parentIdparentId Identifica quale elemento dal < DataInstance > blocco è l'elemento padre dell'elemento corrente.Identifies which element from the < DataInstance > block is the parent element of the current element. I valori con il diffgr: parentId annotazione sono nel formato [NomeTabella] [IdentificatoreRiga] .Values with the diffgr:parentId annotation are in the form [TableName][RowIdentifier]. Ad esempio: <Orders diffgr:parentId="Customers1">.For example: <Orders diffgr:parentId="Customers1">.
hasChangeshasChanges Identifica una riga nel < DataInstance > bloccare come modificata.Identifies a row in the < DataInstance > block as modified. Il hasChanges annotazione può avere uno dei due valori seguenti:The hasChanges annotation can have one of the following two values:

insertedinserted
Identifica un Added riga.Identifies an Added row.

modifiedmodified
Identifica un Modified riga che contiene un' originale versione di riga nel <diffgr: prima > blocco.Identifies a Modified row that contains an Original row version in the <diffgr:before> block. Si noti che Deleted righe avranno un originale versione di riga nel <diffgr: prima > blocco, ma non è presente alcun elemento annotato nel < DataInstance > blocco.Note that Deleted rows will have an Original row version in the <diffgr:before> block, but there will be no annotated element in the < DataInstance > block.
hasErrorshasErrors Identifica una riga nel < DataInstance > blocco con un RowError.Identifies a row in the < DataInstance > block with a RowError. L'elemento di errore viene inserito nel <diffgr: Errors > blocco.The error element is placed in the <diffgr:errors> block.
ErroreeError Contiene il testo del RowError per un particolare elemento le <diffgr: Errors > blocco.Contains the text of the RowError for a particular element in the <diffgr:errors> block.

Quando legge o scrive il proprio contenuto come DiffGram, il tipo DataSet include ulteriori annotazioni.The DataSet includes additional annotations when reading or writing its contents as a DiffGram. La tabella seguente descrive tali annotazioni, che sono definiti nello spazio dei nomi urn: schemas-microsoft-com: xml-msdata.The following table describes these additional annotations, which are defined in the namespace urn:schemas-microsoft-com:xml-msdata.

AnnotazioneAnnotation DescrizioneDescription
RowOrderRowOrder Conserva l'ordine di riga dei dati originali e identifica l'indice di una riga in un particolare tipo DataTable.Preserves the row order of the original data and identifies the index of a row in a particular DataTable.
HiddenHidden Identifica una colonna con un ColumnMapping impostata su MappingType.Identifies a column as having a ColumnMapping property set to MappingType.Hidden. L'attributo viene scritto nel formato msdata: hidden [NomeColonna] = "valore".The attribute is written in the format msdata:hidden [ColumnName]="value". Ad esempio: <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">.For example: <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.Note that hidden columns are only written as a DiffGram attribute if they contain data. In caso contrario, vengono ignorate.Otherwise, they are ignored.

Esempio di DiffGramSample DiffGram

Di seguito viene riportato un esempio di formato DiffGram.An example of the DiffGram format is shown below. Questo esempio mostra il risultato di un aggiornamento a una riga prima della conferma delle modifiche.This example shows the result of an update to a row in a table before the changes have been committed. La riga con CustomerID pari a "ALFKI" è stata modificata, ma non aggiornata.The row with a CustomerID of "ALFKI" has been modified, but not updated. Di conseguenza, è presente una correnti riga con un diffgr: ID pari a "Customers1" nel < DataInstance > blocco e un originale riga con un diffgr: ID pari a "Customers1" nel <diffgr: prima > blocco.As a result, there is a Current row with a diffgr:id of "Customers1" in the < DataInstance > block, and an Original row with a diffgr:id of "Customers1" in the <diffgr:before> block. La riga con CustomerID "ANATR" include un RowError, quindi è annotata con diffgr:hasErrors="true" e si trova un elemento correlato nel <diffgr: Errors > blocco.The row with a CustomerID of "ANATR" includes a RowError, so it is annotated with diffgr:hasErrors="true" and there is a related element in the <diffgr:errors> block.

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