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.
Note
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.
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
Microsoft.SharePoint Namespace