Elsa Web

In this topic, we'll demonstrate how to integrate Elsa Workflows into an ASP.NET Core application. This setup is ideal for executing long-running workflows in the background, supporting various activities like Timer, Cron, Event, and others that necessitate a background service.

This application type does not expose the necessary API endpoints for Elsa Studio to connect to. For that, please refer to Elsa Server.

Setup

Create the Project
Create a new empty ASP.NET app using the following command:
dotnet new web -n "ElsaWeb" -f net8.0
Add Packages
Navigate to your project's root directory and install the Elsa package:
cd ElsaWeb dotnet add package Elsa
Modify Program.cs
Open Program.cs in your project and replace its contents with the code provided below.
Program.cs
using Elsa.Extensions; var builder = WebApplication.CreateBuilder(args); // Add services to the container. builder.Services.AddControllers(); builder.Services.AddElsa(); var app = builder.Build(); // Configure the HTTP request pipeline. app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();
This configuration allows your application to use Elsa services for running workflows.

Our application is now ready to execute workflows. Let's look at a few examples to see how we might integrate with the engine

Demo 1

In this demo, we will add a custom controller that, when invoked, will execute a workflow that we create on the fly.

Add Controller
Add a new controller named HelloWorldController:
Controllers/HelloWorldController.cs
using Elsa.Http; using Elsa.Workflows.Activities; using Elsa.Workflows.Contracts; using Elsa.Workflows.Memory; using Microsoft.AspNetCore.Mvc; namespace ElsaWeb.Controllers; [ApiController] [Route("hello-world")] public class HelloWorldController(IWorkflowRunner workflowRunner) : ControllerBase { [HttpGet] public async Task Get([FromQuery] string message = "Hello ASP.NET world!") { var messageVariable = new Variable<string>(message); var workflow = new Sequence { Variables = { messageVariable }, Activities = { new WriteLine("This workflow runs a sequence of steps."), new WriteHttpResponse { Content = new(message) }, new WriteLine(messageVariable), new WriteLine("This workflow is now complete.") } }; await workflowRunner.RunAsync(workflow); } }
Restart the application and navigate to https://localhost:5001/hello-world
The response should read: Hello ASP.NET world!

Demo 2

In addition to programmatically invoking workflows, you can also create workflows that themselves are routable via HTTP requests. To enable this, we need to add the WorkflowsMiddleware ASP.NET middleware component to the request pipeline.

Let's see how this works.

In Program.cs, add the following line before app.Run();:
app.UseWorkflows();
The complete file should look like this:
using Elsa.Extensions; var builder = WebApplication.CreateBuilder(args); // Add services to the container. builder.Services.AddControllers(); builder.Services.AddElsa(); var app = builder.Build(); // Configure the HTTP request pipeline. app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.UseWorkflows(); app.Run();
Create a new directory called Workflows and add a new file to it called HttpHelloWorld.cs with the following.
Workflows/HttpHelloWorld.cs
using Elsa.Http; using Elsa.Workflows; using Elsa.Workflows.Activities; using Elsa.Workflows.Contracts; namespace ElsaWeb.Workflows; public class HttpHelloWorld : WorkflowBase { protected override void Build(IWorkflowBuilder builder) { builder.Root = new Sequence { Activities = { new HttpEndpoint { Path = new("/hello-world"), CanStartWorkflow = true }, new WriteHttpResponse { Content = new("Hello world of HTTP workflows!") } } }; } }
In order for the workflow runtime to be able to trigger workflows automatically, you need to set the activity's CanStartWorkflow property to true. This is easy to forget, so whenever you are wondering why a workflow isn't running even though you are sure you triggered it, the first thing to check is to see if this property is set correctly.
Update Program.cs to register this workflow:
using ElsaWeb.Workflows; // Add this line. builder.Services.AddElsa(elsa => { elsa.AddWorkflow<HttpHelloWorld>(); });
The complete file should look like this:
Program.cs
using Elsa.Extensions; using ElsaWeb.Workflows; var builder = WebApplication.CreateBuilder(args); // Add services to the container. builder.Services.AddControllers(); builder.Services.AddElsa(elsa => { elsa.AddWorkflow<HttpHelloWorld>(); elsa.UseHttp(); }); var app = builder.Build(); // Configure the HTTP request pipeline. app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.UseWorkflows(); app.Run();
Restart the app and visit https://localhost:5001/workflows/hello-world. You should see the following message: Hello world of HTTP workflows!
Notice that the URL path is /workflows/hello-world and not /hello-world as we defined in the workflow definition. This is because the WorkflowsMiddleware component is configured to use /workflows as the prefix path by default. You can change this by passing a different prefix path to the UseHttp method. For example, if you want to use /api, you can do so as follows:
elsa.UseHttp(http => http.ConfigureHttpOptions = options => options.BasePath = "/api");
Let's update the workflow to support a message variable that is received from the query string, just like we did in the controller demo.
Update HttpHelloWorld.cs with the following code:
HttpHelloWorld.cs:
using Elsa.Http; using Elsa.Workflows; using Elsa.Workflows.Activities; using Elsa.Workflows.Contracts; namespace ElsaWeb.Workflows; public class HttpHelloWorld : WorkflowBase { protected override void Build(IWorkflowBuilder builder) { var queryStringsVariable = builder.WithVariable<IDictionary<string, object>>(); var messageVariable = builder.WithVariable<string>(); builder.Root = new Sequence { Activities = { new HttpEndpoint { Path = new("/hello-world"), CanStartWorkflow = true, QueryStringData = new(queryStringsVariable) }, new SetVariable { Variable = messageVariable, Value = new(context => { var queryStrings = queryStringsVariable.Get(context)!; var message = queryStrings.TryGetValue("message", out var messageValue) ? messageValue.ToString() : "Hello world of HTTP workflows!"; return message; }) }, new WriteHttpResponse { Content = new(messageVariable) } } }; } }
Restart the app and visit https://localhost:5001/workflows/hello-world?message=Hello. You should now see the following message: Hello

Summary

We've covered how to set up Elsa Workflows in an ASP.NET Core application, demonstrating various methods of workflow execution and integration. This approach allows for versatile and efficient handling of background processes and activities within your ASP.NET applications.

The complete code and additional resources are available here.

Last modified: 21 January 2024