Lesson 7: Shared helpers
Several workflows of one application send the same payloads and end with the same steps. Helpers keep those in one place, and the analyzer still checks them.
Payload helpers
/// <summary>Expression helpers shared by several workflows.</summary>
public static class Payloads
{
/// <summary>The customer reference that every customer-service call sends.</summary>
public static WorkflowExpressionDefinition CustomerReference() =>
WorkflowExpr.Obj(WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")));
}
A flow extension
/// <summary>A step sequence several workflows end with: notify the customer, then complete.</summary>
public static class FlowExtensions
{
public static WorkflowFlowBuilder<TStartRequest> NotifyCustomerAndComplete<TStartRequest>(
this WorkflowFlowBuilder<TStartRequest> flow)
where TStartRequest : class
{
return flow
.Call("Notify customer", new HttpAddress("notifications", "/messages"), Payloads.CustomerReference())
.Complete();
}
}
A workflow that uses them
/// <summary>Updates a customer's address and notifies the customer, using the shared helpers.</summary>
public sealed class AddressChangeWorkflow : IDeclarativeWorkflow<AddressChangeRequest>
{
public string WorkflowName => "AddressChange";
public string WorkflowVersion => "1.0.0";
public string DisplayName => "Customer address change";
public IReadOnlyCollection<string> WorkflowRoles { get; } = ["customer-service"];
public WorkflowSpec<AddressChangeRequest> Spec { get; } = WorkflowSpec.For<AddressChangeRequest>()
.InitializeState(
WorkflowExpr.Obj(
WorkflowExpr.Prop("customerId", WorkflowExpr.Path("start.customerId")),
WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("start.newAddress"))))
.StartWith(flow => flow
.Call(
"Update address",
new EndpointAddress("customers", "/addresses"),
WorkflowExpr.Obj(
WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")),
WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("state.newAddress"))))
.NotifyCustomerAndComplete())
.Build();
public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}
Concepts
- The analyzer and its generator walk into helpers of the same project.
- A helper whose parameters end up in the definition (a
stringfor a template or a service name), and an address returned by a helper or built from constants, are reported as WF021: the workflow works, but is left out of the build-time bundle and the publisher compiles it when it starts. - To stay in the bundle, write names and values as literals and addresses in place,
new HttpAddress("notifications", "/messages"), as these helpers do. - A helper in another project of yours that breaks a rule is reported as WF010 at the call (analyzer reference).
The complete code
The lesson’s complete code. It uses the namespace of the tutorials; put the classes in a namespace of yours.
SharedHelpers.cs:
using StellaOps.Workflow.Abstractions;
using StellaOps.Workflow.Contracts;
namespace Examples.Workflow.Tutorials.SharedHelpers;
/// <summary>Expression helpers shared by several workflows.</summary>
public static class Payloads
{
/// <summary>The customer reference that every customer-service call sends.</summary>
public static WorkflowExpressionDefinition CustomerReference() =>
WorkflowExpr.Obj(WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")));
}
/// <summary>A step sequence several workflows end with: notify the customer, then complete.</summary>
public static class FlowExtensions
{
public static WorkflowFlowBuilder<TStartRequest> NotifyCustomerAndComplete<TStartRequest>(
this WorkflowFlowBuilder<TStartRequest> flow)
where TStartRequest : class
{
return flow
.Call("Notify customer", new HttpAddress("notifications", "/messages"), Payloads.CustomerReference())
.Complete();
}
}
public sealed class AddressChangeRequest
{
[WorkflowBusinessId]
public string CustomerId { get; set; } = string.Empty;
public string NewAddress { get; set; } = string.Empty;
}
/// <summary>Updates a customer's address and notifies the customer, using the shared helpers.</summary>
public sealed class AddressChangeWorkflow : IDeclarativeWorkflow<AddressChangeRequest>
{
public string WorkflowName => "AddressChange";
public string WorkflowVersion => "1.0.0";
public string DisplayName => "Customer address change";
public IReadOnlyCollection<string> WorkflowRoles { get; } = ["customer-service"];
public WorkflowSpec<AddressChangeRequest> Spec { get; } = WorkflowSpec.For<AddressChangeRequest>()
.InitializeState(
WorkflowExpr.Obj(
WorkflowExpr.Prop("customerId", WorkflowExpr.Path("start.customerId")),
WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("start.newAddress"))))
.StartWith(flow => flow
.Call(
"Update address",
new EndpointAddress("customers", "/addresses"),
WorkflowExpr.Obj(
WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")),
WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("state.newAddress"))))
.NotifyCustomerAndComplete())
.Build();
public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}
The canonical form
The C# compiles to a canonical JSON definition, the document the engine validates, stores and renders. Write it to a file with the export helper of lesson 9:
CanonicalExport.WriteCanonicalJson(new AddressChangeWorkflow(), "address-change.definition.json");
Next: Lesson 8: Expressions.
