As many of you know, event receivers are a great way to hook into various SharePoint events. These can apply to Feature events such as FeatureActivated, List events such as FieldAdded, and many others. The most common set of receivers used, however, are part of SPItemEventReceiver which let you wire your code up to a number of events that can occur to items on a list or library.
When working with events, you’ll quickly find that before (synchronous) and after (asynchronous) events exist, and the method suffix such as “ing” (e.g. ItemAdding) and “ed” (e.g. ItemAdded) will tell you whether it gets invoked before or after the actual change is made. Basic stuff.
And, as you get deeper, you’ll even find that you can extract the before and after state of the change. For example, you can hook into the ItemUpdating event for a document library and prevent a user from changing a certain column. The code might look like this:
public override void ItemUpdating(SPItemEventProperties properties)
{
if (properties.BeforeProperties["column"] != properties.AfterProperties["column"])
{
properties.Cancel = true;
properties.ErrorMessage = "This column cannot be changed";
}
}
For a document library, this works just fine. However, you should know that the BeforeProperties hash table is not populated for items on a list. As is worded in the SDK: “For documents, Before and After properties are guaranteed for post events, such as ItemUpdated, but Before properties are not available for post events on list items”
When they say “not available for post events on list items”, do they mean after events (like ItemUpdated, ItemDeleted, etc)? The wording is curious here, so I thought I’d take some time to test each combination of common events such as Add, Update and Delete. These were done across a custom list and then a document library. Each test involved adding a new item, editing the item and then deleting the item. Here are the results for a list:
| List |
BeforeProperties |
AfterProperties |
properties.ListItem |
| ItemAdding |
No value |
New value |
Null |
| ItemAdded |
No value |
New value |
New value |
| ItemUpdating |
No value |
Changed value |
Original value |
| ItemUpdated |
No value |
Changed value |
Changed value |
| ItemDeleting |
No value |
No value |
Original value |
| ItemDeleted |
No value |
No value |
Null |
No value means that column value in the hash table was not available.
New value means that the correct value for the column was available.
Changed value means that the correct updated value was available.
Original value means that the correct original value was available.
Here is the same test against a document library:
| Library |
BeforeProperties |
AfterProperties |
properties.ListItem |
| ItemAdding |
No value |
No value |
Null |
| ItemAdded |
No value |
No value |
New value |
| ItemUpdating |
Original value |
Changed value |
Original value |
| ItemUpdated |
Original value |
Changed value |
Changed value |
| ItemDeleting |
No value |
No value |
Original value |
| ItemDeleted |
No value |
No value |
Null |
Properties.ListItem refers the the current value for the list item at that point in the event. Null means that the item is not available. My analysis yields the following results:
- Not surprisingly, we get null values for for ItemAdding (before item is added) and ItemDeleted (after item is deleted). This was proven by Ishai Sagi some time ago.
- As correctly documented in the SDK, item events for lists do not expose BeforeProperties.
- ItemAdding and ItemAdded correctly report the value in the AfterProperties for an list item, but not a library item. This is curious.
- We have no visibility on the previous states during the ItemDeleted event. Once it’s deleted, it’s clearly gone.
So, if we go back to our original problem listed above. How can we prevent a user from changing a certain column for an item in a list event? From the list table, you can see if we hook into the ItemUpdating event, we can compare the current item’s value (properties.ListItem) to the AfterProperties value. The code would look like this:
if (properties.ListItem["column"] != properties.AfterProperties["column"])
{
properties.Cancel = true;
properties.ErrorMessage = "This column cannot be changed";
}
I hope this post gives you a better idea of how before and after events work for both lists and libraries. Your comments and feedback are always welcomed.
Technorati: SharePoint