Use the Event 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. When Optimizely Content Management System (CMS) starts, the event system has no predefined events. 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 an event object instance if one was not already created for the event ID. Otherwise, it returns the existing one. It is important to note that the GUID event ID is only important to users of the event system because it lets different pieces of code identify the same event. The event system does not know what these events are or who uses them.

The Event class returned from the Get method has the following .NET events that the 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 on tracking the sequence numbers allocated to remote events and detecting after a predetermined amount of time that one or more are missing.

The event system does not guarantee that events are processed sequentially, 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: raise and receive 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);
}

Use custom event arguments

In the previous example, a string is sent as an event argument, the data for the event. You can also send custom objects as event arguments as long as you can serialize 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 does not scale.

Example of event argument:

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