Table of Contents

Entity event rule

What are entity event rules ?

Entity event rules are pieces of code executed when events are triggered on the server application.

Warning

Due to identification difficulties with EF Core, entities with only an Image property set to null do not appear in modified elements.

Writing the code of an event rule

In this article, we will focus on the available events and properties.

You can either write the C# code directly in the Neos Studio code editor or in Visual Studio (after the event rule has been saved once). See more about adding / editing server code.

Example with a Saving event rule :

/// <inheritdoc/>
public Task OnSavingAsync(ISavingRuleArguments<IOrderView> args)
{
    foreach (IOrderView order in args.CreatedAndModifiedItems)
    {
        order.Total = order.OrderDetails.Sum((od) => od.Subtotal);
    }

    return Task.CompletedTask;
}
Note

If the event rule call an asynchronous method, the good practice is to use the overload of the OnSavingAsync method that accepts a CancellationToken parameter and propagate this cancellation token.

The args parameter content is detailed in the next section.

Accessing the original value

In a Saving event rule, you can compare the modified entity with its original (pre-modification) state:

  • args.GetOriginal(item) : returns the original state of the item, typed as the rule's entity type (no cast needed).
  • args.GetRepository(item) : returns the concrete repository as the non-generic IRepository. Use its non-generic members directly (GetOriginal, GetAll, GetKeyValues). Typed operations such as GetState or Find live on IRepository<TEntity>, but a rule declared on an abstract/base entity resolves the concrete subtype's repository — casting it to IRepository<TBase> would fail at runtime, so the non-generic API is the safe surface here.

This works even when the event rule is declared on an abstract base entity. A rule declared on a base entity runs for every derived entity, and GetOriginal / GetRepository resolve the correct concrete repository for each item at runtime.

Note

The typed args.GetOriginal(item) shortcut is available on Saving rules (and validation rules through GetOriginal()), where it returns the pre-modification state.

It is intentionally not offered on Saved rules: once the triggering save is persisted, the tracked original values have been reset to the just-persisted state, so the pre-modification original is no longer available. args.GetRepository(item) stays available on Saved rules for regular repository operations; calling GetOriginal on it there reflects the post-persistence baseline (the state at the start of the Saved phase, and backend-dependent) — an advanced use to reach for only when you understand that semantics. To compare against the pre-modification state from a Saved rule, capture it in the Saving rule and carry it through the rule context.

Example with a Saving event rule declared on an abstract LockableEntity (which exposes a bool IsLocked property) :

/// <inheritdoc/>
public Task OnSavingAsync(ISavingRuleArguments<LockableEntity> args, CancellationToken cancellationToken)
{
    foreach (LockableEntity item in args.ModifiedItems)
    {
        LockableEntity original = args.GetOriginal(item);
        if (original.IsLocked)
        {
            throw new BusinessException("Locked items cannot be modified.");
        }
    }

    return Task.CompletedTask;
}

Event rule properties

  • Event rule : type of the event rule
  • Business assembly : business assembly that will contain the C# class representing the event rule. The chosen assembly must belong to the event rule module or one of its children.
  • Show Application layer assemblies : the source element of your code is in the Domain layer. This layer is the core of your business and we recommend placing all the code associated with the elements of this layer there. Placing your code in an Application layer assembly is only justified if your code uses elements from this layer (entity views, data objects, server methods, notifications...). See more about domain and application layers.

Available rules

Several rules are available in an entity event view. This section is an exhaustive list of these rules.

Context

The context is shared between the Saving and Saved events. A value added in the context during the Saving event is available at the Saved event level.

The context is shared between the entity event EntityViewRetrieving and the entity view event Retrieving. A value added to the context during the entity event EntityViewRetrieving is available at the entity view event Retrieving.

The context is also shared between the entity Saving / Saved events and the entity view Saving / Saved events. The order of triggering events is as follows:

  1. EntityView.Saving event
  2. Entity.Saving event
  3. Entity.Saved event
  4. EntityView.Saved event

Monitoring event rules execution

The execution of event rules can be tracked in the Backend monitoring screen of the manager.