Creating Event Log Messages for a Document Library in Microsoft Windows SharePoint Services

Nigel Bridport
Microsoft Corporation

October 2003

Applies to:
    Microsoft® Windows® SharePoint™ Services
    Microsoft Office SharePoint Portal Server 2003

Summary: Use this article and code sample to enable event log messages for a document library in Microsoft Windows SharePoint Services. This article provides a walk-through of how to create an event handler for use with Microsoft Windows SharePoint Services. Download the code sample and modify it for your own environment. (13 printed pages)

Download CreatingEventsforaDocumentLibrarySample.exe.

Contents

Overview
Event Settings
Enabling Events for Document Libraries
Creating a Microsoft Visual Studio .NET 2003 Project for an Event
Associating Event Code with a Document Library
Conclusion
Appendix A-Sample Installation
Appendix B-Sample Event Code

Overview

Microsoft® Windows® SharePoint™ Services provides document library events that enable you to build upon the Windows SharePoint Services platform. You can create managed code assemblies that define handlers for these events and then bind the handlers to document libraries. The event handlers call into the object model (OM) to access the configuration and content databases directly or they invoke external services, using Windows SharePoint Services as a user interface for other systems. By defining the event handlers and enabling event logging for a specific document library, you can view event messages by using the Microsoft Event Viewer.

The following table describes the events for document libraries provided by Windows SharePoint Services for which you can enable logging.

Table 1. Document library events

In the context of Windows SharePoint Services, an event handler is a .NET class that implements the IListEventSink interface, whose single method, OnEvent, is used within the handler. The SPListEvent object contains information about an event that occurs. You can identify the type of the event from the Type property. You can use the Site property to access the object model of the Microsoft.SharePoint namespace within the handler.

You must install the managed assemblies that define an event handler to the Global Assembly Cache (GAC) or the appropriate virtual server BIN directory.

Note   Additionally, in a server farm configuration, each front-end Web server must have the managed assembly installed.

To deploy an event handler on a server, you must enable event handling on the Virtual Server General Settings page in SharePoint Central Administration.

**Note **  You must be a member of the local Administrators group or the SharePoint Administrators group to enable event handling for a document library.

Event Settings

The metadata for a document library binds the class of an event handler to the document library by means of the properties specified in the following table. You can specify these properties on the Document Library Advanced Settings page for the document library, or through code that sets the EventSinkAssembly, EventSinkClass and EventSinkData properties of the SPList object.

Table 2. Possible event settings

After you install the event handler assembly, on the Document Library Advanced Settings page for the document library, you must specify the strong name of the assembly in the Assembly Name box, in the following format:

Assembly_Name, **Version=Version, Culture=**Culture, **PublicKeyToken=**Public_Key_Token

You can identify these values by browsing to the default GAC location (%windir%\assembly) in Microsoft Windows Explorer. For example, by default, the strong name for the Windows SharePoint Services assembly is as follows:

Microsoft.SharePoint, Version=11.0.0.0, Culture=Neutral, PublicKeyToken=71e9bce111e9429c

The value that you specify for the Class Name box must be the complete, case-sensitive name of a class defined in the specified assembly that implements the IListEventSink interface. For example, the full name of the class in the following example is as follows:

WSSEventSink.EventSink

Enabling Events for Document Libraries

By default, Windows SharePoint Services does not enable events for a document library. Follow the steps below to enable events for a document library. Events are enabled on a per virtual server basis. Therefore, when you enable events, you enable them for all sites created on the specified virtual server.

To enable events on a virtual server

1. On the server running Windows SharePoint Services, click Start, point to Administrative Tools, and then click SharePoint Central Administration. See Figure 1.

   **Note   **The default Central Administration page is determined according to which SharePoint product or technology is installed on the computer. If necessary, in the Link pane, click Windows SharePoint Services to go to the Windows SharePoint Services Central Administration page:

   

   Figure 1. The Central Administration page for Windows SharePoint Services

2. In the Virtual Server Configuration section, click Configure virtual server settings.

3. On the Virtual server list, click the virtual server with which you want to work, for example, click Default Web Site.

4. On the Virtual Server Settings page, in the Virtual Server Management section, click Virtual server general settings.

5. On the Virtual Server General Settings page, in the Event Handlers section, in the Event handlers are box, select On, and then click OK.

The virtual server that is hosting the SharePoint site is now enabled for events.

Creating a Microsoft Visual Studio .NET 2003 Project for an Event

This section describes how to create a custom event handler.

Important   This section assumes that Microsoft Visual Studio® .NET 2003 is installed on the server running Windows SharePoint Services. If you want to develop the Event Handler on a computer that does not have Windows SharePoint Services installed, you will need access to a server running Windows SharePoint Services. On the server computer, copy Microsoft.SharePoint.dll from the <System Drive>:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI folder and transfer it to a folder on the computer where you will be developing the event handler

To create a custom event handler in Visual Studio .NET 2003

1. On the File menu, point to New and then click Project.

2. In the Project Types window, click Visual Basic Projects and then in the Templates window, click Class Library*.*

3. In the Name field, type WSSEventSink, and then click OK*.*

4. From the Solution Explorer, click Class.vb and in the Properties window, under Misc, change the File Name to EventSink.vb.

   The next step is to add a reference to Microsoft.SharePoint.dll.

5. To do so, on the Project menu, click Add Reference. In the .NET list, click Microsoft.SharePoint.dll and then click OK. If this computer does not have Windows SharePoint Services installed, then on the .NET tab, click Browse and then navigate to the folder where you copied the Microsoft.SharePoint.DLL to as described previously. Select the .DLL and click Open.

6. Copy the sample code from Appendix B and paste it in the code window for EventSink.vb, replacing any default code already present**in the project file and then click Save.

7. On the Tools menu, click Create GUID to create a GUID*.*

8. Click 4. Registry Format (ie. {xxxxxxx-xxxx. . . xxxx}), click Copy, and then click Exit.

9. In Solution Explorer, click AssemblyInfo.vb to open the code window for AssemblyInfo.vb.

10. In the code window for AssemblyInfo.vb, locate the assembly GUID entry and replace the string with the GUID you copied.

11. In the AssemblyInfo.vb, locate the following and add a version number.

    <Assembly: AssemblyVersion("1.0.*")> 
    

    For example, <Assembly: AssemblyVersion("1.0.0.1")>

12. Save the project file.

    Next, you need to strong-name the project before using it with Windows SharePoint Services:

13. On your development computer, click Start, point to All Programs, point to Microsoft Visual Studio .NET 2003, point to Visual Studio .NET Tools, and then click Visual Studio .NET 2003 Command Prompt.

14. Type the following sn.exe –k c:\keypair.snk

    Note   You can change the path to whatever is required.

15. In the event sink project open the AssemblyInfo.vb file and add the following line to the end of the module

    <Assembly: AssemblyKeyFile("c:\\keypair.snk")>

16. You can now compile the project. To do so, on the Build menu, click Build Solution.

17. Verify and resolve any build errors and save any changes. Rebuild the solution if necessary.

18. The next step is to copy the new .dll to the Global Assembly Cache (GAC) on your server running Windows SharePoint Services. To do this, browse to the location of the project on your development computer and copy the Windows SharePoint Services EventSink.dll file to the GAC on the Windows SharePoint Services server located at the following location relevant for Windows 2003 and Windows XP:

    %windir%\assembly
    

19. Note the value of the Public Key Token once you have copied the assembly to the GAC as this value is required when associating the code with a document library in Windows SharePoint Services. To find the Public Key Token for the managed assembly, open the GAC in Windows Explorer and observe the Public Key Token column.

You have now successfully created an event handler for use with Windows SharePoint Services.

Note   For a complete version of this code sample, download CreatingEventsforaDocumentLibrarySample.exe.

Associating Event Code with a Document Library

After creating your custom event handler, you must associate it with the relevant document library where you wish the code to execute. This step also acts as the SafeControl entry for Windows SharePoint Services; therefore you do not need to modify other SharePoint files, such as the Web.config.

To associate event code

1. On your SharePoint site, browse to the document library that you want to associate with this event code.

2. In the link bar, click Modify settings and columns.

3. In the General Settings section, click Change advanced settings.

4. If you are using the sample managed assembly provided by this article, then in the Event Handler section, in the Assembly Name text box, type the following:

   WSSEventSink, Version=1.0.0.2, Culture=neutral, PublicKeyToken=25a7f6c72becfbbb

   **Note   **If you have created your own code, then you will need to update the Version and PublicKeyToken values with the one relevant for your managed assembly.

5. In the Class Name text box, type the following:

   WSSEventSink.EventSink

6. Click OK.

You have now associated the custom event handler code with the document library.

Conclusion

This article provides an overview of how to enable event log messages for a document library in Microsoft Windows SharePoint Services. It provides in-depth instructions on how to create an event handler by using Microsoft Visual Studio .NET 2003 and provides a code sample for use in your own deployment of Microsoft SharePoint Products and Technologies. To see an example result set from the code, see Appendix A—Sample Installation.

Appendix A—Sample Installation

The following are sample events based on the custom event code used in this paper. To open the event viewer, click Start, point to Administrative Tools and then click Event Viewer. The following figure shows the default view of the Event Viewer.

Figure 2. Default view of the event viewer

The following figure shows the properties of a sample event.

Figure 3. Sample event

The following example shows a complete description of the event:

Event occurred in <Shared Documents>
Event type was <Insert>

Item that caused the event was <Shared Documents/sample.doc

Item field details are as follows ->

Field name = <Created Date> 
   Value = <08/07/2003 12:00:58>
Field name = <Created By> 
   Value = <1; user_name\administrator>
Field name = <Last Modified> 
   Value = <08/07/2003 12:00:58>
Field name = <Modified By> 
   Value = <1; user_name\administrator>
Field name = <Approval Status> 
   Value = <0>
Field name = <Approver Comments> 
   Value = <>
Field name = <URL Path> 
   Value = </sites/site_name/Shared Documents/Steps to enable events for sample.doc>
Field name = <URL Dir Name> 
   Value = <11; sites/site_name/Shared Documents>
Field name = <Modified> 
   Value = <08/07/2003 12:00:58>
Field name = <Created> 
   Value = <08/07/2003 12:00:58>
Field name = <File Size> 
   Value = <193024>
Field name = <File System Object Type> 
   Value = <0>
Field name = <ID of the User who has the item checked out> 
   Value = <11; >
Field name = <Name> 
   Value = <Steps to enable events for sample.doc>
Field name = <Virus Status> 
   Value = <11; 193024>
Field name = <Checked Out To> 
   Value = <11; >
Field name = <Checked Out To> 
   Value = <11; >
Field name = <Document Modified By> 
   Value = <user_name\administrator>
Field name = <Document Created By> 
   Value = <user_name\administrator>
Field name = <File Type> 
   Value = <doc>
Field name = <HTML File Type> 
   Value = <>
Field name = <Source Url> 
   Value = <>
Field name = <Shared File Index> 
   Value = <>
Field name = <Name> 
   Value = <Steps to enable events for sample.doc>
Field name = <Name> 
   Value = <Steps to enable events for sample.doc>
Field name = <Select> 
   Value = <11>
Field name = <Select> 
   Value = <11>
Field name = <Edit> 
   Value = <>
Field name = <Type> 
   Value = <doc>
Field name = <Server-based Relative URL> 
   Value = </sites/site_name/Shared Documents/sample.doc>
Field name = <Encoded Absolute URL> 
   Value = <http://server_name/sites/site_name/Shared%20Documents/sample.doc>
Field name = <Name> 
   Value = <Steps to enable events for sample.doc>
Field name = <File Size> 
   Value = <193024>
Field name = <InstanceID> 
   Value = <>
Field name = <Title> 
   Value = <Steps to enable events for sample.doc>

Appendix B—Sample Event Code

The following is sample code available for use when creating custom event handlers. The code is written in Microsoft Visual Basic® .NET using Microsoft Visual Studio .NET 2003.

Option Explicit On 

Imports System
Imports System.IO
Imports Microsoft.SharePoint

Public Class EventSink : Implements IListEventSink

    Public Sub OnEvent(ByVal listEvent As Microsoft.SharePoint.SPListEvent) Implements
Microsoft.SharePoint.IListEventSink.OnEvent
        On Error Resume Next
        Dim SharePointWeb As SPWeb = listEvent.Site.OpenWeb()
        Dim SharePointEventItem As SPFile = SharePointWeb.GetFile(listEvent.UrlAfter)
        Dim oItem As SPListItem = SharePointEventItem.Item
        Dim oField As SPField
        Dim oFields As SPFieldCollection
        Dim sLog As String

        'Check to make sure that we actually have the event item!
        If SharePointEventItem Is Nothing Then
            EventLog.WriteEntry("Event Log Test", "Cannot retrieve event item", EventLogEntryType.Information,
 listEvent.Type)
            Exit Sub
        End If

        'Get the fields collection for the Event Item
        oFields = oItem.Fields

        'Inform the user of some top-level information such as the source of the event
        sLog = "Event occurred in <" + listEvent.Title + ">" + vbCrLf
        sLog = sLog + "Event type was <" + listEvent.Type.ToString + ">" + vbCrLf + vbCrLf

        'The delete event carries no useful information to log in the fields collection
        If (Len(listEvent.UrlAfter.ToString) > 1) Then
            sLog = sLog + "Item that caused the event was <" + listEvent.UrlAfter.ToString + ">" + vbCrLf + vbCrLf
            sLog = sLog + "Item field details are as follows ->" + vbCrLf + vbCrLf

            'Iterate through the items fields and detail them
            For Each oField In oFields
                sLog = sLog + "Field name = <" + oField.Title.ToString + "> " + vbCrLf + vbTab + 
"Value = <" + oItem(oField.Title.ToString) + ">" + vbCrLf
            Next
        End If

        'Event Id Explanation
        '  -1 : Invalid
        '   0 : Insert
        '   1 : Update
        '   2 : Delete()
        '   3 : Move or Rename
        '   4 : Copy
        '   5 : CheckIn
        '   6 : CheckOut
        '   7 : UnCheckOut
        'Write out the collected information to the Application Log
        EventLog.WriteEntry("Event Log Test", sLog, EventLogEntryType.Information, listEvent.Type)

        'This is just some sample code that shows how to operate on the different
        '  event types.
        Select Case listEvent.Type

            Case SPListEventType.CheckIn
                'Perform necessary actions for the CheckIn event

            Case SPListEventType.CheckOut
                'Perform necessary actions for the CheckOut event

            Case SPListEventType.Copy
                'Perform necessary actions for the Copy event

            Case SPListEventType.Delete
                'Perform necessary actions for the Delete event

            Case SPListEventType.Insert
                'Perform necessary actions for the Insert event

            Case SPListEventType.Invalid
                'Perform necessary actions for the Invalid event

            Case SPListEventType.Move
                'Perform necessary actions for the Move event

            Case SPListEventType.UncheckOut
                'Perform necessary actions for the UnCheckOut event

            Case SPListEventType.Update
                'Perform necessary actions for the Update event

        End Select
    End Sub 'OnEvent
End Class 'EventSink