Umbraco Commerce
CMSCloudHeartcoreDXP
15.latest
15.latest
  • Umbraco Commerce Documentation
  • Release Notes
    • v15.1.0-Rc
    • v15.0.0-Rc
  • Commerce Products
    • Commerce Packages
    • Commerce Payment Providers
    • Commerce Shipping Providers
  • Getting Started
    • Requirements
    • Installation
    • Licensing
    • Configuration
    • User Interface
  • Upgrading
    • Upgrading Umbraco Commerce
    • Version Specific Upgrade Notes
    • Migrate from Vendr to Umbraco Commerce
      • Migrate Umbraco Commerce Checkout
      • Migrate custom Payment Providers
  • Tutorials
    • Build a Store in Umbraco using Umbraco Commerce
      • Installation
      • Creating a Store
        • Configuring your Store
      • Creating your first Product
      • Implementing a Shopping Cart
        • Using the Umbraco.Commerce.Cart Drop-in Shopping Cart
        • Creating a Custom Shopping Cart
      • Implementing a Checkout Flow
        • Using the Umbraco.Commerce.Checkout Drop-in Checkout Flow
        • Creating a Custom Checkout Flow
      • Configuring Store Access Permissions
  • How-To Guides
    • Overview
    • Configure SQLite support
    • Use an Alternative Database for Umbraco Commerce Tables
    • Customizing Templates
    • Configuring Cart Cleanup
    • Limit Order Line Quantity
    • Implementing Product Bundles
    • Implementing Member Based Pricing
    • Implementing Dynamically Priced Products
    • Implementing Personalized Products
    • Implementing a Currency Switcher
    • Building a Members Portal
    • Order Number Customization
    • Create an Order via Code
  • Key Concepts
    • Get to know the main features
    • Base Currency
    • Calculators
    • Currency Exchange Rate Service Provider
    • Dependency Injection
    • Discount Rules / Rewards
    • Events
      • List of validation events
      • List of notification events
    • Fluent API
    • Order Calculation State
    • Payment Forms
    • Payment Providers
    • Pipelines
    • Price/Amount Adjustments
    • Price Freezing
    • Product Adapters
    • Product Bundles
    • Product Variants
      • Complex Variants
    • Properties
    • ReadOnly and Writable Entities
    • Sales Tax Providers
    • Search Specifications
    • Settings Objects
    • Shipping Package Factories
    • Shipping Providers
    • Shipping Range/Rate Providers
    • Tax Sources
    • UI Extensions
      • Analytics Widgets
      • Entity Quick Actions
      • Order Line Actions
      • Order Properties
      • Order Collection Properties
      • Order Line Properties
      • Store Menu Items
    • Umbraco Properties
    • Unit of Work
    • Umbraco Commerce Builder
    • Webhooks
  • Reference
    • Stores
    • Shipping
      • Fixed Rate Shipping
      • Dynamic Rate Shipping
      • Realtime Rate Shipping
    • Payments
      • Configure Refunds
      • Issue Refunds
    • Taxes
      • Fixed Tax Rates
      • Calculated Tax Rates
    • Storefront API
      • Endpoints
        • Order
        • Checkout
        • Product
        • Customer
        • Store
        • Currency
        • Country
        • Payment method
        • Shipping method
        • Content
    • Management API
    • Go behind the scenes
    • Telemetry
Powered by GitBook
On this page
  • Validation events
  • Example: Validation event handler
  • Registering a Validation event handler
  • Notification events
  • Example: Notification event handler
  • Registering a Notification event handler

Was this helpful?

Edit on GitHub
Export as PDF
  1. Key Concepts

Events

Listening for changes within Umbraco Commerce.

PreviousDiscount Rules / RewardsNextList of validation events

Last updated 5 months ago

Was this helpful?

Much like the standard events in .NET, Umbraco Commerce has an events system to notify you when certain things happen within the application. However, Umbraco Commerce differs slightly in the types of events that are fired and how you register your event handlers.

Events in Umbraco Commerce are registered via the interface, rather than via static event delegates. This has a number of advantages, such as being able to control the order of when event handlers are fired. It also allows us to inject dependencies into the event handlers making it a much more decoupled approach to eventing.

In Umbraco Commerce, there are two main types of events you can create handlers for. Both are explained in detail below.

Validation events

Validation events are events that fire immediately before a change is about to be made to an entity. These events allow you to inject your own logic to decide whether an action should be possible or not. We already have a number of validation handlers built in to maintain the consistency of your data. Validation events allow you to extend this behavior with your own rules.

A full list of validation events can be found in the .

Example: Validation event handler

An example of a Validation event handler would look something like this:

public class MyOrderProductAddValidationHandler : ValidationEventHandlerBase<ValidateOrderProductAdd>
{
    public override void Validate(ValidateOrderProductAdd evt)
    {
        if (evt.ProductReference == "MyProductRef" && evt.Quantity % 10 != 0)
            evt.Fail("This product can only be purchased in increments of 10");
    }
}

All Validation event handlers inherit from a base class ValidationEventHandlerBase<TEvent> where TEvent is the Type of the event the handler is for. They then have a Validate method that accepts an instance of the event type, and inside which you can perform your custom logic. If the event fails the validation logic, you can call evt.Fail("Your message here") to block the related action from happening and have a ValidationException be thrown. This can then be captured in the front end to display a friendly error message.

Registering a Validation event handler

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register my event handlers
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandler<MyOrderProductAddValidationHandler>();

        // Return the builder to continue the chain
        return builder;
    }
}

You can control the order of when Validation event handlers run, before or after another Validation event handler. This is done by registering them via the RegisterHandlerBefore<THandler>() or RegisterHandlerAfter<THandler>() methods respectively.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register MyOrderProductAddValidationHandler to execute before the SomeOtherValidationHandler handler
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandlerBefore<SomeOtherValidationHandler, MyOrderProductAddValidationHandler>();

        // Register MyOrderProductAddValidationHandler to execute after the SomeOtherValidationHandler handler
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandlerAfter<SomeOtherValidationHandler, MyOrderProductAddValidationHandler>();

        // Return the builder to continue the chain
        return builder;
    }
}

Notification events

Notification events are events that fire, often immediately before or after an action is executed. It provides you the ability to run custom logic to react to that action occurring. This is useful for scenarios such as sending emails when an Order is finalized or allowing you to synchronize stock updates with an external system.

Notification events won't allow you to change the behavior of how Umbraco Commerce runs. They provide you with an effective means of reacting when changes occur.

Example: Notification event handler

An example of a Notification event handler would look something like this:

public class MyOrderFinalizedHandler : NotificationEventHandlerBase<OrderFinalizedNotification>
{
    public override void Handle(OrderFinalizedNotification evt)
    {
        // Implement your custom logic here
    }
}

All Notification event handlers inherit from a base class NotificationEventHandlerBase<TEvent> where TEvent is the Type of the event the handler is for. They then have a Handle method that accepts an instance of the event type, and inside which you can perform your custom logic.

Registering a Notification event handler

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register my event handlers
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandler<MyOrderFinalizedHandler>();

        // Return the builder to continue the chain
        return builder;
    }
}

You can also control the order of when Notification event handlers run by registering them via the RegisterHandlerBefore<THandler>() or RegisterHandlerAfter<THandler>() methods respectively.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register MyOrderFinalizedHandler to execute before the SomeOtherNotificationHandler handler
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandlerBefore<SomeOtherNotificationHandler, MyOrderFinalizedHandler>();

        // Register MyOrderFinalizedHandler to execute after the SomeOtherNotificationHandler handler
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandlerAfter<SomeOtherNotificationHandler, MyOrderFinalizedHandler>();

        // Return the builder to continue the chain
        return builder;
    }
}

Validation event handlers are interface using the WithValidationEvent<TEvent>() builder extension method. This is done to identify the event you want to handle and then call the RegisterHandler<THandler>() method to register your handler(s) for that event.

A full list of notification events can be found in the .

Notification event handlers are interface using the WithNotificationEvent<TEvent>() builder extension method. This is used to identify the event you want to handle and then call the RegisterHandler<THandler>() method to register your handler(s) for that event.

IUmbracoCommerceBuilder
List of validation events
registered via the IUmbracoCommerceBuilder
List of notification events
registered via the IUmbracoCommerceBuilder