SPChange Class

Article
07/24/2014

Represents a change that has been made to a SharePoint object within the scope of an item, list, Web site, site collection, or content database, or to a security policy within the scope of a Web application.

Inheritance Hierarchy

System.Object
Microsoft.SharePoint.SPChange

Namespace: Microsoft.SharePoint
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online

Syntax

'Declaration
<SubsetCallableTypeAttribute(ForcePolymorphicForReturnTypes := True)> _
<ClientCallableTypeAttribute(Name := "Change", ServerTypeId := "{c717121b-f82f-4afb-a2b7-25f67522120f}")> _
Public Class SPChange
'Usage
Dim instance As SPChange

[SubsetCallableTypeAttribute(ForcePolymorphicForReturnTypes = true)]
[ClientCallableTypeAttribute(Name = "Change", ServerTypeId = "{c717121b-f82f-4afb-a2b7-25f67522120f}")]
public class SPChange

Remarks

Each entry in the SharePoint Foundation change log is represented by 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 change log does not record changes to all SharePoint objects, only to selected object types. The object types that are tracked in the change log are listed in the following table, along with the subclasses of SPChange that represent changes to them.

Subclass	Represents changes to
SPChangeAlert	SPAlert objects.
SPChangeContentType	SPContentType objects.
SPChangeField	SPField objects.
SPChangeFile	SPFile objects that exist outside of a list and do not have corresponding items.
SPChangeFolder	SPFolder objects that exist outside of a list and do not have corresponding items.
SPChangeGroup	SPGroup objects.
SPChangeItem	SPListItem objects and files and folders that might be associated with them.
SPChangeList	SPList objects.
SPChangeSecurityPolicy	SPPolicy objects.
SPChangeSite	SPSite objects.
SPChangeUser	SPUser objects.
SPChangeView	SPView objects.
SPChangeWeb	SPWeb objects.

Use the GetChanges method of the SPList, SPWeb, SPSite, or SPContentDatabase object to return a 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.

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 retrieves all entries in the change log for a content database and prints information about each change to the console.

using System;
using Microsoft.SharePoint;

namespace Test
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite site = new SPSite("https://localhost"))
            {
                using (SPWeb web = site.RootWeb)
                {
                    // Construct a query.
                    SPChangeQuery query = new SPChangeQuery(true, true);

                    SPTimeZone timeZone = web.RegionalSettings.TimeZone;
                    long total = 0;

                    // Get changes in batches.
                    while (true)
                    {
                        // Fetch a set of changes.
                        SPChangeCollection changes = site.ContentDatabase.GetChanges(query);
                        total += changes.Count;

                        // Write info about each change to the console.
                        foreach (SPChange change in changes)
                        {
                            // Print the date of the change.
                            Console.WriteLine("\nDate: {0}",
                                              timeZone.UTCToLocalTime(change.Time).ToString());

                            // Print the ID of the site where the change took place.
                            Console.WriteLine("Site ID: {0}", change.SiteId.ToString("B"));

                            // Print the type of object that was changed.
                            //   GetType().Name returns SPChangeItem, SPChangeList, etc.
                            //   Remove the "SPChange" part of the name.
                            string objType = change.GetType().Name.Replace("SPChange", null);
                            Console.WriteLine("Type of object: {0}", objType);

                            // Print the nature of the change.
                            Console.WriteLine("Type of change: {0}", change.ChangeType.ToString());
                        }

                        // 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 changes: {0}", total);
                }
            }
            Console.Write("\nPress ENTER to continue...");
            Console.ReadLine();
        }
    }
}

Imports System
Imports Microsoft.SharePoint

Module Test

    Sub Main()

        Using site As SPSite = New SPSite("http://lswss5/sites/don")
            Using web As SPWeb = site.RootWeb
                ' Construct a query.
                Dim query As SPChangeQuery = New SPChangeQuery(True, True)

                Dim timeZone As SPTimeZone = web.RegionalSettings.TimeZone
                Dim total As Long = 0

                ' Get changes in batches.
                While True
                    ' Fetch a set of changes.
                    Dim changes As SPChangeCollection = site.ContentDatabase.GetChanges(query)
                    total += changes.Count

                    ' Write info about each change to the console.
                    Dim change As SPChange
                    For Each change In changes
                        ' Print the date of the change.
                        Console.WriteLine(vbCrLf + "Date: {0}", _
                                          timeZone.UTCToLocalTime(change.Time).ToString())

                        ' Print the ID of the site where the change took place.
                        Console.WriteLine("Site ID: {0}", change.SiteId.ToString("B"))

                        ' Print the type of object that was changed.
                        '   GetType().Name returns SPChangeItem, SPChangeList, etc.
                        '   Remove the "SPChange" part of the name.
                        Dim objType As String = change.GetType().Name.Replace("SPChange", Nothing)
                        Console.WriteLine("Type of object: {0}", objType)

                        ' Print the nature of the change.
                        Console.WriteLine("Type of change: {0}", change.ChangeType.ToString())
                    Next

                    ' Break out of loop if we have the last batch
                    If changes.Count < query.FetchLimit Then
                        Exit While
                    End If
                    ' Otherwise, go get another batch
                    query.ChangeTokenStart = changes.LastChangeToken

                End While

                Console.WriteLine(vbCrLf + "Total changes: {0}", total)

            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.

Inheritance Hierarchy

Share via

SPChange Class

Inheritance Hierarchy

Syntax

Remarks

Examples

Thread Safety

See Also

Reference

Other Resources

Inheritance Hierarchy

Additional resources