How to configure a handler runtime


The handler runtime configuration provides a configuration model which makes it possible to run the three message processing runtimes together or in isolation.

Scoping a runtime

To configure a new runtime, you first need to create a new instance of HandlerRuntimeConfiguration.

This class can be found in the MessageHandler.Runtime.Configuration nuget package, but usually you don't need to explicitly install it as other packages already depend on it.

PM> Install-Package MessageHandler.Runtime.Configuration

You can optionally pass in an instance of IServiceCollection to the constructor. Do this in case you want to share dependencies from the dotnet runtime that you are hosting in, e.g. in an hosting environment, with the runtime.

 var runtimeConfiguration = new HandlerRuntimeConfiguration(services);

Configuring the runtime

It's always advised to set a name for your handler, otherwise a name will be assigned based on the friendly name of the running app domain.


And, in case you are scaling your handler out, provide a unique instance id, potentially derived from your environment. If not specified, the handler name will be used instead.


After this initial setup, you should pass the handler runtime configuration instance to the respective processing runtime configurations for further extension.

Register the runtime in the hosting environment

When hosting MessageHandler in a framework where you don't control the startup point, such as, you should register the runtime to automatically start along with the framework.


This action will first register hosted services to start up the processing infrastructure and then create a ServiceProvider instance from the ServiceCollection.

In case you passed in a ServiceCollection ensure that it is fully configured before calling this method, as any additions beyond this point will not be present in the internal ServiceProvider instances of the handler runtime.

Manually starting the runtime

Not all frameworks start up automatically though, for instance a console application.

In such cases, you can create and start the runtime manually.

var runtime = HandlerRuntime.Create(runtimeConfiguration);
await runtime.Start();

Sign up to our newsletter to get notified about new content and releases

You can unsubscribe at any time by clicking the link in the footer of your emails. I use Mailchimp as my marketing platform. By clicking subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp's privacy practices here.