The List Item Event Receivers

The Training Management application includes two list item event receivers; they are named ItemAdding and ItemUpdating. When managers create a course, the ItemAdding event receiver first validates the information before the course is added to the list. When you create a content type and select Add with Event Receiver in the Content Type Settings dialog box, Visual Studio automatically generates a file named nameItemEventReceiver.cs and a file named nameListEventReceiver.cs.

The ItemAdding and ItemUpdating event receivers are defined in the TrainingCourseItemEventReceiver class. This class must inherit from the SPItemEventReceiver class to access the event receivers.

The SPItemEventProperties class is provided by the SharePoint platform. It contains the following properties that are used by the list item event receivers:

• ErrorMesssage. Set this property to a text string that explains the validation failure.
• Cancel. Set this property to true if you want to fail the validation; if you do this, SharePoint produces an error message and does not add the item to the list.
• AfterProperties. Use this property to retrieve the values you want to validate.

For more information, see SPItemEventProperties on MSDN.

The following is the code for the business rules.

public override void ItemAdding(SPItemEventProperties properties)
{
   bool isValid = true;
   StringBuilder errorMessage = new StringBuilder();

   string title = string.Empty;
   string code = string.Empty;
   DateTime enrollmentDate = DateTime.MinValue;
   DateTime startDate = DateTime.MinValue;
   DateTime endDate = DateTime.MinValue;
   float cost = 0;

   // A Web is required to retrieve Field names for iterating through the 
   // ListItem collection in the SPItemEventProperties and for
   // retrieving existing items in the TrainingCourses list.
   using (SPWeb web = properties.OpenWeb())
   {
       ITrainingCourseRepository repository = ServiceLocator.GetInstance().Get<ITrainingCourseRepository>();
       Initalize(properties.AfterProperties, repository, web, out title, out code, out enrollmentDate, out startDate, out endDate, out cost);

       if (this.ValidateCourseCodeExists(repository, code, errorMessage, web))
       {
           isValid = false;
       }
   }

   isValid = isValid & this.ValidateCourseCode(code, errorMessage);
   isValid = isValid & this.ValidateEnrollmentDate(enrollmentDate, errorMessage);
   isValid = isValid & this.ValidateStartDate(enrollmentDate, startDate, errorMessage);
   isValid = isValid & this.ValidateEndDate(startDate, endDate, errorMessage);
   isValid = isValid & this.ValidateCourseCost(cost, errorMessage);

   // If any of the rules fail, set an error message and set the
   // Cancel property to true to instruct SharePoint to redirect to 
   // a standard error page.
   if (!isValid)
   {
       properties.ErrorMessage = errorMessage.ToString();
       properties.Cancel = true;
   }
}           

If the course information violates any of these rules, the user receives an error message that explains the problem. This message is displayed on the standard SharePoint error page.

The ItemUpdating list item event receiver is invoked when a user edits information about a course that already exists. The only difference between it and the ItemAdding event receiver is that it does not validate the enrollment date.

If there is an unhandled exception, SharePoint catches it and displays a standard error page with a generic message. If you catch exceptions in your own code, you can create your own error messages and cancel the operation to the list item.

Home page on MSDN | Community site