Thinking out aloud - Dave Hunter's SharePoint Blog

A while ago I wrote the article Delving into SharePoint 2007 Event Receivers its a popular article but lacks something, which I believe are some real world examples people can see in action and relate to ... Introducing the next series of articles SharePoint Event Receivers By Example.

One of the out of the box libraries in SharePoint is the contact list.  This holds contact information such as First Name, Last Name, Telephone, Email etc.  The email column is a standard single line of text site column.  I wanted to validate the email address users whilst creating contacts. 

Event Receivers have before or after events.  You would use a before event to capture users creating contacts and updating contacts.  You need to use the SPItemEventReceiver class and utilise the ItemAdding and ItemUpdating events.

To check the values that the user enters during a before event you should check the properties.AfterProperties.  This is a collection of name value pairs.  You can retrieve a value using the internal name of a column (not the display name).  For example:

string emailMessage = properties.AfterProperties["Email"].ToString();

You can cancel the event using:

properties.Status = SPEventReceiverStatus.CancelWithError;
properties.Cancel = true;
properties.ErrorMessage = "Please enter a valid email address";

The Status is set to cancel and display an error.  properties.Cancel determines if the event should be cancelled.  The default is false but once you set it to true it will cancel the event when the current execution ends.  An error message is set using the ErrorMessage property.  The following is displayed to the user:

Here's the code:

#region namespaces
using System;
using System.Collections.Generic;
using System.Text;
using System.Text.RegularExpressions;

using Microsoft.SharePoint;
using System.Collections;
#endregion

namespace Dhunter.SharePoint.EventReceivers
{
    public class ValidEmailEventReceiver : SPItemEventReceiver
    {
        #region events

        /// <summary>
        /// Test the email expression when the user creates a new item
        /// </summary>
        /// <param name="properties"></param>
        public override void ItemAdding(SPItemEventProperties properties)
        {
            base.ItemAdding(properties);

            // only perform if we have an Email column
            if (properties.AfterProperties["Email"] != null)
            {
                // test to see if the email is valid
                if (!IsValidEmailAddress(properties.AfterProperties["Email"].ToString()))
                {
                    // email validation failed, so display an error
                    properties.Status = SPEventReceiverStatus.CancelWithError;
                    properties.Cancel = true;
                    properties.ErrorMessage = "Please enter a valid email address";
                    
                }
            }

            
        }

        /// <summary>
        /// Test the email expression when the user updates an existing item
        /// </summary>
        /// <param name="properties"></param>
        public override void ItemUpdating(SPItemEventProperties properties)
        {
            base.ItemUpdating(properties);

            // only perform if we have an Email column
            if (properties.AfterProperties["Email"] != null)
            {
                // test to see if the email is valid
                if (!IsValidEmailAddress(properties.AfterProperties["Email"].ToString()))
                {
                    // email validation failed, so display an error
                    properties.Status = SPEventReceiverStatus.CancelWithError;
                    properties.Cancel = true;
                    properties.ErrorMessage = "Please enter a valid email address";
                    
                }
            }

            
        }

        #endregion

        #region private methods

        /// <summary>
        /// Test the email address to see if it meets the validation
        /// </summary>
        /// <param name="email"></param>
        /// <returns></returns>
        private bool IsValidEmailAddress(string email)
        {
            bool isValid = false;

            // regular expression to test the email
            string emailRegEx = @"^(([^<>()[\]\\.,;:\s@\""]+(\.[^<>()[\]\\.,;:\s@\""]+)*)|
(\"".+\""))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$";

            // run the test
            Regex reStrict = new Regex(emailRegEx);
            isValid = reStrict.IsMatch(email);
            
            // flag to indicate if its valid
            return isValid;
        }

        #endregion

    }
}

My findings during creating this event receiver

• BeforeProperties are only available in Event Receivers bound to a document library.  For more information please see http://msdn.microsoft.com/en-us/library/aa979520.aspx
• BeforeProperties and AfterProperties contain a collection of DictionaryEntry's you should use the internal name of the column.  I tried this using the email address.  The internal name can be found by editing a site column and looking in the url, for example: /_layouts/fldedit.aspx?field=EMail.  I tried using properties.AfterProperties["EMail"] always returned null.  After looking into the collection the field was actually called "Email".  You can check these names using:

foreach (DictionaryEntry de in properties.AfterProperties)
{
  string key = de.Key.ToString();
  string value = de.Value.ToString();
}

• Cancel doesn't stop the ItemAdding or ItemUpdating unless base.ItemAdding(properties); is called at the top of the event.
• I used the SharePoint Tips Utility Pack http://www.codeplex.com/spstipsUtilityPack to bind the event receiver to the list.  The tool has a event handler management section that allows you to quickly register your event receiver to a list.

Happy coding.