SPList.GetChanges method (SPChangeToken, SPChangeToken)

Returns a collection of changes logged over a specified period of time.

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

'Declaration
Public Function GetChanges ( _
	changeToken As SPChangeToken, _
	changeTokenEnd As SPChangeToken _
) As SPChangeCollection
'Usage
Dim instance As SPList
Dim changeToken As SPChangeToken
Dim changeTokenEnd As SPChangeToken
Dim returnValue As SPChangeCollection

returnValue = instance.GetChanges(changeToken, _
	changeTokenEnd)

Parameters

changeToken
Type: Microsoft.SharePoint.SPChangeToken

The starting date and time.

changeTokenEnd
Type: Microsoft.SharePoint.SPChangeToken

The ending date and time.

Return value

Type: Microsoft.SharePoint.SPChangeCollection
The changes.

ExceptionCondition
SPException

changeToken or changeTokenEnd is not a valid token.

When you construct the SPChangeToken objects to use with this method, pass SPChangeCollection.CollectionScope.List as the constructor’s first argument, the value of the current object’s SPList.ID property as the second argument, and a DateTime object as the third argument.

In addition, the following rules apply:

  • If either token refers to a time before the start of the current change log, the method throws an exception.

  • If the time of the second token is before the time of the first token, the method returns an empty collection.

  • If the first token is a null reference (Nothing in Visual Basic), the change collection that is returned starts at the beginning of the current change log.

  • If the second token is a null reference (Nothing in Visual Basic), the change collection that is returned includes all changes after the date specified by the first change token, up to the limit for a single collection. If more changes occurred in this period, the first batch is returned.

NoteNote

By default, the change log retains data for 60 days. You can configure the retention period by setting the ChangeLogRetentionPeriod property.

The following example is a console application that queries the change log for changes to a list during a period of seven days. After retrieving the changes, the application prints information about each change to the console.

Imports System
Imports Microsoft.SharePoint

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

            ' Get a list.
            Dim list As SPList = webSite.Lists(0)

            Dim startToken As New SPChangeToken(SPChangeCollection.CollectionScope.List, _
                                                list.ID, _
                                                New DateTime(2008, 10, 12))

            Dim endToken As New SPChangeToken(SPChangeCollection.CollectionScope.List, _
                                              list.ID, _
                                              New DateTime(2008, 10, 18))

            Dim timeZone As SPTimeZone = webSite.RegionalSettings.TimeZone
            Dim total As Integer = 0

            ' Get the first batch of changes.
            Dim changes As SPChangeCollection = list.GetChanges(startToken, endToken)

            ' Loop until we reach the end of the log.
            While changes.Count > 0

               total += changes.Count

               ' Print info about each change to the console.
               For Each change As SPChange In changes
                  Console.WriteLine(vbCrLf + "Date: {0}", timeZone.UTCToLocalTime(change.Time).ToString())
                  Console.WriteLine("Object type: {0}", change.GetType().ToString())
                  Console.WriteLine("Change: {0}", change.ChangeType.ToString())
               Next change

               ' Go get another batch of changes starting where we left off.
               startToken = changes.LastChangeToken
               changes = list.GetChanges(startToken, endToken)

            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
Show: