How to: Filter the Change Log by Change Type

Applies to: SharePoint Foundation 2010

This example is a console application that queries the change log at content database scope. The query asks for changes to SPUser and SPGroup objects that involve adding, updating, or deleting either type of object and also changes that modify the membership of groups.

Note that the example tries to account for the fact that security for the change log is managed independently of the security for objects in the system. When you compile and run the example, your privileges may permit you to read the change log and discover which types of objects have changed and which types of changes have been made to them, but you might not be permitted to access the objects themselves. As a result, the code might print the information that on a certain date an SPUser object was added to a site collection, and it could print the GUID for the object that was added, but it might still throw an UnauthorizedAccessException when it attempts to retrieve the object. Having permission to access the change log is not the same as having permission to access the changed objects.

Example

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace Test
{
    class Program
    {
        static SPUserCollection m_users;
        static SPGroupCollection m_groups;

        static void Main(string[] args)
        {
            using (SPSite currentSite = new SPSite("http://localhost"))
            {
                SPTimeZone tz = currentSite.RootWeb.RegionalSettings.TimeZone;
                SPContentDatabase db = currentSite.ContentDatabase;
                m_users = currentSite.RootWeb.AllUsers;
                m_groups = currentSite.RootWeb.Groups;

                // Construct a query.
                SPChangeQuery query = new SPChangeQuery(false,  // Specify object types
                                                        false   // Specify change types
                                                        );
                // Specify object types. 
                query.User = true;
                query.Group = true;

                // Specify change types. 
                query.Add = true;
                query.Delete = true;
                query.Update = true;
                query.GroupMembershipAdd = true;
                query.GroupMembershipDelete = true;

                long total = 0;
                while (true)
                {
                    SPChangeCollection changes = db.GetChanges(query);

                    total += changes.Count;

                    foreach (SPChange change in changes)
                    {
                        // Print the date of the change.
                        Console.WriteLine("\nDate: {0}",
                                          tz.UTCToLocalTime(change.Time).ToString());

                        // Get the url, user collection, and group collection
                        // of the site where the change took place.
                        foreach (SPSite site in db.Sites)
                        {
                            if (site.ID == change.SiteId)
                            {
                                Console.WriteLine("Site Url: {0}", site.Url);
                                try
                                {
                                    m_users = site.RootWeb.AllUsers;
                                    m_groups = site.RootWeb.Groups;
                                }
                                catch (UnauthorizedAccessException)
                                {
                                    // Do nothing. The failure is handled elsewhere in the code.
                                }
                                finally
                                {
                                    site.Dispose();
                                }
                                break;
                            }
                            site.Dispose();
                        }

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

                        // Get information about a user change.
                        if (change is SPChangeUser)
                        {
                            SPChangeUser userChange = (SPChangeUser)change;
                            // Print the user name.
                            string userName = GetPrincipalName(userChange.Id, true);
                            Console.WriteLine("User name: {0}", userName);
                        }

                        // Get information about a group change.
                        if (change is SPChangeGroup)
                        {
                            SPChangeGroup groupChange = (SPChangeGroup)change;
                            // Print the group name.
                            string groupName = GetPrincipalName(groupChange.Id, false);
                            Console.WriteLine("Group name: {0}", groupName);

                            if (groupChange.ChangeType == SPChangeType.MemberAdd ||
                                groupChange.ChangeType == SPChangeType.MemberDelete)
                            {
                                string userName = GetPrincipalName(groupChange.UserId, true);
                                Console.WriteLine("User name: {0}", userName);
                            }
                        }
                    }
                    if (changes.Count < query.FetchLimit)
                        break;
                    query.ChangeTokenStart = changes.LastChangeToken;
                }
                Console.WriteLine("\nTotal changes = {0:#,#}", total);
            }
            Console.Write("\nPress ENTER to continue...");
            Console.Read();
        }

        static string GetPrincipalName(int id, bool isUser)
        { 
            string name = string.Empty;
            try
            {
                if (isUser)
                {
                    SPUser user = m_users.GetByID(id);
                    name = user.LoginName;
                }
                else
                {
                    SPGroup group = m_groups.GetByID(id);
                    name = group.Name;
                }
            }
            catch (UnauthorizedAccessException)
            {
                name = "unknown (access not authorized)";
            }
            catch (SPException)
            {
                name = "unknown (not found)";
            }
            return name;
        }
    }
}
Imports System
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Administration

Module ConsoleApp

   Dim m_users As SPUserCollection
   Dim m_groups As SPGroupCollection

   Sub Main()
      Using currentSite As SPSite = New SPSite("http://localhost")

         Dim tz As SPTimeZone = currentSite.RootWeb.RegionalSettings.TimeZone
         Dim db As SPContentDatabase = currentSite.ContentDatabase
         m_users = currentSite.RootWeb.Users
         m_groups = currentSite.RootWeb.Groups

         ' Construct a query.
         Dim query As SPChangeQuery = New SPChangeQuery(False, False)

         ' Specify object types.
         query.User = True
         query.Group = True

         ' Specify change types. 
         query.Add = True
         query.Delete = True
         query.Update = True
         query.GroupMembershipAdd = True
         query.GroupMembershipDelete = True

         Dim total As Long = 0
         While True
            Dim changes As SPChangeCollection = db.GetChanges(query)
            total += changes.Count

            Dim change As SPChange
            For Each change In changes
               ' Print the date of the change.
               Console.WriteLine(vbCrLf + "Date: {0}", _
                                    tz.UTCToLocalTime(change.Time).ToString())

               ' Get the url, user collection, and group collection
               ' of the site where the change took place.
               Dim site As SPSite
               For Each site In db.Sites
                  If site.ID = change.SiteId Then
                     Console.WriteLine("Site Url: {0}", site.Url)

                     Try
                        m_users = site.RootWeb.AllUsers
                        m_groups = site.RootWeb.Groups
                     Catch
                        ' Do nothing. The failure is handled elsewhere in the code.
                     Finally
                        site.Dispose()
                     End Try

                     Exit For
                  End If
                  site.Dispose()
               Next

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

               ' Get information about a user change.
               If TypeOf change Is SPChangeUser Then
                  Dim userChange As SPChangeUser = CType(change, SPChangeUser)
                  ' Print the user name.
                  Dim userName As String = GetPrincipalName(userChange.Id, True)
                  Console.WriteLine("User name: {0}", userName)
               End If

               ' Get information about a group change.
               If TypeOf change Is SPChangeGroup Then
                  Dim groupChange As SPChangeGroup = CType(change, SPChangeGroup)
                  ' Print the group name.
                  Dim groupName As String = GetPrincipalName(groupChange.Id, False)
                  Console.WriteLine("Group name: {0}", groupName)

                  If (groupChange.ChangeType = SPChangeType.MemberAdd) Or _
                     (groupChange.ChangeType = SPChangeType.MemberDelete) Then
                     Dim userName As String = GetPrincipalName(groupChange.UserId, True)
                     Console.WriteLine("User name: {0}", userName)
                  End If
               End If

            Next

            If changes.Count < changes.FetchLimit Then
               Exit While
            End If

            query.ChangeTokenStart = changes.LastChangeToken
            changes = db.GetChanges(query)

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

      Console.Write(vbCrLf + "Press ENTER to continue...")
      Console.Read()
   End Sub

   Function GetPrincipalName(ByVal id As Integer, ByVal isUser As Boolean) As String
      Dim name As String = String.Empty
      Try
         If isUser Then
            Dim user As SPUser = m_users.GetByID(id)
            name = user.LoginName
         Else
            Dim group As SPGroup = m_groups.GetByID(id)
            name = group.Name
         End If
      Catch secex As UnauthorizedAccessException
         name = "unknown (access not authorized)"
      Catch spex As SPException
         name = "unknown (not found)"
      End Try
      Return name
   End Function

End Module

See Also

Tasks

How to: Filter the Change Log by Object Type

Concepts

Querying the Change Log for Specific Changes