Event management and event providers

This document describes the event management system and event providers in EPiServer. The events system provides a mechanism for distributing events between IIS applications and EPiServer websites in a load balanced environment. The event system in EPiServer is provider-based, and you can either use the built-in event provider or develop your own customized one.

Event providers

Built-in event provider

The built-in event provider in EPiServer is based on Microsoft Windows Communication Foundation (WCF) and requires some manual WCF configuration steps to enable. It uses either UDP broadcasting or TCP, which requires detailed knowledge about ports, firewalls and endpoints. To use elastic scaling (adding and removing servers on demand) with the WCF provider, you need to use UPD broadcasting since TCP requires you to manually configure all endpoints.

Elastic scaling in cloud environments does not work well using the built-in WCF provider since you may not have detailed control over networks and servers. An event provider optimized for Microsoft Azure is available on NuGet. The event provider for Azure uses Service Bus for distributing events and requires no configuration of servers or network details. An event provider for Amazon Web Services is also available on NuGet.

Customized event provider

Another alternative is to develop your own custom event provider, adapted for your hosting environment.

Configuring an event provider

For the built-in WCF-based event provider it is enough to define WCF end-points as described in the section Configuring events over WCF, since it is the default provider.

To use another custom event provider, add the provider configuration to the event element in the episerver.framework section of the web.config. For example:

<episerver.framework>
    <event defaultProvider="msmq">
        <providers>
            <add name="msmq" type="MSMQEventProvider.MSMQEventProvider, MSMQEventProvider" />
        </providers>
    </event>
</episerver.framework>

See Using the Event API for details.

Event system process flow

The logical setup and execution of event system actions are described below.

1. When an EPiServer CMS website starts, it will do the following:
   1. Create a secret if one does not already exist in the site database.
   2. Initialize the Event Broker responsible for sending and recieving event messages remotely.
   3. Initialize each Event Provider that has been configured.
   4. Enable the Event system when the initialization process has completed (for example when CMS or Commerce has completed initialization).
2. Code in a site obtains an Event object instance and subscribes to the Raised and optionally to the Missed event.
3. Code in a site obtains an Event object instance and calls the Raise method (the Cache Manager could raise a cache changed event for example).
4. The Event object instance fires the Raised event to notify the local subscribers.
5. The Event object instance informs the Event Broker about the event.
6. The Event Broker sends the event to all the other sites on the same server and other servers in the network using the configured Event Provider. In addition to the event information a cryptographic HMAC block is also sent in the message to allow the receiver to test the authenticity of the event (this functionality can be disabled by the provider if a secure channel is already present).
7. The Event Broker on another instance (either an IIS site on the local server or remote server) receives the sent message and does the following:
   1. Makes sure the message was sent from another instance sharing the same database. If no match is found, the action will be logged, the message dropped and no further action taken.
   2. Verifies the HMAC using the event data and the secret stored in the database (unless the provider disabled validation).
   3. If the verification fails, the action will be logged, the message dropped and no further action taken.
   4. Obtains the Event object instance for the event and calls the Raise method to notify the local subscribers.

Testing the event system

Examples of EPiServer CMS functionality that use the events system are Cache updates. To test cache events, edit a page on one EPiServer CMS site and ensure the change is reflected on the 2nd load balanced EPiServer CMS website. See below for exact details:

1. On EPiServer CMS #1, navigate to a page in the example website.
2. On EPiServer CMS #2, enter Edit mode and navigate to the same page as in step 1.
3. On EPiServer CMS #2, add/edit/delete some text on the page and the click Publish.
4. On EPiServer CMS #1, refresh the page and ensure it reflects the new information saved in step 3.

See also

• Deployment
• Configuring events over WCF