Skip to content

3.0.0
Compare
Choose a tag to compare
@thedmi thedmi released this 07 Jul 08:26
· 27 commits to master since this release
3.0.0
5739ba6
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

The 3.0 release brings support for synchronous methods when using AwaitEnqueueing synchronization mode, and switches the default failure mode to Abort to align with .NET background service behavior.

Capsule.Core

Changed

  • The synchronizer interface ICapsuleSynchronizer as well as its default implementation have been changed to be synchronous (return type void instead of Task) for EnqueueReturn(), the synchronizer method that is used for the AwaitEnqueuing synchronization mode. Breaking change.
  • CapsuleOptions.FailureMode defaults now to CapsuleFailureMode.Abort. This is a change in behavior and thus a breaking change.
  • The DefaultInvocationLoopFactory takes a ILoggerFactory instead of a logger now. This allows using the right logger type in the invocation loop. Breaking. Provide the logger factory instead of the logger.
  • The obsolete DefaultSynchronizerFactory constructor overload without ILoggerFactory parameter has removed. Breaking. Use the overload with ILoggerFactory parameter.

Capsule.Generator

Changed

  • The generator has been updated to render methods with AwaitEnqueueing as synchronous or asynchronous interface/implementation. Exact generation depends on various factors, refer to the docs for details. This generator release is incompatible with Capsule.Core 1.x and 2.x, so this is a breaking change.

Capsule.Testing

Changed

  • The testing library provides a fake implementation of ICapsuleSynchronizer. This has been updated to reflect the interface changes in Capsule.Core 3.0. Breaking change.

Migration Guide

This section outlines what needs to be done to migrate a codebase from Capsule v2 to v3. Many usages will be compatible and not require additional changes. The two exceptions to this are described below.

Synchronous AwaitEnqueueing

This breaking change affects codebases that use Synchronization = CapsuleSynchronizationMode.AwaitEnqueueing on a Capsule that doesn't directly implement the Capsule interface (i.e. where the interface is only implemented by the generated hull, but not the Capsule implementation itself).

If this is the case for you, the following migrate your codebase to make it v3 compatible:

  • Make interface methods synchronous where you get build errors because the hull doesn't implement all interface members
  • In Capsule clients, don't await interface methods where they don't return a task anymore

Both issues will be flagged by the compiler when you try to build the existing codebase with v3. If no build errors are reported, your codebase is not affected by sync/async breaking changes.

Failure Mode

Starting with version 3.0, the default failure mode is now Abort. This affects your setup if you're using AddCapsuleHost() without specifying the failure mode.

There are two ways to update your codebase if you're affected by this change:

  • Explicitly specify FailureMode = CapsuleFailureMode.Continue to retain the v2 behavior (not recommended).
  • Review and update your capsule implementations to ensure all expected exceptions are caught.

Removed Factory Constructors

If you're registering Capsule with AddCapsuleHost(), this breaking change doesn't affect your setup.

One constructor in each of DefaultInvocationLoopFactory and DefaultSynchronizerFactory were removed. In their place, a constructor taking an ILoggerFactory has been added. Review the constructor calls and update them accordingly.

Assets 2
Loading