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 é 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
Cascadedo 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. |
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>