How to: Save and Restore a Change Token

Applies to: SharePoint Foundation 2010

If your application queries the change log on a regular schedule, you might want to persist the last change token at the end of a run, and later reconstruct the persisted token to use as a starting point for the next run. To save a change token, first call the SPChangeToken.ToString() method to get a string representation of the token; then persist the result to permanent storage. To restore the token, retrieve the string from storage and pass it to the SPChangeToken.SPChangeToken(String) constructor.

Example

The following example is a console application that queries the change log for changes that have content database scope.

The first time the application runs, the query retrieves all changes recorded from the beginning of the log to its current end. This query is performed by first setting the ChangeTokenStart property of an SPChangeQuery object to a null value, and then passing the SPQuery object to the GetChanges method. After all changes have been processed, the program serializes the last change token from the last batch of changes by calling the ToString() method and stores the result in a file on disk.

On subsequent runs, the program deserializes the stored change token and uses it to set the ChangeTokenStart property, which defines the starting point for its query against the change log. The ChangeTokenEnd property is left at its default null value, which signals that the query should proceed to the end of the log.

The important work is done in the GetStartingToken function, which is where the SPChangeToken constructor is called.

using System;
using System.IO;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace Test
{
   class ConsoleApp
   {
      private const string DATA_FILE_PATH = "ChangeToken.dat";

      static void Main(string[] args)
      {
         using (SPSite site = new SPSite("https://localhost"))
         {
            SPChangeQuery query = new SPChangeQuery(true, true);
            query.ChangeTokenStart = GetStartingToken();

            while (true)
            {
               // Get a batch of changes.
               SPChangeCollection changes = site.ContentDatabase.GetChanges(query);

               // Process them.
               foreach (SPChange change in changes)
               {
                  Console.WriteLine("Date: {0}  Type of object: {1}  Type of change: {2}",
                     change.Time.ToShortDateString(), change.GetType().ToString(), change.ChangeType);
               }

               // Starting point for next batch.
               query.ChangeTokenStart = changes.LastChangeToken;

               // If this is the last batch, exit.
               if (changes.Count < query.FetchLimit)
                  break;
            }
            // Serialize the last token as a starting point for the next run.
            SaveLastToken(query.ChangeTokenStart);
         }

         Console.Write("\nPress ENTER to continue...");
         Console.ReadLine();
      }

      static SPChangeToken GetStartingToken()
      {
         // Passing a null token to GetChanges fetches 
         // changes from the start of the log.
         SPChangeToken token = null;

         // If we have a token from the last run, use it.
         if (File.Exists(DATA_FILE_PATH))
         {
            using (FileStream fs = File.OpenRead(DATA_FILE_PATH))
            {
               BinaryReader br = new BinaryReader(fs);
               try
               {
                  string str = br.ReadString();
                  // Construct a change token from serialized string.
                  token = new SPChangeToken(str);
               }
               catch (EndOfStreamException e)
               {
                  // No serialized string, so do nothing.
               }
               finally
               {
                  br.Close();
               }
            }
         }
         return token;
      }

      static void SaveLastToken(SPChangeToken token)
      {
         using (FileStream fs = File.Create(DATA_FILE_PATH))
         {
            // Serialize the token.
            BinaryWriter bw = new BinaryWriter(fs);
            string s = token.ToString();
            bw.Write(s);

            // Flush and close.
            bw.Flush();
            bw.Close();
         }
      }
   }
}

Imports System
Imports System.IO
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Administration

Module ConsoleApp

   Private Const DATA_FILE_PATH As String = "ChangeToken.dat"

   Sub Main()
      Using site As SPSite = New SPSite("https://localhost")

         Dim query As New SPChangeQuery(True, True)
         query.ChangeTokenStart = GetStartingToken()

         While (True)
            ' Get a batch of changes.
            Dim changes As SPChangeCollection = site.ContentDatabase.GetChanges(query)

            ' Process them.
            For Each change As SPChange In changes
               Console.WriteLine("Date: {0}  Type of object: {1}  Type of change: {2}", _
                     change.Time.ToShortDateString(), change.GetType().ToString(), change.ChangeType)
            Next

            ' This is the starting point for next batch.
            query.ChangeTokenStart = changes.LastChangeToken

            ' If this is the last batch, exit.
            If changes.Count < query.FetchLimit Then
               Exit While
            End If

         End While

         ' Serialize the last token as a starting point for the next run.
         SaveLastToken(query.ChangeTokenStart)
      End Using

      Console.Write(vbCrLf + "Press ENTER to continue...")
      Console.ReadLine()

   End Sub

   Function GetStartingToken() As SPChangeToken
      ' Passing a null token to GetChanges fetches 
      ' changes from the start of the log.
      Dim token As SPChangeToken = Nothing

      ' If we have a token from the last run, use it.
      If File.Exists(DATA_FILE_PATH) Then
         Using fs As FileStream = File.OpenRead(DATA_FILE_PATH)
            Dim br As BinaryReader = New BinaryReader(fs)
            Try
               Dim str As String = br.ReadString()
               ' Construct a change token from serialized string.
               token = New SPChangeToken(str)
            Catch e As EndOfStreamException
               ' No serialized string, so do nothing.
            Finally
               br.Close()
            End Try
         End Using
      End If

      Return token
   End Function

   Sub SaveLastToken(ByRef token As SPChangeToken)
      Using fs As FileStream = File.Create(DATA_FILE_PATH)
         ' Serialize the token.
         Dim bw As BinaryWriter = New BinaryWriter(fs)
         Dim s As String = token.ToString()
         bw.Write(s)
         ' Flush and close.
         bw.Flush()
         bw.Close()
      End Using
   End Sub

End Module

See Also

Reference

SPChangeToken

SPChangeTokenCollection