For the complete documentation index, see llms.txt. This page is also available as Markdown.

Feature Switches

How-to · Applies to Brighter V10

We provide a FeatureSwitch Attribute and FeatureSwitchAsync Attribute that you can use on your IHandleRequests<TRequest>.Handle() method, and IHandleRequests<TRequest>.HandleAysnc() method. The FeatureSwitch Attribute and FeatureSwitchAsync Attribute that you have configured will determine whether or not the IHandleRequests<TRequest>.Handle() and IHandleRequests<TRequest>.HandleAsync() will be executed.

Using the Feature Switch Attribute

By adding the FeatureSwitch Attribute or FeatureSwitchAsync Attribute, you instruct the Command Processor to do one of the following:

  • run the handler as normal, this is FeatureSwitchStatus.On.

  • not execute the handler, this is FeatureSwitchStatus.Off.

  • detemine whether to run the handler based on a Feature Switch Registry, creating of which is described later.

In the following example, MyFeatureSwitchedHandler runs when the Feature Switch Registry sets it to FeatureSwitchStatus.On, and is skipped when it sets it to FeatureSwitchStatus.Off. With no registry at all, FeatureSwitchStatus.Config behaves as On. With a registry that has no entry for the handler, its MissingConfigStrategy decides; the FluentConfigRegistryBuilder's default throws a ConfigurationException.

using Paramore.Brighter;
using Paramore.Brighter.FeatureSwitch;
using Paramore.Brighter.FeatureSwitch.Attributes;

public class MyFeatureSwitchedHandler : RequestHandler<MyCommand>
{
    [FeatureSwitch(typeof(MyFeatureSwitchedHandler), FeatureSwitchStatus.Config, step: 1)]
    public override MyCommand Handle (MyCommand command)
    {
        /* Do work */
        return base.Handle(command);
    }
}

In the second example, MyIncompleteHandlerAsync will not be run in the pipeline.

Don't Acknowledge When Switched Off

By default, when a feature switch is Off, the handler is skipped and the message is silently acknowledged and discarded. This is fine when you are using the Command Processor directly, but when consuming messages from an External Bus you may want to hold messages on the channel until the feature is re-enabled, rather than losing them.

The dontAck parameter controls this behavior. When set to true and the feature is off, the attribute throws a DontAckAction instead of silently consuming the message. The message pump returns the message to the channel unacknowledged, and the transport delivers it again: the in-memory transport at once, a broker by its own redelivery rules.

The async variant works the same way:

The dontAck parameter defaults to false to preserve backward compatibility. Set it to true whenever you are consuming from an External Bus and want to preserve messages while a feature is temporarily disabled.

For more on how DontAckAction works and how transports handle unacknowledged messages, see Error Handling.

Building a config for Feature Switches with FluentConfigRegistryBuilder

We provide a FluentConfigRegistryBuilder to build a mapping of request handlers to FeatureSwitchStatus. For each Handler that you wish to feature switch you supply a type and a status using a fluent API. The valid statuses used in the builder are FeatureSwitchStatus.On and FeatureSwitchStatus.Off. This example switches the two handlers declared in the examples above.

Implementing a custom Feature Switch Registry

The FluentConfigRegistryBuilder provides compile time configuration of FeatureSwitch Attributes. If this is not suitable to your needs then you can write you own Feature Switch Registry using the IAmAFeatureSwitchRegistry interface. The two requirements of this interface is a MissingConfigStrategy, and an implementation of StatusOf(Type type) which returns a FeatureSwitchStatus.

The MissingConfigStrategy determines how the Command Processor should behave when a Handler is decorated with a FeatureSwitch Attribute that is set to FeatureSwitchStatus.Config does not exist in the registry.

Your implementation of the StatusOf method is used to determine the FeatureSwitchStatus of the Handler type that is passed in as a parameter. How you store and retrieve these configurations is then up to you.

In the following example there are two Feature Switches configured in appsettings.json, under a FeatureSwitches section keyed by each handler's full type name. We then build a ConfigurationFeatureSwitchRegistry that takes the application's IConfiguration. Its StatusOf method reads the handler's entry and returns its status, falling back to the MissingConfigStrategy when there is none.

Setting Feature Switching Registry

We associate a Feature Switch Registry with a Command Processor by passing it into the constructor of the Command Processor. For convenience, we provide a Commmand Processor Builder that helps you configure new instances of Command Processor.

Last updated

Was this helpful?