SPChangeToken class

Represents the unique sequential location of a change within the change log.

Inheritance hierarchy

System.Object
  Microsoft.SharePoint.SPChangeToken

Namespace:  Microsoft.SharePoint
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)

Syntax

'Declaration
<SerializableAttribute> _
Public NotInheritable Class SPChangeToken
'Usage
Dim instance As SPChangeToken

[SerializableAttribute]
public sealed class SPChangeToken

Remarks

Each entry in the change log is represented by an SPChange object. When a change is logged, it is stamped with an identifying token, which is represented by an SPChangeToken object of the ChangeToken property of the SPChange object.

You can get the change token that will be used to mark the next change that is logged for the list, site, site collection, or content database that you are programming against by accessing the CurrentChangeToken property of the SPList, SPWeb, SPSite, or SPContentDatabase class.

More often, you will want to use a change token to limit the scope of a query against the change log. For example, you can retrieve changes starting from a particular point in the change log by passing an SPChangeToken object as an argument to the GetChanges method of the SPList, SPWeb, SPSite, or SPContentDatabase class. The change token that you pass represents the sequential location in the log where you want your query to begin.

You can also call the GetChanges method with two change tokens as arguments, indicating both a starting and an ending point for your query. Similarly, you can specify start and end points by calling another overload of GetChanges, this one accepting an instance of the SPChangeQuery class. This class has properties that you can use to refine a query, including two properties that hold SPChangeToken objects, the ChangeTokenStart property and the ChangeTokenEnd property.

All overloads of the GetChanges method return an SPChangeCollection object. The number of changes that are returned in a single collection is limited for performance reasons, so you should call GetChanges in a loop until you get an empty collection, signifying either that you have reached the end of the log or that there are no more changes that satisfy your query. When you do this, use the token that is returned by the LastChangeToken property of the first batch to get the second batch, and so on until you get a batch with zero changes. The general approach is illustrated by the following code, which retrieves all changes logged for a site collection.

// Get the first batch of changes.
SPChangeToken token = null;
SPChangeCollection changes = siteCollection.GetChanges(token);

while (changes.Count > 0)
{
   foreach (SPChange change in changes)
   {
      // Process each change.
   }

   // Go get another batch.
   token = changes.LastChangeToken;
   changes = siteCollection.GetChanges(token);
}

' Get the first batch of changes.
Dim token As SPChangeToken = Nothing
Dim changes As SPChangeCollection = siteCollection.GetChanges(token)

While changes.Count > 0
   Dim change As SPChange
   For Each change in changes
      ' Process the change.
   Next change

   ' Go get another batch.
   token = changes.LastChangeToken
   changes = siteCollection.GetChanges(token)
End While

Examples

The following example is a console application that uses the SPChangeToken class to return changes that have occurred on a Web site during the past 60 days.

using System;
using Microsoft.SharePoint;

namespace Test
{
   class ConsoleApp
   {
      static void Main(string[] args)
      {
         using (SPSite siteCollection = new SPSite("https://localhost"))
         {
            using (SPWeb webSite = siteCollection.RootWeb)
            {
               // Display change times as local time.
               SPTimeZone timeZone = webSite.RegionalSettings.TimeZone;

               // Create a change token.
               DateTime startTime = DateTime.UtcNow.AddDays(-60);
               SPChangeToken startToken = new SPChangeToken(SPChangeCollection.CollectionScope.Web,
                                                            webSite.ID,
                                                            startTime);

               // Retrieve the first batch of changes.
               SPChangeCollection changes = webSite.GetChanges(startToken);

               while (changes.Count > 0)
               {
                  foreach (SPChange change in changes)
                  {
                     // Process the change.
                     Console.WriteLine("\nDate: {0}", timeZone.UTCToLocalTime(change.Time).ToString());
                     Console.WriteLine("Change subclass: {0}", change.GetType().ToString());
                     Console.WriteLine("Type of change: {0}", change.ChangeType.ToString());
                  }

                  // Get another batch.
                  startToken = changes.LastChangeToken;
                  changes = webSite.GetChanges(startToken);
               }
            }
         }
         Console.Write("\nPress ENTER to continue...");
         Console.ReadLine();
      }
   }
}

Imports System
Imports Microsoft.SharePoint

Module ConsoleApp
   Sub Main()
      Using siteCollection As SPSite = New SPSite("https://localhost")
         Using webSite As SPWeb = siteCollection.RootWeb

            ' Display change times as local time.
            Dim timeZone As SPTimeZone = webSite.RegionalSettings.TimeZone

            ' Create a change token.
            Dim startTime As DateTime = DateTime.UtcNow.AddDays(-60)
            Dim startToken As SPChangeToken = New SPChangeToken(SPChangeCollection.CollectionScope.Web, _
                                                                webSite.ID, _
                                                                startTime)

            ' Retrieve the first batch of changes.
            Dim changes As SPChangeCollection = webSite.GetChanges(startToken)

            While changes.Count > 0
               Dim change As SPChange
               For Each change In changes
                  ' Process the change.
                  Console.WriteLine(vbCrLf + "Date: {0}", timeZone.UTCToLocalTime(change.Time).ToString())
                  Console.WriteLine("Change subclass: {0}", change.GetType().ToString())
                  Console.WriteLine("Type of change: {0}", change.ChangeType.ToString())
               Next

               ' Get another batch.
               startToken = changes.LastChangeToken
               changes = webSite.GetChanges(startToken)
            End While

         End Using
      End Using
      Console.Write(vbCrLf + "Press ENTER to continue...")
      Console.ReadLine()
   End Sub
End Module

Thread safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See also

Reference

SPChangeToken members

Microsoft.SharePoint namespace

Other resources

Using the Change Log