Create event log messages for document libraries in Microsoft Windows SharePoint Services

Applicable:
Microsoft _ WINDOWS _ SharePoint Services
Microsoft Office SharePoint Portal Server 2003

Summary: Use this article and sample code to enable the document library event log message in Microsoft Windows SharePoint Services. This document describes how to create an event handler for use in Microsoft Windows SharePoint Services. Download the sample code and modify it according to your environment. (13 page printing)

Download creatingeventsinadocumentlibrarysample.exe.

Content on this page

Overview
Event settings
Enable document library events
Create a Microsoft Visual Studio. NET 2003 project for the event
Associate Event code with document library
Summary
Appendix A-sample Installation
Appendix B-sample Event code

Overview

Microsoft _ WINDOWS _ SharePoint? Services provides document library events that allow you to build based on the Windows SharePoint services platform. You can create a managed code assembly that defines handlers for these events and then bind these handlers to the document library. The event handler can directly access the configuration database and content database by calling the Object Model (OM), or use Windows SharePoint Services as the user interface of other systems to call external services. You can use Microsoft Event Viewer to view event messages by defining event handlers and enabling event logging for a specific document library.

The following table lists the events in the document library provided by Windows SharePoint Services. You can enable logging for these events.

Table 1. Document Library events

Event	Description
Cancel check out	Undo the changes to the checked-out document.
Check in	Check the document in the document library.
Check out	Check out documents from the document library.
Copy	Copy the document in the document library.
Delete	Delete a document from the document library.
Insert	Save the new document to the document library.
Move or rename	Move or rename a document.
Update	Edit the values of existing documents or custom columns in the library.

In the context of Windows SharePoint Services, the event handler is an implementationIlisteventsinkThe. NET class of the interface. It is a single method used in the event handler.Onevent.SplisteventThe object contains information about the event. You can useTypeAttribute to identify the event type, and can be usedSiteAttribute to access the processing programMicrosoft. SharePointThe object model of the namespace.

You must install the hosted assembly that defines the event handler to the Global Assembly Cache (GAC) or the appropriate virtual server bin directory.

NoteIn addition, in the server farm configuration, each front-end web server must have a hosted Assembly installed.

To deploy an event handler on a server, you must enable event processing on the general settings page of the virtual server in SharePoint administration.

NoteYou must be a member of the local Administrators Group or SharePoint Administrators Group to enable event processing for the document library.

Back to Top event settings

The metadata of the document library can be bound to the document library through the attributes specified in the following table. You can specify these attributes for the document library on the "advanced settings of the document library" page, or by settingSplistObjectEventsinkassembly,EventsinkclassAndEventsinkdataAttribute code.

Table 2. Possible event settings

Set	Type	Description
Assembly name	String	Strong name of the Assembly file (in the GAC or bin directory) of the event handler
Class Name	String	Fully-qualified and case-sensitive class names in a dataset
Properties	String	Any string of custom attributes used by the event handler. the string length cannot exceed 255 characters.

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

Assembly name, Version =Version, Culture =Region, Publickeytoken =Public Key tag

You can view the default GAC location (% WinDir % \ assembly) in Microsoft Windows Resource Manager to identify these values. For example, by default,Windows SharePoint ServicesThe strong Assembly name is as follows:

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

The value you specify for the "Class Name" box must be a complete, case-sensitive class name, which is defined in the specified assembly and can be implementedIlisteventsinkInterface. For example, in the following example, the full name of the class is as follows:

WSSEventSink.EventSink

Back to the top of the page for enabling document library events

By default, Windows SharePoint Services does not enable document library events. To enable document library events, follow these steps. Events are enabled based on each virtual server. Therefore, when you enable events, they are enabled for all sites created on the specified virtual server.

Enable events on a virtual server

1. On the server running Windows SharePoint Services, click Start, point to administrative tools, and then click SharePoint management center ". See Figure 1.

   NoteThe default "Management Center" page is determined by the SharePoint product or technology installed on the computer. If necessary, click Windows SharePoint Services in the links pane to go to the Management Center page of Windows SharePoint Services:

   
   

   Figure 1. "Management Center" page of 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 you want to set, 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. In the "event handler" section on the "general settings of virtual servers" Page, select "open" in the "event handler status" box and click "OK ".

These events are now enabled on the virtual server hosting the SharePoint site.

Back to Top: Create a Microsoft Visual Studio. NET 2003 project for the event

This section describes how to create a custom event handler.

Important this section assumes that Microsoft Visual Studio _. NET 2003 has been installed on the server running Windows SharePoint Services. If you want to develop an event handler on a computer that does not have Windows SharePoint services installed, you need to access the server running Windows SharePoint Services. On the server computer< System Drive >:\ Program Files \ common files \ microsoft shared \ Web Server Extensions \ 60 \ ISAPIFolder ReplicationMicrosoft. Sharepoint. dllAnd transfer it to the folder of the computer on which the event handler will be developed.

Create a custom event handler in Visual Studio. NET 2003

1. On the File menu, point to new and click Project ".

2. In the project type window, click Visual Basic project, and then click class library in the template window ".

3. In the "name" field, TypeWsseventsinkAnd then click OK ".

4. In Solution Explorer, clickClass. VBIn the Properties window, under miscellaneous, change the file nameEventsink. VB.

   The next step is to addMicrosoft. Sharepoint. dll.

5. To do this, click Add reference on the project menu ". In the. NET list, click Microsoft. Sharepoint. dll, and then click OK ". If Windows SharePoint Services is not installed on this computer, Click Browse on the. NET tab and navigateMicrosoft. Sharepoint. dllCopy to the folder. Select the. dll file and click open ".

6. Copy the sample code in Appendix B and paste it into the code window of eventsink. VB, replace any existing default code in the project file, and click Save ".

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

8. Click 4. Registry format ({xxxxxxx-XXXX... XXXX}), click Copy, and then click exit ".

9. In Solution Explorer, clickAssemblyinfo. VBTo open the assemblyinfo. VB code window.

10. In the assemblyinfo. VB code window, locate the guid of the assembly and replace the string with the copied guid.

11. In assemblyinfo. VB, find the following code and add a version number.

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

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

12. Save the project file.

    Then, you must give the project a strong name before using it in Windows SharePoint Services:

13. On the development computer, click Start, point to all programs, and point to Microsoft Visual Studio. NET 2003, pointing to "Visual Studio. and then click Visual Studio. NET 2003 command prompt ".

14. Type the following command:Sn.exe-k c: \ keypair. SNK

    NoteYou can change the path to any required path.

15. In the event receiving project, open the assemblyinfo. VB file and add the downstream to the end of the module.

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

16. Now you can compile the project. To do this, click Generate solution on the generate menu ".

17. Verify and resolve all generated errors, and save all changes. If necessary, rebuild the solution.

18. The next step is to copy the new. DLL to the Global Assembly Cache (GAC) of the server running Windows SharePoint Services. To this end, browse to the location of the project on the development computer, and then add Windows SharePoint Services eventsink. copy the DLL file to the GAC on the Windows SharePoint Services server. The GAC is located in the following location that corresponds to Windows 2003 and Windows XP:

    %windir%\assembly

19. After the Assembly is copied to GAC, note the value of "public key mark" because this value is required when the code is associated with the document library in Windows SharePoint Services. To find the Public Key tag of the hosted assembly, open GAC in Windows Resource Manager and observe the "Public Key tag" column.

Now, you have successfully created the event handler to be used in Windows SharePoint Services.

NoteFor the complete version of this sample code, download creatingeventsinadocumentlibrarysample.exe.

Back to the top page, associate the Event code with the document library.

After creating a custom event handler, you must associate it with the relevant document library in which you want to execute the code. This step also serves as the safecontrol for Windows SharePoint services. Therefore, you do not have to modify other SharePoint files, suchWeb. config.

Associated Event code

1. On the SharePoint site, browse to the document library associated with the Event code.

2. In the chain bar, click Modify settings and bar ".

3. In the general Settings section, click Change advanced settings ".

4. If you use the sample hosted Assembly provided in this article, type the following in the Assembly Name text box in the event handler section:

   Wsseventsink, version = 1.0.0.2, culture = neutral, publickeytoken = 25a7f6c72becfbbb

   NoteIf you have created your own code, you need to update it with the value corresponding to your hosted assemblyVersionAndPublickeytokenValue.

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

   Wsseventsink. eventsink

6. Click OK ".

Now you have associated the Custom Event Handler code with the document library.

Back to Top Summary

This topic describes how to enable event log messages in the document library in Microsoft Windows SharePoint Services. This article describes how to use Microsoft Visual Studio. NET 2003 to create an event handler and provides a sample code that allows you to deploy Microsoft SharePoint products and technologies. To view the sample result set of this Code, see "Appendix A-sample installation ".

Back to Top Appendix A-example installation

The following sample event is based on the Custom Event code used in this article. To open the Event Viewer, click Start, point to administrative tools, and then click event viewer ". Displays the default view of the Event Viewer.

Figure 2. default view of Event Viewer

Displays the properties of the 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.docItem 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 = 
Back to Top Appendix B-sample Event code
The following sample code can be used to create a custom event handler. This code is written in Microsoft Visual Studio. NET 2003 in Microsoft Visual Basic _. net.


Option Explicit On Imports SystemImports System.IOImports Microsoft.SharePointPublic Class EventSink : Implements IListEventSink    Public Sub OnEvent(ByVal listEvent As Microsoft.SharePoint.SPListEvent) ImplementsMicrosoft.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 'OnEventEnd Class 'EventSink