For developers: Subscribe to Manager / DataProvider events

For example, this is how you subscribe to the  PageManager.Executing event in the Global.asax file of your web application.

NOTE: If you do not have a Global.asax file added to your project, in the context menu of your project, click Add » New Item… » Visual C# » Web » Global Application Class.

When working with an Executing/Executed event you get access to several useful objects in your event handler:

• The CommandName

  The ExecutingEventArgs collection gives you access to the CommandName object. The CommandName is the name of the provider virtual method that is currently called and is made available via interception. Since the provider Executing and Executed events fire multiple times for different provider methods, checking the CommandName enables you to identify which exact method you are plugging your logic into from the event handler. In most common scenarios you check whether the command name is FlushTransaction or CommitTransaction. These are two methods used by the Sitefinity CMS API to persist data in the database.

  • FlushTransaction
    The FlushTransaction method indicates that the provider is about to commit data to the database. You can access this data to read some properties or modify the data prior to it being committed.
  • CommitTransaction
    The CommitTransaction method indicates data is being committed in the database. Usually the method gets called after FlushTransaction, but there are cases where CommitTransaction is called directly, without going through FlushTransaction first. If you subscribe to an Executing event and get a CommitTransaction command name, this means you’re plugging in to a point prior to the commit logic being executed. If you subscribe to the Executed event, and get a CommitTransaction command name, this means data has been committed.

    NOTE: While it makes sense to check whether the args.CommandName is FlushTransaction or CommitTransaction when hooking up to the Executing event handler, it makes sense to check only for CommitTransaction when hooking up to the Executed event handler. This is because FlushTransaction in Executed event handler will give access to data that is no longer relevant.

• The Provider

  You can access the instance of the DataProvider for the Manager that raised the event. This is done by casting the event handler sender object as the respective provider type. DataProviders follow a standard naming convention, for example if you are subscribing to NewsManager.Executing event, you cast the sender as NewsDataProvider.

• The DirtyItems collection

  The dirtyItems collection represents the data that is written by an uncommitted transaction. You can access it by calling the GetDirtyItems() method of the provider instance. Inside the dirtyItems collection you will find the items that Sitefinity CMS will persist. You can read or modify the properties of the dirtyItems in your logic.

  Keep in mind the items inside the dirtyItems collection are of type ProviderDirtyItem. You need to cast them to the proper item type to access their properties. For example, the dirtyItems inside a NewsManager.Executing event handler must be cast to a NewsItem type to work with the actual properties of the news item.

  NOTE: If you are working with a manager that is responsible for content items (for example news, events, blogs) you need to keep in mind that Sitefinity CMS implements lifecycle for the content items. This means the system keeps a Master, Live and Temp copies of an item. Since the provider Executing and Executed events fire after the Sitefinity Lifecycle has taken care of synchronizing the item properties you must checking the dirty item lifecycle status to know which copy of the item you are updating. For more information about content lifecycle in Sitefinity CMS see: For developers: Content lifecycle.

• The items TransactionActionType

  The TransactionActionType indicates the status of a dirty item in a transaction. It is available when intercepting the FushTransaction and CommitTransaction methods. The TransactionActionType can be:

  • New – a new item is being created
  • Updated – an existing item is updated
  • Deleted – an item is being deleted
• ExecutionStateData
  ExecutionStateData is a mechanism for tracking the changes happening to an item while it goes through the DataProvider logic. It can be useful in scenarios where you want to track the item changes, for example for advanced audit trail implementation or sync with third party systems. ExecutionStateData enables you to persist item properties from the Executing event handler, and access them in the Executed event handler.

The following sample demonstrates hooking up to the Executing and Executed events of NewsManager and working with the above described objects: