SPList.GetChanges Method (SPChangeQuery)
Gets the changes to the list from the change log as filtered by the specified query.
Namespace: Microsoft.SharePoint
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online
Syntax
'Declaration
<ClientCallableExceptionConstraintAttribute(FixedId := "a", ErrorType := GetType(SPException), _
Condition := "Change token has incorrect scope or scopeid.", _
ErrorCode := )> _
<ClientCallableExceptionConstraintAttribute(FixedId := "b", ErrorType := GetType(SPException), _
Condition := "Unable to validate change token. No rows returned from DB.", _
ErrorCode := )> _
<ClientCallableAttribute> _
Public Function GetChanges ( _
query As SPChangeQuery _
) As SPChangeCollection
'Usage
Dim instance As SPList
Dim query As SPChangeQuery
Dim returnValue As SPChangeCollection
returnValue = instance.GetChanges(query)
[ClientCallableExceptionConstraintAttribute(FixedId = "a", ErrorType = typeof(SPException),
Condition = "Change token has incorrect scope or scopeid.",
ErrorCode = )]
[ClientCallableExceptionConstraintAttribute(FixedId = "b", ErrorType = typeof(SPException),
Condition = "Unable to validate change token. No rows returned from DB.",
ErrorCode = )]
[ClientCallableAttribute]
public SPChangeCollection GetChanges(
SPChangeQuery query
)
Parameters
query
Type: Microsoft.SharePoint.SPChangeQueryThe query.
Return Value
Type: Microsoft.SharePoint.SPChangeCollection
The changes recorded for the list, filtered by the specified query. The number of changes that can be returned in a single collection is limited for performance reasons. You can adjust the maximum size of the collection by setting the FetchLimit property.
Remarks
Use this method to filter changes when you are interested only in changes to particular objects, rather than all objects, or only in selected actions on particular objects. For more information about queries, see the SPChangeQuery class.
Note
By default, the change log retains data for 60 days. You can configure the retention period by setting the ChangeLogRetentionPeriod property.
Examples
The following example is a simple console application that queries the change log for items added, updated, or deleted from a specified list. After retrieving the changes, the application examines each change and prints the date of the change, type of change, and the name of the item that has changed to the console.
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.OpenWeb())
{
// Get a list.
SPList list = webSite.Lists[0];
// Construct a query.
SPChangeQuery query = new SPChangeQuery(false, // limit object types
false); // limit change types
// Specify the object type.
query.Item = true;
// Specify change types.
query.Add = true;
query.Delete = true;
query.Update = true;
SPTimeZone timeZone = webSite.RegionalSettings.TimeZone;
int total = 0;
// Loop until we reach the end of the log.
while (true)
{
SPChangeCollection changes = list.GetChanges(query);
total += changes.Count;
// Print info about each change to the console.
foreach (SPChangeItem change in changes)
{
// Get the item name.
string itemName = String.Empty;
SPListItem item = null;
try
{
item = list.GetItemByUniqueId(change.UniqueId);
itemName = item.Name;
}
catch (ArgumentException)
{
itemName = "Unknown";
}
Console.WriteLine("\nDate: {0}",
timeZone.UTCToLocalTime(change.Time).ToString());
Console.WriteLine("Change: {0}", change.ChangeType);
Console.WriteLine("Item: {0}", itemName);
}
// Break out of loop if we have the last batch.
if (changes.Count < query.FetchLimit)
break;
// Otherwise, go get another batch.
query.ChangeTokenStart = changes.LastChangeToken;
}
Console.WriteLine("\nTotal of {0} changes to {1} list", total, list.Title);
}
}
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.OpenWeb()
' Get a list.
Dim list As SPList = webSite.Lists(0)
' Construct a query
Dim query As New SPChangeQuery(False, False)
' Specify the object type.
query.Item = True
' Specify change types.
query.Add = True
query.Delete = True
query.Update = True
Dim timeZone As SPTimeZone = webSite.RegionalSettings.TimeZone
Dim total As Integer = 0
' Loop until we reach the end of the log.
While True
Dim changes As SPChangeCollection = list.GetChanges(query)
total += changes.Count
' Print info about each change to the console.
For Each change As SPChangeItem In changes
' Get the item name.
Dim itemName As String = String.Empty
Dim item As SPListItem = Nothing
Try
item = list.GetItemByUniqueId(change.UniqueId)
itemName = item.Name
Catch ex As ArgumentException
itemName = "Unknown"
End Try
Console.WriteLine(vbCrLf + "Date: {0}", timeZone.UTCToLocalTime(change.Time).ToString())
Console.WriteLine("Change: {0}", change.ChangeType)
Console.WriteLine("Item: {0}", itemName)
Next change
' Break out of the loop when we fetch the last batch of changes.
If changes.Count < query.FetchLimit Then
Exit While
End If
' Go get another batch of changes starting where we left off.
query.ChangeTokenStart = changes.LastChangeToken
End While
Console.WriteLine(vbCrLf + "Total of {0:#,#} changes to {1} list", total, list.Title)
End Using
End Using
Console.Write(vbCrLf + "Press ENTER to continue...")
Console.ReadLine()
End Sub
End Module
See Also
Reference
Microsoft.SharePoint Namespace