[Breaking change]: Umbraco Commerce v15 will become async only

[mattbrailsford]

Description

As of Umbraco Commerce version 15, all C# API's will become asynchronous without any synchronous fallback option.

Version

Umbraco 15

Previous behavior

Previously all C# API's were synchronous and thus blocking by nature.

  // Fluent API example
  order.AddProduct(productRef, 1)
    .SetPaymentMethod(paymentMethodId)
    .SetShippingMethod(shippingMethodId);
  
  // Service method examples
  orderService.SaveOrder(order);
  emailTemplateService.SendEmail(emailTemplateId, order);

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

New behavior

All API's will become asynchronous and thus be suffixed with Async, return a Task<T> result, and accept an optional cancelation token

  // Fluent API example
  await order.AddProductAsync(productRef, 1, token)
    .SetPaymentMethodAsync(paymentMethodId, token)
    .SetShippingMethodAsync(shippingMethodId, token);
  
  // Service method examples
  await orderService.SaveOrderAsync(order, token);
  await emailTemplateService.SendEmailAsync(emailTemplateId, order, token);

  // Notification events
  public class MyNotification : AsyncNotificationEventHandlerBase<OrderFinalizedNotification>
  {
    public override Task HandleAsync(OrderFinalizedNotification evt, CancelationToken cancelationToken)
    {
        // Implement your custom logic here
    }
  }

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

This change is needed for a number of reasons.

1. Some of the core CMS API's that Umbraco Commerce uses have already migrated to async APIs and Umbraco v15 marks their time for removal. As such there is no longer a synchronous alternative for us to use which would require us to either migrate, or use non recommended ways of running the async code synchronously.
2. Async is the defacto in ASP.NET now and so it makes sense to transition to this recommended approach.
3. In previous testing, it was highlighted that synchronous code is a performance bottleneck for Umbraco Commerce under load and so moving to async will bring performance benefits.

The main reason to make this change backwards incompatible is due to the extensive nature of the changes required and the amount of overhead it would bring to maintain both approaches. We feel it better to rip the band aid and make the move as quickly as possible.

Recommended action

For the most part this will mainly require developers to update their codebase to call the new Async versions of the API methods, passing through any cancelation tokens provided, and awaiting their responses.

If any Umbraco Commerce functionality has been wrapped or encapsulated in anyway way, then it will also be necessary to make these API's async also.

Affected APIs

All C# APIs