Elementy DiffGram

Artykuł
03/05/2024

DiffGram to format XML, który identyfikuje bieżące i oryginalne wersje elementów danych. Używa DataSet formatu DiffGram do ładowania i utrwalania jego zawartości oraz serializacji jego zawartości do transportu przez połączenie sieciowe. Gdy obiekt DataSet jest zapisywany jako DiffGram, wypełnia diffGram wszystkimi niezbędnymi informacjami, aby dokładnie odtworzyć zawartość, choć nie schemat, DataSetz wartościami kolumn zarówno z wersji oryginalnych , jak i bieżących wierszy, informacji o błędach wiersza i kolejności wierszy.

Podczas wysyłania i pobierania elementu DataSet z usługi sieci Web XML format DiffGram jest używany niejawnie. Ponadto podczas ładowania zawartości DataSet elementu z pliku XML przy użyciu metody ReadXml lub podczas zapisywania zawartości elementu w formacie XML przy użyciu metody WriteXml można określić, że zawartość DataSet będzie odczytywana lub zapisywana jako DiffGram. Aby uzyskać więcej informacji, zobacz Ładowanie zestawu danych z formatu XML i zapisywanie zawartości zestawu danych jako danych XML.

Chociaż format DiffGram jest używany głównie przez program .NET Framework jako format serializacji zawartości DataSetelementu , można również użyć diffGrams do modyfikowania danych w tabelach w bazie danych programu Microsoft SQL Server.

Diffgram jest generowany przez zapisanie zawartości wszystkich tabel do elementu diffgram>.<

Aby wygenerować diffgram

Wygeneruj listę tabel głównych (czyli tabele bez żadnego elementu nadrzędnego).
Dla każdej tabeli i jej elementów podrzędnych na liście zapisz bieżącą wersję wszystkich wierszy w pierwszej sekcji Diffgram.
Dla każdej tabeli w DataSetpliku zapisz oryginalną wersję wszystkich wierszy, jeśli istnieje, w <sekcji przed> diffgramu.
W przypadku wierszy, które mają błędy, zapisz zawartość błędu w <sekcji błędów> diffgramu.

Diffgram jest przetwarzany w kolejności od początku pliku XML do końca.

Aby przetworzyć diffgram

Przetwórz pierwszą sekcję diffgramu, która zawiera bieżącą wersję wierszy.
Przetwórz drugą lub poprzednią <> sekcję zawierającą oryginalną wersję wiersza zmodyfikowanych i usuniętych wierszy.

Uwaga

Jeśli wiersz zostanie oznaczony jako usunięty, operacja usuwania może również usunąć elementy podrzędne wiersza, w zależności od Cascade właściwości bieżącej DataSet.
Przetwórz sekcję <błędów> . Ustaw informacje o błędzie dla określonego wiersza i kolumny dla każdego elementu w tej sekcji.

Uwaga

Jeśli ustawisz XmlWriteMode wartość Diffgram, zawartość obiektu docelowego DataSet i oryginalna DataSet może się różnić.

DiffGram Format

Format DiffGram jest podzielony na trzy sekcje: bieżące dane, oryginalne dane (lub "przed") oraz sekcję błędów, jak pokazano w poniższym przykładzie.

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

Format DiffGram składa się z następujących bloków danych:

< DataInstance >
Nazwa tego elementu, DataInstance, jest używana do celów objaśnienia w tej dokumentacji. Element DataInstance reprezentuje DataSet wiersz DataTablelub . Zamiast klasy DataInstance element będzie zawierać nazwę DataSet elementu lub DataTable. Ten blok formatu DiffGram zawiera bieżące dane, niezależnie od tego, czy został zmodyfikowany, czy nie. Element lub wiersz, który został zmodyfikowany, jest identyfikowany z adnotacją diffgr:hasChanges .

<diffgr:before>
Ten blok formatu DiffGram zawiera oryginalną wersję wiersza. Elementy w tym bloku są dopasowywane do elementów w bloku DataInstance przy użyciu adnotacji diffgr:id .

<diffgr:errors>
Ten blok formatu DiffGram zawiera informacje o błędzie dla określonego wiersza w bloku DataInstance. Elementy w tym bloku są dopasowywane do elementów w bloku DataInstance przy użyciu adnotacji diffgr:id .

Adnotacje diffGram

DiffGramy używają kilku adnotacji do powiązania elementów z różnych bloków DiffGram, które reprezentują różne wersje wierszy lub informacje o błędzie w obiekcie DataSet.

W poniższej tabeli opisano adnotacje DiffGram zdefiniowane w przestrzeni nazw DiffGram urn:schemas-microsoft-com:xml-diffgram-v1.

Adnotacja	opis
id	Służy do parowania elementów w diffgr:before> i <diffgr:errors> bloków do elementów w < bloku DataInstance>.< Wartości z adnotacją diffgr:id są w postaci `[TableName][RowIdentifier]`. Na przykład: `<Customers diffgr:id="Customers1">`.
parentId	Określa, który element z < bloku DataInstance > jest elementem nadrzędnym bieżącego elementu. Wartości z adnotacją diffgr:parentId są w postaci `[TableName][RowIdentifier]`. Na przykład: `<Orders diffgr:parentId="Customers1">`.
hasChanges	Identyfikuje wiersz w bloku DataInstance> zgodnie z < modyfikacją. Adnotacja hasChanges może mieć jedną z następujących dwóch wartości: Wstawiony Identyfikuje dodany wiersz. Zmodyfikowano Identyfikuje zmodyfikowany wiersz, który zawiera wersję oryginalnego wiersza w< diffgr:before> block. Należy pamiętać, że usunięte wiersze będą miały oryginalną wersję wiersza w< diffgr:before> block, ale w bloku DataInstance> nie będzie żadnych adnotacji.<
hasErrors	Identyfikuje wiersz w < bloku DataInstance> za pomocą polecenia RowError. Element error znajduje się w <bloku diffgr:errors> .
Błąd	Zawiera tekst elementu RowError dla określonego< elementu w bloku diffgr:errors>.

Zawiera DataSet dodatkowe adnotacje podczas odczytywania lub zapisywania jego zawartości jako DiffGram. W poniższej tabeli opisano te dodatkowe adnotacje zdefiniowane w przestrzeni nazw urn:schemas-microsoft-com:xml-msdata.

Adnotacja opis

Kolejność wierszy Zachowuje kolejność wierszy oryginalnych danych i identyfikuje indeks wiersza w określonym DataTableobiekcie .

Ukryty Identyfikuje kolumnę jako właściwość ColumnMapping ustawioną na MappingType.Hidden. Atrybut jest zapisywany w formacie msdata:hidden [ColumnName]="value". Na przykład: <Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">.

Należy pamiętać, że ukryte kolumny są zapisywane tylko jako atrybut DiffGram, jeśli zawierają dane. W przeciwnym razie są one ignorowane.

Adnotacja	opis
Kolejność wierszy	Zachowuje kolejność wierszy oryginalnych danych i identyfikuje indeks wiersza w określonym DataTableobiekcie .
Ukryty	Identyfikuje kolumnę jako właściwość ColumnMapping ustawioną na MappingType.Hidden. Atrybut jest zapisywany w formacie msdata:hidden [ColumnName]="value". Na przykład: `<Customers diffgr:id="Customers1" msdata:hiddenContactTitle="Owner">`. Należy pamiętać, że ukryte kolumny są zapisywane tylko jako atrybut DiffGram, jeśli zawierają dane. W przeciwnym razie są one ignorowane.

Przykładowy diffGram

Poniżej przedstawiono przykład formatu DiffGram. W tym przykładzie pokazano wynik aktualizacji wiersza w tabeli przed zatwierdzeniu zmian. Wiersz o identyfikatorze CustomerID "ALFKI" został zmodyfikowany, ale nie został zaktualizowany. W związku z tym w bloku DataInstance > znajduje się bieżący wiersz o identyfikatorze diffgr:id "Customers1"< i oryginalny wiersz o identyfikatorze "Customers1" w <bloku diffgr:before.> Wiersz z identyfikatorem CustomerID wartości "ANATR" zawiera błąd RowError, dlatego jest oznaczony adnotacją diffgr:hasErrors="true" i istnieje powiązany element w< bloku 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>

Udostępnij za pośrednictwem