Plugin RegisteredEvent

DLaBGenericPluginBase<T>.CreateEvents

Implement this abstract method in your plugin class to be able to specify when your plugin should run, what columns are required, and based on the context, what method of the plugin should be executed.

RegisteredEventBuilder

The RegisteredEventBuilder class is used to define RegisteredEvent(s) the plugin will execute for. Here is an example usage:

protected override IEnumerable<RegisteredEvent> CreateEvents()
{
    return new RegisteredEventBuilder(PipelineStage.PreOperation, MessageType.Create, MessageType.Update)
        .ForEntities<Contact>()
        .WithExecuteAction(OnUserEmailRouterAccessApproved)
        .WithValidator(new RequirementValidator()
            .Updated(new SystemUser { EmailRouterAccessApproval = SystemUser_EmailRouterAccessApproval.Approved }))
        .WithAssertValidator(new RequirementValidator()
            .Contains<Contact>(ContextEntity.CoalesceTargetPreImage, c => new { c.FullName, c.EmailAddress1 }),
                "Name and Email address are required to notify admin of email router access approval!")
        .Build();
}

and here is a line-by-line breakdown of what it means:

---

RegisteredEventBuilder Constructor - This will limit the plugin to run only if the plugin execution context is for the PreOperation stage of a Create or Update message. Any other plugin event will cause the DLaBGenericPluginBase to throw an exception:

new RegisteredEventBuilder(PipelineStage.PreOperation, MessageType.Create, MessageType.Update)

---

ForEntities - This will limit the plugin to run only run if the registered table is Contact. Any other execution of the plugin for a different table will cause the DLaBGenericPluginBase to throw an exception. This is optional, and if no table/entity is defined, the plugin can be run with any table type:

.ForEntities<Contact>()

---

WithExecuteAction - Rather than executing the default ExecuteInternal method of the plugin, the OnUserEmailRouterAccessApproved method will be called instead. This is optional, and if no execute action is defined, the ExecuteInternal method of the plugin will be called:

.WithExecuteAction(OnUserEmailRouterAccessApproved)

This allows for multiple RegisteredEvent's to be registered with different entry points into the plugin, for example having a OnCreate method for creates and OnUpdate method for updates:

return new RegisteredEventBuilder(PipelineStage.PreOperation, MessageType.Create)
        .WithExecuteAction(OnCreate)
    .And(PipelineStage.PreOperation, MessageType.Update)
        .WithExecuteAction(OnUpdate);

---

WithValidator - Defines the validation to be run to determine if the plugin execution should be skipped without error. This is optional, and if no validator is defined, the execute action will always be called. In this example, if the EmailRouterAccessApproval has not been updated to Approved then the plugin execution will be skipped without error:

.WithValidator(new RequirementValidator()
    .Updated(new SystemUser { EmailRouterAccessApproval = SystemUser_EmailRouterAccessApproval.Approved }))

Note: Only one RequirementValidator can be defined per RegisteredEvent.

See the RequirementValidator page for more information on defining a validator.

---

WithAssertValidator - Defines a requirement that if not true, will cause an exception to be thrown. This is optional, and if no assert validator is defined, no exception will be thrown. Assert validators will only be evaluated after the standard validator (if present) has passed validation, In this example, if the Target (coalesced with the pre-image) does not contain a non-null value for fullname and emailaddress an InvalidPluginExecutionException will be thrown with the message "Name and Email address are required to notify admin of email router access approval!":

.WithAssertValidator(new RequirementValidator()
    .Contains<Contact>(ContextEntity.CoalesceTargetPreImage, c => new { c.FullName, c.EmailAddress1 }),
        "Name and Email address are required to notify admin of email router access approval!")

RequirementValidator