Compartilhar via

DiffGrams

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 é escrito como um DiffGram, ele preenche o DiffGram com todas as informações necessárias para recriar com precisão o conteúdo da DataSet, embora não o esquema, incluindo valores das colunas das versões de linha Original e Current, informações de erro de linha e 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 XML usando o ReadXml método ou ao escrever o conteúdo de um DataSet em XML usando o WriteXml método, você pode especificar que o conteúdo seja lido ou gravado como um 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 escrevendo o conteúdo de todas as tabelas em um <diffgram> elemento.

Para gerar um Diffgram

  1. Gere uma lista de tabelas Raiz (ou seja, tabelas sem pai).

  2. Para cada tabela e seus descendentes na lista, anote a versão atual de todas as linhas na primeira seção do Diffgram.

  3. Para cada tabela na DataSet, escreva a versão original de todas as linhas, se houver, na seção <before> do Diffgram.

  4. Para linhas que têm erros, escreva o conteúdo do erro na <errors> seção do Diffgram.

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

Para processar um Diffgram

  1. Processe a primeira seção do Diffgram que contém a versão atual das linhas.

  2. Processe a segunda ou a <before> seção que contém a versão original das linhas antes de serem modificadas ou 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.

  3. Processe a <errors> seção. 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 explicativos 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> Este 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> Este 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.

Anotação Descrição
id Usado para emparelhar os elementos no bloco <diffgr:before> e bloco <diffgr:errors> a 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 hasChanges anotação pode ter um dos dois valores a seguir:

inserida
Identifica uma Added linha.

modificado
Identifica uma Modified linha que contém uma versão de Original linha num bloco <diffgr:before>. Observe que Deleted as linhas terão uma Original versão de linha no <diffgr:before> bloco, mas não haverá nenhum elemento anotado no <DataInstance> bloco.
hasErrors Identifica uma linha no bloco <DataInstance> com um RowError. O elemento de erro é colocado no <diffgr:errors> bloco.
Error Contém o texto do RowError para 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.

Anotação 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 uma coluna como tendo uma ColumnMapping propriedade 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, há uma Current linha com um diffgr:id de "Customers1" no < bloco DataInstance> e uma Original linha com um diffgr:id de "Customers1" no <diffgr:before> bloco. A linha com um CustomerID "ANATR" inclui um RowError, portanto, ela é 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>

Confira também

  • Last updated on