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

<SerializableAttribute> _
<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel := True)> _
Public NotInheritable Class SPChangeToken

Dim instance As SPChangeToken

[SerializableAttribute]
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
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 in the SPChange object’s ChangeToken property.

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. For performance reasons, the maximum number of changes that are returned in a single collection is limited to 1000, a value that is specified by the CountLimit constant. If the scope of your query is likely to include more than 1000 changes, you can call the GetChanges method in a loop to retrieve changes in batches. 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 fewer than 1000 changes, which signifies that you have reached the end of the list. The general approach is illustrated by the following code, which retrieves all changes logged for a site collection.

' Start at the beginning of the log.
Dim token As SPChangeToken = Nothing

' Loop until we reach the end of the log.
While True

   ' Get a batch of changes.
   Dim changes As SPChangeCollection = siteCollection.GetChanges(token)

   Dim change As SPChange
   For Each change in changes
      ' Process the change.
   Next change

   ' Break out of the loop when we fetch the last batch.
   If changes.Count < SPChangeCollection.CountLimit Then
      Exit While
   End If

   ' Go get another batch of changes starting where we left off.
   token = changes.LastChangeToken

End While

// Start at the beginning of the log.
SPChangeToken token = null;

// Loop until we reach the end of the log.
while (true)
{
   // Get a batch of changes.
   SPChangeCollection changes = siteCollection.GetChanges(token);

   foreach (SPChange change in changes)
   {
      // Process the change.
   }

   // Break out of loop if we have the last batch.
   if (changes.Count < SPChangeCollection.CountLimit)
      break;

   // Go get another batch of changes starting where we left off.
   token = changes.LastChangeToken;
}

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 15 days.

Imports System
Imports Microsoft.SharePoint

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

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

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

            ' Retrieve the changes.
            Dim changes As SPChangeCollection = webSite.GetChanges(startToken)
            Dim change As SPChange
            For Each change In changes
               ' Process the change.
               Console.WriteLine(vbCrLf + "Date: {0}", timeZone.UTCToLocalTime(change.Time).ToString())
               Console.WriteLine("Type of change: {0}", change.ChangeType.ToString())
               Console.WriteLine("Subclass: {0}", change.GetType().ToString())
            Next change

         End Using
      End Using

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

   End Sub
End Module

using System;
using Microsoft.SharePoint;

namespace Test
{
   class ConsoleApp
   {
      static void Main(string[] args)
      {
         using (SPSite siteCollection = new SPSite("http://localhost"))
         {
            using (SPWeb webSite = siteCollection.OpenWeb())
            {
               // Create a change token.
               DateTime startTime = DateTime.UtcNow.AddDays(-15);
               SPChangeToken startToken = new SPChangeToken(SPChangeCollection.CollectionScope.Web, 
                                                            webSite.ID, 
                                                            startTime);

               // Display change times as local time.
               SPTimeZone timeZone = webSite.RegionalSettings.TimeZone;

               // Retrieve the changes.
               SPChangeCollection changes = webSite.GetChanges(startToken);
               foreach (SPChange change in changes)
               {
                  // Process the change.
                  Console.WriteLine("\nDate: {0}", timeZone.UTCToLocalTime(change.Time).ToString());
                  Console.WriteLine("Type of change: {0}", change.ChangeType.ToString());
                  Console.WriteLine("Subclass: {0}", change.GetType().ToString());
               }
            }
         }
         Console.Write("\nPress ENTER to continue...");
         Console.ReadLine();
      }
   }
}

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 Changes to Query for Objects