DiffGrams

Artigo
07/08/2024

DiffGram é um formato XML que identifica as versões atuais e originais dos elementos de dados. O DataSet usa o formato DiffGram para carregar e persistir o conteúdo e serializar o conteúdo para transporte em uma conexão de rede. Quando um DataSet é gravado como 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 os valores de coluna das versões de linha Original e Atual, as informações de erro de linha e a ordem de linha.

Ao enviar e recuperar um DataSet de um serviço Web XML, o formato DiffGram é usado implicitamente. Além disso, ao carregar o conteúdo de um DataSet do formato XML usando o método ReadXml ou ao gravar o conteúdo de um DataSet em XML usando o método WriteXml, você pode especificar que o conteúdo seja lido ou gravado como DiffGram. Para obter mais informações, confira Como carregar um conjunto de dados em XML e Como gravar o conteúdo do conjunto de dados como dados XML.

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

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

Para gerar um Diffgram

Gere uma lista de tabelas Raiz (ou seja, tabelas sem pai).
Para cada tabela e seus descendentes na lista, anote a versão atual de todas as linhas na primeira seção do Diffgram.
Para cada tabela no DataSet, anote 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 das linhas modificadas e excluídas.

Observação

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

Observação

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

Formato DiffGram

O formato DiffGram é dividido em três seções: os dados atuais, os dados originais (ou "anteriores") 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 um DataSet ou uma linha de um DataTable. Em vez de DataInstance, o elemento conteria o nome do DataSet ou do DataTable. Esse bloco do formato DiffGram contém os dados atuais, independentemente de terem sido modificados. Um elemento (ou uma linha) modificado é identificado com a anotação diffgr:hasChanges.

<diffgr:before>
Esse bloco do formato DiffGram contém a versão original de uma linha. Os elementos neste bloco combinados com os elementos no bloco DataInstance usando a anotação diffgr:id.

<diffgr:errors>
Esse bloco do formato DiffGram contém informações de erro para uma linha específica no bloco DataInstance. Os elementos neste bloco combinados com os elementos no bloco DataInstance usando a anotação diffgr:id.

Anotações de DiffGram

Os DiffGrams usam várias anotações para relacionar os 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 do DiffGram definidas no namespace do DiffGram urn:schemas-microsoft-com:xml-diffgram-v1.

Annotation	Descrição
id	Usado para emparelhar os elementos nos blocos <diffgr:before> e <diffgr:errors> com os elementos no bloco < DataInstance >. Os valores com a anotação diffgr:id estão no formato `[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 no formato `[TableName][RowIdentifier]`. Por exemplo: `<Orders diffgr:parentId="Customers1">`.
hasChanges	Identifica uma linha no bloco < DataInstance > conforme modificado. A anotação hasChanges pode ter um dos dois valores a seguir: inserida Identifica uma linha Adicionada. modificado Identifica uma linha Modificada que contém uma versão de 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á elementos anotados no bloco < DataInstance >.
hasErrors	Identifica uma linha no bloco < DataInstance > com um RowError. O elemento de erro é colocado no bloco <diffgr:errors>.
Erro	Contém o texto do RowError de um elemento específico no bloco <diffgr:errors>.

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

Annotation Descrição

RowOrder Preserva a ordem de linha dos dados originais e identifica o índice de uma linha em um DataTable específico.

Oculto Identifica que uma coluna tem a propriedade ColumnMapping definida como MappingType.Hidden. O atributo é gravado no formato msdata:hidden [ColumnName]="value". Por exemplo: <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">.

Observe que as colunas ocultas só serão gravadas como atributo do DiffGram se contiverem dados. Caso contrário, eles serão ignorados.

Annotation	Descrição
RowOrder	Preserva a ordem de linha dos dados originais e identifica o índice de uma linha em um DataTable específico.
Oculto	Identifica que uma coluna tem a propriedade ColumnMapping definida como MappingType.Hidden. O atributo é gravado no formato msdata:hidden [ColumnName]="value". Por exemplo: `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">`. Observe que as colunas ocultas só serão gravadas como atributo do DiffGram se contiverem dados. Caso contrário, eles serão ignorados.

Exemplo de DiffGram

Veja abaixo um exemplo do formato DiffGram. Este exemplo mostra o resultado de uma atualização para uma linha em uma tabela, antes da confirmação das alterações. A linha com um CustomerID de "ALFKI" foi modificada, mas não atualizada. Como resultado, existe uma linha Atual 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. Portanto, ela foi anotada com diffgr:hasErrors="true" e existe 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>

Compartilhar via