SPChangeCollection Class
Represents a collection of objects derived from the SPChange class.
Inheritance Hierarchy
System.Object
Microsoft.SharePoint.Administration.SPAutoSerializingObject
Microsoft.SharePoint.SPBaseCollection
Microsoft.SharePoint.SPChangeCollection
Namespace: Microsoft.SharePoint
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online
Syntax
'Declaration
<SubsetCallableTypeAttribute> _
<ClientCallableTypeAttribute(Name := "ChangeCollection", ServerTypeId := "{2ba7a459-eeda-42d0-90e2-fad3487ad0d3}", _
CollectionChildItemType := GetType(SPChange))> _
Public NotInheritable Class SPChangeCollection _
Inherits SPBaseCollection
'Usage
Dim instance As SPChangeCollection
[SubsetCallableTypeAttribute]
[ClientCallableTypeAttribute(Name = "ChangeCollection", ServerTypeId = "{2ba7a459-eeda-42d0-90e2-fad3487ad0d3}",
CollectionChildItemType = typeof(SPChange))]
public sealed class SPChangeCollection : SPBaseCollection
Remarks
Use the GetChanges method of the SPList, SPWeb, SPSite, or SPContentDatabase object to return an SPChangeCollection object with the changes that have occurred within a given scope. You can then enumerate the collection and examine each of its members individually.
Each object in the SPChangeCollection that is returned by the GetChanges method is a subclass of the SPChange class. The properties of the parent SPChange class contain basic information about a change, including the type of change, as represented by the ChangeType property; the time of the change, as represented by the Time property; and the ID of the site collection where the change was made, as represented by the SiteId property. The properties of subclasses of SPChange contain information specific to the type of object that was changed. For example, the SPChangeItem class represents a change to an SPListItem object and therefore has a ListId property that identifies the list where the item was changed. Similarly, the SPChangeList class represents a change to a list and has a WebId property that identifies the Web site where the list was changed.
The total number of changes returned by a query against the change log could be very large, depending on the retention period set for the log and the scope of the query. For performance reasons, changes are returned in batches of limited size. If you want all changes rather than only the first batch, your code should call the GetChanges method in a loop until it returns a collection with zero changes, signifying that it has reached the end of the log. You can use the ChangeToken from the last change of the first batch to get the second batch, and so on until you get an empty collection.
Alternatively, you can pass an SPChangeQuery object to the GetChanges method. This object has properties that you can use to filter changes by object type and by change type. You can also adjust the size of the collection that is returned on a single roundtrip by setting the SPChangeQuery object’s FetchLimit property.
For more information about working with the change log, see Using the Change Log.
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.
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
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.