Writing Custom Entries to the Audit Log in Windows SharePoint Services 3.0

Microsoft Windows SharePoint Services provides an auditing facility that allows you to see the actions users take within the context of a site collection. Examples of user actions that you can audit automatically include viewing, updating, and deleting list items and documents, as well as viewing site pages. One important limitation of the built-in auditing facility is that it cannot audit access to application pages that are deployed within the \LAYOUTS directory.

If you want to audit the actions of users as they view your custom application pages, you must add code that writes custom audit entries into the Windows SharePoint Services audit log. You can write custom audit entries within the context of any auditable object, such as those of type SPSite, SPWeb, SPList, and SPListItem.

Auditable objects, such as SPSite, SPWeb, SPList, and SPListItem, expose an Audit property. This property contains a reference to an SPAudit object that exposes a method named WriteAuditEvent. Here is an example of code within a custom application page that writes a custom audit entry for a specific SPListItem object.

SPSite siteColl = SPContext.Current.Site;
SPWeb site = SPContext.Current.Web;
string ListId = Request.QueryString["ListId"];
string ItemId = Request.QueryString["ItemId"];
SPList list1 = site.Lists[new Guid(ListId)];
SPListItem item1 = list1.Items.GetItemById(Convert.ToInt32(ItemId));
item1.Audit.WriteAuditEvent(SPAuditEventType.Custom, 
                            "CustomViewAuditEvent", "");

Dim siteColl As SPSite = SPContext.Current.Site
Dim site As SPWeb = SPContext.Current.Web
Dim ListId As String = Request.QueryString("ListId")
Dim ItemId As String = Request.QueryString("ItemId")
Dim list1 As SPList = site.Lists(New Guid(ListId))
Dim item1 As SPListItem = _    
    list1.Items.GetItemById(Convert.ToInt32(ItemId))
item1.Audit.WriteAuditEvent(SPAuditEventType.Custom, _
                            "CustomViewAuditEvent", "")

When you write a custom audit entry by using the WriteAuditEvent method, Windows SharePoint Services records the name of the current user by using the identity of the executing code. That means you should avoid programming techniques that elevate privileges or that use impersonation before making the call to WriteAuditEvent because that can cause the wrong user to be associated with the audit entry.

When you call WriteAuditEvent, the first argument is an enumeration value of type SPAuditEventType, which indicates the type of audit entry you are making. The second parameter is a string that allows you to indicate the name of the audit source.

item1.Audit.WriteAuditEvent(SPAuditEventType.Delete, "MySource", "");

item1.Audit.WriteAuditEvent(SPAuditEventType.Delete, "MySource", "")

The third parameter passed to the WriteAuditEvent method is an open-ended string value that you can use to pass whatever custom data you want to record for a custom log entry. This allows you to pass a domain-specific XML document to track any type of information you want when writing an entry to the audit log for a particular event.

item1.Audit.WriteAuditEvent(SPAuditEventType.Custom, 
                            "MySource", 
                            "<MyData>MyValue</MyData>");

item1.Audit.WriteAuditEvent(SPAuditEventType.Custom, _
                            "MySource", _
                            "<MyData>MyValue</MyData>")

As you write custom XML documents into entries in the audit log, you also must provide the complementary code that reads these audit entries and interprets the data within these XML documents.

Watch the Video

Length: 5:15 | Size: 17.3 MB | Type: WMV

• Item-Level Auditing with SharePoint Server 2007

• SharePoint Developer Center

• Office Developer Center