Handling Events Share Point 2010

Most software applications are event driven—that is, the order in which code executes is determined by a sequence of events. Events can be raised by many different sources, such as a user clicking a button or the contents of a file changing. To support an event-driven software development approach, the SharePoint platform also raises many different events that can be programmatically handled.

A few different levels of event handling apply to applications developed using the SharePoint platform. One of the most obvious is the events that are raised and handled by the underlying ASP.NET framework. Some of these events, also known as post-back events, are raised when users interact with controls on a web page. Along with these user-initiated events are system-generated events such as the PreInit, Load, and Render events that form part of the ASP.NET page processing lifecycle. Handling events such as these are run-of-themill tasks for developers familiar with the ASP.NET platform, so I won’t spend much time covering them other than to acknowledge that they are an important part of any SharePoint application design.
In addition to the event handling model provided by the ASP.NET framework and the various user controls that SharePoint provides that directly use this mode, SharePoint also provides an additional level of event handling that is tied more directly to the operations in the SharePoint platform.

Event Hosts
As you’ve seen in many of the examples in this book, a few core objects provide most of the functionality that we commonly use when developing SharePoint applications: SPSite, SPWeb, SPList, and SPContentType. Each of these objects is capable of hosting events and as such is known as an event host. To compare this to the Windows forms event model, an example of an event host might be a button on a form.

Event Receivers
Events raised by any of the event host classes are handled by event receivers, which work in a similar fashion to an event handler in traditional ASP.NET programming. Each event receiver is implemented in a class that’s derived from a base class that defines methods for each event that can occur. The primary difference between SharePoint events and traditional ASP.NET events is that the event receiver is decoupled from the event host—that is, the event receiver exists in an assembly that’s completely separate from the event host and the connection between the two is dynamically made via configuration as opposed to being established within code. A direct comparison with the Windows forms event model isn’t possible, since Windows forms events make use of delegates, which allow events to be handled in any class. Each SharePoint event receiver is a class in its own right; in a sense, each method defined within an event receiver serves the same purpose as a delegate in the Windows forms model.

Receiver Base Classes
As mentioned, each event receiver must be based on an appropriate receiver base class. The base class dictates which events can be handled by the event receiver as well as which event hosts can call the event receiver. Naturally, not all event hosts are capable of raising the same events, so it makes sense that not all event hosts support each receiver base class. Within the SharePoint platform are four receiver base classes that are derived from SPEventReceiverBase. Event receivers can be derived from these classes to handle events from the SPSite, SPWeb, SPList, and SPContentType event hosts.

SPItemEventReceiver
This base class defines methods that can be used to trap events that are raised by items. As you’ve seen, an item can be either a document or a list item. This base class defines methods that can be used to trap events that are raised by lists.As you’ve seen, an SPList object can represent either a list or a document library. For a complete list of the events that can be handled using this base class.

SPWebEventReceiver
This base class defines methods that can be used to trap events that are raised by web sites. Each web site is represented by a SPWeb object.The SPWorkflowEventReceiver class is a new addition in SharePoint 2010. In previous versions, it was not possible to create event receivers to handle workflow events such as Starting or Completed. This presented a problem when further validation of processing was required before a workflow could be started. With SharePoint 2010, four new workflow events have been added: Workflow Completed, Workflow Postponed, Workflow Started, and Workflow Starting.

Synchronous and Asynchronous Events
If we look at a few of the events that can be handled by the SPItemEventReceiver class, we see that usually two events occur for each action—for example, ItemAdded and ItemAdding. This duplicity can exist because these events occur at different points in the process of adding an item. If a new SPItem is created and added via the object model, when the Update method is called on the appropriate object, the ItemAdding event is fired. This event runs in the same thread as the code that added the item; as a result, this type of event is known as a synchronous event. After the Update method has been called and any synchronous event receivers have been called, processing returns to the code that added the item. However, behind the scenes, the SharePoint Object Model commits the changes to the content database. After this has completed, the ItemAdded event is fired and runs in a separate thread; it is known as an asynchronous event handler.
The main reason for handling a synchronous event as opposed to an asynchronous event is to perform some validation before the results of an action are committed to the content database. For example, before an item is added to a list, some managed code can be executed to check that all required fields are populated. If this check fails, the action can be canceled and return an error message to the user. With an asynchronous event handler, any problems would need to be resolved by rolling back already committed changes, and since the event occurs in a separate thread, no mechanism is in place to alert the user of any problem.In previous versions of SharePoint, events that were fired after changes were committed to the content database and were always asynchronous. With SharePoint 2010, it’s now possible to dictate that these events should be fired either synchronously or asynchronously. As we saw earlier, one way to add an event receiver to a particular event host was to create a new object of type SPEventReceiverDefinition. One of the properties of the SPEventReceiverDefinition object, Synchronization, allows us to specify which mode should be used when firing the event.

Security Context
When event receivers are called, generally speaking, they run in the security context of the user who initiated the changes that caused the event to be fired. If the events have been raised as the result of changes made by a workflow process, the events run in the context of the user who either started the workflow or made the change that caused the workflow to be started automatically. This behavior differs from previous versions of SharePoint, in which events that were initiated by workflow changes always executed under the SharePointSystem security context.

NOTESharePointSystem is a virtual account that’s mapped to a physical account by the SharePoint platform when a web application is created. Each web application can potentially have a different application pool account. So that developers and the SharePoint platform itself have a single, well-defined way to refer to this account, regardless of the underlying physical account that’s used, “SharePointSystem” is used as a pseudonym throughout the platform. Since all system processes are started by the SharePointSystem account, this account has full control over all aspects of a web application. In some situations, the default security context may not be appropriate. If an event receivers executing under the security context of a particular user and a higher level of system privilege is required, using SPSecurity. RunWithElevated Privileges allows code to be executed as SharePointSystem:

Although this works well for elevating system privileges, it doesn’t do much to help us when the receiver is running as SharePointSystem and we want to revert to the security context of the user who originated the event. For example, in this code snippet, because the Updatemethod is being called with a section of code that is being run with elevated privileges, any ItemUpdated or ItemUpdatingevent receivers that are defined will run under the SharePointSystem security context.
To get around this problem, SharePoint 2010 adds a new property that allows us to pick up the security token of the originating user and make use of it to switch security context manually, as this example shows:

Event Properties
Four different receiver base classes can be used to create event receivers for the event hosts described earlier. Since each of these hosts represents a different object within the SharePoint platform, the properties that are available to each event receiver are also different. Each receiver base class makes use of a specific event properties class that is derived fromSPEventPropertiesBase to communicate with the respective event receiver. These base classes are SPItemEventProperties, SPListEventProperties, SPWebEventProperties,andSPWorkflowEventProperties.

SPItemEventProperties

The SPItemEventProperties class is used to communicate details of the item on which an event was raised to the appropriate event receiver. Two important properties of the class that warrant further explanation are AfterProperties and BeforeProperties. Earlier we looked at synchronous events and asynchronous events, and we discovered that in SharePoint 2010, it is possible to specify that events that would normally occur asynchronously can instead be called synchronously. For the sake of clarity, let’s consider events that are synchronous by default as before events, and events that are asynchronous by default as after events. When a before event is raised, AfterProperties contains the item properties that will be stored in the content database if the event is processed successfully. BeforeProperties contains the item properties that are currently stored in the content database. When an after event is raised, either synchronously or asynchronously, BeforeProperties contains the values that were previously stored in the content database, whereas AfterProperties contains the values that are currently stored in the content database. CAUTION BeforeProperties works only for document items. For all other items, BeforeProperties will always be null.

SPListEventProperties

The SPListEventProperties class is used to communicate the details of the list or field on which an event was raised tothe appropriate event receiver. SPWebEventProperties The SPWebEventProperties class is used to communicate the details of the web or site on which an event was raised to the appropriate event receiver. The SPWebEventProperties class contains both a ServerRelativeUrl and a NewServerRelativeUrl property. When the event being handled is a before event (as defined above), the ServerRelativeUrl property will contain the current URL of a site or web, and the NewServerRelativeUrl will contain the URL that the site or web will have if the event is processed successfully.

When the event being handled is an after event, the ServerRelativeUrl property will contain the previous URL of the site or web, whereas the NewServerRelativeUrl will contain the current URL.If the event is a Deleteor Deleting event, the NewServerRelativeUrl will throw an Invalid Operation Exception.

SPWorkflowEventProperties

The SPWorkflowEventProperties class is used to communicate the details of the workflow instance on which an event was raised to the appropriate event receiver.

Shared Properties

The base SPEventPropertiesBase class defines a few interesting properties that are inherited by all event properties classes. First, the Status property allows code within an event receiver to specify the outcome of an event. Possible outcomes are defined by the SPEventReceiverStatus enumeration and include the following:

  • Continue All is well; carry on as normal.
  • CancelNoError Cancel the request but don’t present a notification to the caller.
  • CancelWithError Cancel the request and raise an error message as specified by the ErrorMessage property.
  • CancelWithRedirectUrl Cancel the request and redirect the caller to the URL specified in the RedirectUrl property.

NOTE :CancelWithRedirectUrl doesn’t work when events are raised by clients using Microsoft Office applications, since these applications do not provide a web browser. Effectively, the redirect is ignored.
Second, the EventUserToken and OriginatingUserToken properties, as discussed earlier, can be used to switch between security contexts.
Packaging and Deployment Events
Along with the event hosts that we looked at earlier, the SharePoint platform also includes an additional host, the SPFeatureDefinition class, which is used for packaging and deployment purposes. Events in the packaging and deployment framework are hooked up a bit differently, and more in-depth coverage of this subject will be provided in Packaging and deployment model. For now, it’s enough to know that these events exist and also make use of event receivers in a similar manner.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Share Point 2010 Topics