Using the Event API

This topic describes the Optimizely event management system API. You can use this system to send events in a load-balanced environment.

Event classes and methods

The EPiServer.Events.Clients.IEventRegistry interface is the public API of the Optimizely event system that lets you send and receive site events in a de-coupled manner. The event system does not have any predefined events when Optimizely CMS starts. It is up to the code that wants to send and receive events to register them using the IEventRegistry.Get method. The Get method accepts a GUID event ID, and creates a new event object instance if one was not already created for the event ID. Else, it returns the existing one. It is important to note that the GUID event ID is only important to users of the event system in that it lets different pieces of code identify the same event. The event system has no knowledge of what these events are or who uses them.

The Event class returned from the Get method has the following .NET events that user code can subscribe to:

• The Raised event is fired when some code has called the Raise method of the Event class.
• The Missed event is fired when the event system detects that a remote event (an event received from another site or server) has gone missing. The algorithm for detecting a missing event is based upon tracking the sequence numbers allocated to remote events and detecting after a predetermind amount of time that one or more are missing.

The event system does not guarantee that events are being processed in sequential order one at a time. Code that uses the event system should be thread-safe and cannot rely on the order in which events arrive to the event listener.

Example of raising and receiving events

The following example shows how to set up an event handler for a custom event, including a method for raising a custom event:

//Generate unique id for your event and the raiser
private static readonly Guid RaiserId = new Guid("F080ABD6-9BB0-4DC0-9D95-265472FA1CC6");
private static readonly Guid EventId = new Guid("888B5C89-9B0F-4E67-A3B0-6E660AB9A60F");

public void Initialize(EPiServer.Framework.Initialization.InitializationEngine context)
  {
    //Set up event handler
    var myEvent =  context.Locate.Advanced.GetInstance<IEventRegistry>().Instance.Get(EventId);
    myEvent.Raised += myEvent_Raised;
  }

void myEvent_Raised(object sender, EventNotificationEventArgs e)
  {
     // don't process events locally raised
    if (e.RaiserId != RaiserId)
      {
        //Do something, e.g. invalidate cache
      }
  }

public void RaiseEvent(string message)
  {
    ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId).Raise(RaiserId, message);
    //IEventRegistry can be used as DI and be called like _eventRegistry.Get(EventId).Raise(RaiserId, message);
  }

Using custom event arguments

In the previous example, a string is sent as event argument, the data for the event. You can also send custom objects as event arguments, as long as you can serialize both using data contract serialization and JSON serialization (cloud).

Event arguments should be small and simple classes. For example, the maximum message size in Azure is 256 Kb (but due to system overhead, this limit is usually slightly less than 256 Kb). Sending large amounts of data in event arguments do not scale.

Example of event argument:

[DataContract]
[EventsServiceKnownType]
public class MyEventData
  {
    [DataMember]
    public string Message { get; set; }
    [DataMember]
    public int MyNumber { get; set; }
  }

Related topics

• Deployment

Last updated: Jul 02, 2021