Working with List Event Receiver

Until now we worked with List Item Event Receivers. Let us take a look at List Event Receiver in this recipe. In this recipe, whenever a new list is created on the site, we need to log an audit entry into another list.

Getting ready

Create a custom list called EventReceivers using the SharePoint user interface.

How to do it...

1. If you have closed your Visual Studio IDE, launch it now as an administrator and create a new Event Receiver project. Name the project ListEventReceiver.

2. By default, Visual Studio selects the SharePoint site available on the machine. Select Deploy as Sandboxed Solution and click Next to proceed to the next step in the wizard.

3. In here, make sure to select List Events from the drop down for What type of event receiver do you want? Check A List is being added in the Handle the following events list box.

4. Click on Finish and Visual Studio adds in the necessary files and opens up the EventReceiver1.cs. This is the code file in which you are going to write your custom event handler.

5. Now add the code necessary to write an entry into the EventReceivers custom list that we created in the Getting Ready section of this recipe. Your code should be as follows:

   using System;
   using System.Security.Permissions;
   using Microsoft.SharePoint;
   using Microsoft.SharePoint.Security;
   using Microsoft.SharePoint.Utilities;
   using Microsoft.SharePoint.Workflow;
   namespace ListEventReceiver.EventReceiver1
   {
       /// <summary>
       /// List Events
       /// </summary>
       public class EventReceiver1 : SPListEventReceiver
       {
          /// <summary>
          /// A list is being added.
          /// </summary>
          public override void ListAdding(SPListEventProperties properties)
          {
             AddMessage(ref properties, "Adding List");
   base.ListAdding(properties);
          }
   
          private void AddMessage(ref SPListEventProperties properties, string sMessage)
          {
              using (SPWeb web = properties.Web as SPWeb)
              {
                  SPList list = web.Lists["EventReceivers"];
                  SPListItem li = list.AddItem();
                  li["Title"] = properties.ListTitle;
                  li["Message"] = sMessage + " - " + properties.ListId;
                  li.Update();
                  li = null;
                  list = null;
              }
   
          }
   
       }
   }

6. Build and execute the solution by pressing F5 or by navigating to menu Debug | Start Debugging. This should bring up the default browser with the local site that you provided in the project creation wizard.

7. Add a new list of custom list templates and call it TestList. You should be able to see an entry in the EventReceivers List as shown below. Your List ID, and the GUID may be different from what is shown in the following screenshot:

   

How it works...

It works in the same way as the List Item Event Receivers works, except for the fact that the List Event Receivers have a base class of SPListEventReceiver. You can compare the elements.xml file from the List Item Event Receiver (created in our first recipe) with this one. The only difference you will see is that it does not have a ListTemplateId attribute. This makes sense as this is applied to all lists in the site. The Event Receiver in this case is acting at the site level. That means, whenever you create a new list in the site where this is deployed, this event gets triggered.

There's more...

If you have noticed, base.ItemAdding method is called first in some cases and called last in some other. Where should we call this method and how do we know if it should be called first or last? The rule of thumb for calling this method is very simple. If you are going to cancel the event then call it in the end. If not, call it in the beginning. So for synchronous events like ListAdding or ListItemAdding events, where you are doing some data validations and will cancel the events, call it in the end.

See also

• Deploying Event Receivers recipe