4.0.0

This release drops support for .NET 6, as .NET 6 is now end of life. Users on .NET 6 will probably still be able to use the .NET Standard 2.0 release.

For users that are on a .NET version that is still supported by Microsoft, there aren't any breaking changes in this release.

Capsule.Core

Changed

• .NET 6 TFM removed, .NET 9 TFM added.

Capsule.Generator

No changes, no release. 3.0.0 is the most recent release.

Capsule.Testing

Changed

• .NET 6 TFM removed, .NET 9 TFM added.

3.1.1

Capsule.Core

Fixed

• The Nuget package now contains XML documentation to enable in-IDE documentation.

Capsule.Generator

No changes, no release. 3.0.0 is the most recent release.

Capsule.Testing

Fixed

• The Nuget package now contains XML documentation to enable in-IDE documentation.

3.1.0

Capsule.Core

Added

• ITimerService now exposes a Count property that indicates the number of pending timers.
• ITimerService.StartSingleShot() takes a third parameter string discriminator now. The discriminator is optional. When it is specified, the timer service will cancel existing timers with the same discriminator. This is useful for cases where a timer is often restarted/recreated, but only the most recent timer needs to be kept.

Capsule.Generator

No changes, no release. 3.0.0 is the most recent release.

Capsule.Testing

Added

• The FakeTimerService has been extended to support the new discriminator parameter and Count property as well.

3.0.0

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.

3.0.0-beta02

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.

3.0.0-beta01

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.

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.

2.3.0

Capsule.Core

No changes, no release (2.2.0 is the latest release)

Capsule.Generator

Added

• Code generation now supports the [Capsule] attribute on nested types.

Changed

• Microsoft.CodeAnalysis.CSharp dependencies updated to 4.9.2.

Fixed

• Code generator failures due to user code indicate the error location now. This improves developer experience.

Capsule.Testing

No changes, no release (2.0.0 is the latest release)

2.2.0

Capsule.Core

Added

• The failure mode of invocation loops can now be customized. The default is CapsuleFailureMode.Continue and leads to the same behavior as before. CapsuleFailureMode.Abort can be specified on a newly introduced CapsuleOptions parameter on AddCapsuleHost(). It is recommended to use Abort and catch expected exceptions in capsule implementations.

Capsule.Generator

No changes, no release (1.0.1 is the latest release)

Capsule.Testing

No changes, no release (2.0.0 is the latest release)

2.1.1

Capsule.Core

Fixed

• Timers are now guaranteed to not fire early.

Capsule.Generator

No changes, no release (1.0.1 is the latest release)

Capsule.Testing

No changes, no release (2.0.0 is the latest release)

2.1.0

Capsule.Core

Added

• Timer events "timer enqueued", "timer cancelled" and "timer fired" are now logged with debug log level. TimerService received a new ILogger<TimerService> constructor parameter to facilitate this. The previous constructor is now obsolete and will be removed with the next major release.

Fixed

• Timers now account for the fact that Task.Delay may return up to 1ms early and ensures timers will not fire early.

Capsule.Generator

No changes, no release (1.0.1 is the latest release)

Capsule.Testing

No changes, no release (2.0.0 is the latest release)