DiffGrams

Artigo
03/05/2024

Um DiffGram é um formato XML que identifica versões atuais e originais de elementos de dados. O DataSet usa o formato DiffGram para carregar e persistir seu conteúdo e serializar seu conteúdo para transporte através de uma conexão de rede. Quando um DataSet é escrito como um DiffGram, ele preenche o DiffGram com todas as informações necessárias para recriar com precisão o conteúdo, embora não o esquema, do DataSet, incluindo valores de coluna das versões de linha Original e Atual, informações de erro de linha e ordem de linha.

Ao enviar e recuperar um DataSet de um XML Web Service, o formato DiffGram é usado implicitamente. Além disso, ao carregar o conteúdo de um DataSet de XML usando o método ReadXml , ou ao escrever o conteúdo de um DataSet em XML usando o método WriteXml , você pode especificar que o conteúdo seja lido ou escrito como um DiffGram. Para obter mais informações, consulte Carregando um DataSet de XML e Gravando Conteúdo de DataSet como Dados XML.

Embora o formato DiffGram seja usado principalmente pelo .NET Framework como um formato de serialização para o conteúdo de um DataSet, você também pode usar DiffGrams para modificar dados em tabelas em um banco de dados do Microsoft SQL Server.

Um Diffgram é gerado gravando o conteúdo de todas as tabelas em um <elemento diffgram> .

Para gerar um Diffgram

Gere uma lista de tabelas raiz (ou seja, tabelas sem nenhum pai).
Para cada tabela e seus descendentes na lista, escreva a versão atual de todas as linhas na primeira seção Diffgram.
Para cada tabela no DataSet, escreva a versão original de todas as linhas, se houver, na <seção anterior> do Diffgram.
Para linhas com erros, escreva o <conteúdo do erro na seção de erros> do Diffgram.

Um Diffgram é processado em ordem desde o início do arquivo XML até o final.

Para processar um Diffgram

Processe a primeira seção do Diffgram que contém a versão atual das linhas.
Processe a segunda seção ou a <seção anterior> que contém a versão original da linha de linhas modificadas e excluídas.

Nota

Se uma linha for marcada como excluída, a operação de exclusão também poderá excluir os descendentes da linha, dependendo da Cascade propriedade do atual DataSet.
Processe a seção de <erros> . Defina as informações de erro para a linha e coluna especificadas para cada item nesta seção.

Nota

Se você definir o XmlWriteMode como Diffgram, o conteúdo do destino DataSet e o original DataSet podem ser diferentes.

Formato DiffGram

O formato DiffGram é dividido em três seções: os dados atuais, os dados originais (ou "antes") e uma seção de erros, conforme mostrado no exemplo a seguir.

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

O formato DiffGram consiste nos seguintes blocos de dados:

<DataInstance>
O nome desse elemento, DataInstance, é usado para fins de explicação nesta documentação. Um elemento DataInstance representa uma DataSet ou uma linha de um DataTablearquivo . Em vez de DataInstance, o elemento conteria o nome do DataSet ou DataTable. Este bloco do formato DiffGram contém os dados atuais, quer tenham sido modificados ou não. Um elemento, ou linha, que foi modificado é identificado com a anotação diffgr:hasChanges .

<diffgr:antes>
Este bloco do formato DiffGram contém a versão original de uma linha. Os elementos neste bloco são correspondidos aos elementos no bloco DataInstance usando a anotação diffgr:id .

<diffgr:erros>
Este bloco do formato DiffGram contém informações de erro para uma linha específica no bloco DataInstance . Os elementos neste bloco são correspondidos aos elementos no bloco DataInstance usando a anotação diffgr:id .

Anotações DiffGram

Os DiffGrams usam várias anotações para relacionar elementos dos diferentes blocos DiffGram que representam diferentes versões de linha ou informações de erro no DataSet.

A tabela a seguir descreve as anotações DiffGram definidas no namespace DiffGram urn:schemas-microsoft-com:xml-diffgram-v1.

Anotação	Description
id	Usado para emparelhar os elementos nos blocos diffgr:before> e <diffgr:errors> com elementos no <bloco DataInstance>.< Os valores com a anotação diffgr:id estão na forma `[TableName][RowIdentifier]`. Por exemplo: `<Customers diffgr:id="Customers1">`.
parentId	Identifica qual elemento do <bloco DataInstance> é o elemento pai do elemento atual. Os valores com a anotação diffgr:parentId estão na forma `[TableName][RowIdentifier]`. Por exemplo: `<Orders diffgr:parentId="Customers1">`.
hasAlterações	Identifica uma linha no <bloco DataInstance> como modificada. A anotação hasChanges pode ter um dos dois valores a seguir: inserido Identifica uma linha Adicionada . modificado Identifica uma linha Modified que contém uma versão da linha Original no <bloco diffgr:before> . Observe que as< linhas excluídas terão uma versão de linha Original no bloco diffgr:before>, mas não haverá nenhum elemento anotado< no bloco DataInstance>.
hasErrors	Identifica uma linha no <*bloco DataInstance>* com um RowError. O elemento error é colocado no <bloco diffgr:errors> .
Erro	Contém o texto do RowError para um elemento específico no <bloco diffgr:errors> .

O DataSet inclui anotações adicionais ao ler ou escrever seu conteúdo como um DiffGram. A tabela a seguir descreve essas anotações adicionais, que são definidas no namespace urn:schemas-microsoft-com:xml-msdata.

Anotação	Description
Ordem de linha	Preserva a ordem das linhas dos dados originais e identifica o índice de uma linha em um determinado DataTable.
Escondido	Identifica uma coluna como tendo uma propriedade ColumnMapping definida como MappingType.Hidden. O atributo é escrito no formato msdata:hidden[ColumnName]="value". Por exemplo: `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">`. Observe que as colunas ocultas só são gravadas como um atributo DiffGram se contiverem dados. Caso contrário, são ignorados.

Exemplo de DiffGram

Um exemplo do formato DiffGram é mostrado abaixo. Este exemplo mostra o resultado de uma atualização de uma linha em uma tabela antes que as alterações tenham sido confirmadas. A linha com um CustomerID de "ALFKI" foi modificada, mas não atualizada. Como resultado, há uma linha Current com um diffgr:id de "Customers1" no <bloco DataInstance> e uma linha Original com um diffgr:id de "Customers1" no< bloco diffgr:before.> A linha com um CustomerID de "ANATR" inclui um RowError, por isso é anotada com diffgr:hasErrors="true" e há um elemento relacionado no< bloco 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>

Partilhar via