Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

The List Item Event Receivers

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The Training Management application includes two list item event receivers 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 on 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 
   // ListItem collection in the SPItemEventProperties as well as 
   // retrieveing existing items in the TrainingCourses list.
   using (SPWeb web = properties.OpenWeb())
   {
       ITrainingCourseRepository repository = ServiceLocator.GetInstance().Get<ITrainingCourseRepository>();
       this.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.

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Show:
© 2015 Microsoft