MassTransit

dotnet add package Elsa.MassTransit

MassTransit is an open-source distributed application framework for .NET that provides a consistent abstraction on top of the supported message transports.

It enables .NET developers to model messages as C# types, which can then be sent & received. To receive messages, one would typically write a Consumer.

When using the MassTransit module with Elsa, there is an additional method of sending & handling messages; through workflow activities.

Messages as Activities

Elsa makes it easy to send and receive messages that are modeled as .NET type. All you need to do is define your type and then register it with the MassTransit feature.

When a message type is registered, two new activities will be automatically available for use:

Publish {activity type}
{activity type}

The first activity will publish your message. The second activity acts as a trigger and will start or resume your workflow when a message of this type is received.

Setup

The following example highlights creating and registering a fictive message type called OrderCreated.

OrderCreated.cs:

public record OrderCreated(string Id, string ProductId, int Quantity);

Program.cs

            services.AddElsa(elsa =>
            {
                // Enable and configure MassTransit
                elsa.AddMassTransit(massTransit =>
                {
                    // Register our message type.
                    massTransit.AddMessageType<OrderCreated>();
                };
            });
        

            services.AddElsa(elsa =>
            {
                // Enable and configure MassTransit
                elsa.AddMassTransit(massTransit =>
                {
                   // Configure MT to use the RabbitMQ broker.
                    massTransit.UseRabbitMq("amqp://guest:guest@localhost:5672", rabbit => rabbit.ConfigureServiceBus = bus =>
                    {
                        bus.PrefetchCount = 4;
                        bus.Durable = true;
                        bus.AutoDelete = false;
                        bus.ConcurrentMessageLimit = 32;
                        // etc.
                    });

                    // Register our message type.
                    massTransit.AddMessageType<OrderCreated>();
                };
            });
        

            services.AddElsa(elsa =>
            {
                // Enable and configure MassTransit
                elsa.AddMassTransit(massTransit =>
                {
                   // Configure MT to use the Azure Service Bus broker.
                    massTransit.UseAzureServiceBus(azureServiceBusConnectionString, serviceBusFeature => serviceBusFeature.ConfigureServiceBus = bus =>
                    {
                        bus.PrefetchCount = 4;
                        bus.LockDuration = TimeSpan.FromMinutes(5);
                        bus.MaxConcurrentCalls = 32;
                        bus.MaxDeliveryCount = 8;
                        // etc.
                    });

                    // Register our message type.
                    massTransit.AddMessageType<OrderCreated>();
                };
            });
        

With the above setup, our workflow server will now add two activities that allow you to send and receive messages of type `OrderCreated`:

Order Created
Publish Order Created

The Order Created activity acts as a trigger, which means that it will automatically start the workflow it is a part of when a message is received of this type. The Publish Order Created activity will publish a message of this type.

Tutorial

In this tutorial, we will set up an Elsa Server and configure it to use the MassTransit module and see it in action.

Prerequisites

For this tutorial, you will need:

To create a new ASP.NET project by following the Elsa Server setup guide, or the Elsa Server and Studio setup guide.
In case you only set up an Elsa Server, you will also need to run an Elsa Studio application. For this tutorial, it suffices to run an existing Elsa Studio image. For this tutorial
A connection string to a running RabbitMQ instance.
A connection string to an Azure Service Bus resource.

Then return here.

Project Setup

Using MassTransit

Create a new ASP.NET project by following the Elsa Server setup guide.
Install the following package:
dotnet add package Elsa.MassTransit
Install the following packages:
dotnet add package Elsa.MassTransit dotnet add package Elsa.MassTransit.RabbitMQ
Install the following packages:
dotnet add package Elsa.MassTransit dotnet add package Elsa.MassTransit.AzureServiceBus
Add the following code to Program.cs:
elsa.UseMassTransit(massTransit => { massTransit.AddMessageType<OrderCompleted>(); massTransit.AddMessageType<OrderCreated>(); });
elsa.UseMassTransit(massTransit => { massTransit.UseAzureServiceBus(azureServiceBusConnectionString); massTransit.AddMessageType<OrderCompleted>(); massTransit.AddMessageType<OrderCreated>(); });
elsa.UseMassTransit(massTransit => { massTransit.UseRabbitMq(rabbitMqConnectionString); massTransit.AddMessageType<OrderCompleted>(); massTransit.AddMessageType<OrderCreated>(); });
Create a new folder called Messages and add a new record type called `OrderCreated`: Messages/OrderCreated.cs
namespace ElsaServer.Messages; public record OrderCreated(string Id, string CustomerId, string Product, int Quantity, decimal Total);
In order to be able to instantiate objects of our `OrderCreated` message type using JavaScript and C# expressions, we need to update the following lines in `Program.cs`:
// Enable JavaScript workflow expressions. elsa.UseJavaScript(); // Enable C# workflow expressions. elsa.UseCSharp();
// Enable JavaScript workflow expressions. elsa.UseJavaScript(javaScript => { javaScript.AllowClrAccess = true; javaScript.ConfigureEngine(options => { options.RegisterType<OrderCreated>(); }); }); // Enable C# workflow expressions. elsa.UseCSharp(csharp => { csharp.Assemblies.Add(typeof(OrderCreated).Assembly); csharp.Namespaces.Add(typeof(OrderCreated).Namespace!); });

Run Project

Run your brand new Elsa Server application on port `5001`:
dotnet run --urls "https://localhost:5001"
Run Elsa Studio on port 6001 and connect it to Elsa Server:
docker pull elsaworkflows/elsa-studio-v3:latest docker run -t -i -e ASPNETCORE_ENVIRONMENT=Development -e ELSASERVER__URL=https://localhost:5001/elsa/api -p 6001:8080 elsaworkflows/elsa-studio-v3:latest
Navigate to http://localhost:6001 and login with the default credentials:
username: admin password: password

Create Workflows

Create a new workflow called Publisher and add the Publish Order Created activity to the canvas.
Configure the activity's Message input with the following C# expression:
return new OrderCreated("order-1", "Bob", "Apple", 15, 7.5m);
Publish the workflow.
Create another workflow called Receiver and add the Order Created activity to the canvas.
Create a variable called `OrderCreatedMessage` and set its Type to `OrderCreated`.
Select the Order Created activity and select it Outputs tab. Update the Results field by selecting the variable we just created.
Add the WriteLine activity to the canvas and connect the Order Created activity to it. For the Text input, supply the following C# expression:
return $"Order created with ID {Variables.OrderCreatedMessage.Id}";
Publish the workflow.

Run Workflows

Go back to the Publisher workflow and select the Play button to run the workflow.
Navigate to the Workflow Instances page and notice that two new instances have been created: one for the Publisher workflow and another one for the Receiver workflow. The Receiver workflow instance exists because it was triggered by the Order Created activity.

Last modified: 19 February 2024