This documentation is archived and is not being maintained.

SPChangeToken Class

Windows SharePoint Services 3

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

System.Object
  Microsoft.SharePoint.SPChangeToken

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

[SerializableAttribute]
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
public sealed class SPChangeToken

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.
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;
}

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.

NoteNote

By default, the change log retains data for 15 days. You can configure this interval in Windows SharePoint Services by using the Web Application General Settings page, which is located on the Central Administration site.

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();
      }
   }
}

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