4.1. Events and Structural Events

Events and Structural Events

Behaviors receive events by CLR type. For contracts that should be defined by name at configuration time rather than compiled into a CLR event class, Stateflows also supports structural events. Each structural event has a registered name and a set of typed fields. State Machine transitions and Activity accept-event nodes can match these events by name and receive a StructuralEvent.

Define structural events

Register event definitions during Stateflows configuration with AddEvents:

using System.ComponentModel.DataAnnotations;
using Microsoft.Extensions.DependencyInjection;
using Stateflows;
using Stateflows.Common;
using Stateflows.Events;

services.AddStateflows(builder => builder
    .AddEvents(events => events
        .AddEvent("submit-order", e => e
            .AddField("orderId", FieldType.String, f =>
                f.AddValidation(new RequiredAttribute()))
            .AddField("quantity", FieldType.Int32, f =>
                f.AddValidation(new RangeAttribute(1, 10)))
            .AddObjectField("shippingAddress", address => address
                .AddField("city", FieldType.String))
            .AddCollectionField("tags", FieldType.String))
        .AddRequest("order-status", "order-status-result", e => e
            .AddField("orderId", FieldType.String))
        .AddEvent("order-status-result", e => e
            .AddField("status", FieldType.String))));

Event and field names are case-sensitive. Primitive field types are String, Boolean, Int32, Int64, Decimal, Double, Guid, DateTime, DateTimeOffset, TimeSpan, DateOnly, TimeOnly, Binary, and Enum. Enum fields declare allowed string values with AddEnumValues. Fields can also be nested objects or collections of primitive/object values; field and item validation attributes are configured on the field builder.

Create, inspect, and validate

Resolve IEventFactory from dependency injection and create a structural event using its registered name. Set accepts typed values; SetObject and SetObjectCollection create nested values:

var eventFactory = serviceProvider.GetRequiredService<IEventFactory>();
var request = eventFactory.Create("submit-order", e => e
    .Set("orderId", "A-1042")
    .Set("quantity", 2)
    .SetObject("shippingAddress", address => address
        .Set("city", "London"))
    .Set("tags", new[] { "priority", "gift" }));

await behavior.SendAsync(request);

Within a transition or accept-event callback, StructuralEvent exposes Name, Fields, ContainsField, Get<T>(fieldName), TryGet<T>(fieldName, out value), and GetCollection<T>(fieldName). Get<T> throws if a field is missing or has a different runtime type; use TryGet when a field is optional. Nested objects are read as StructuralValue.

The registry normalizes values to their declared schema and validates them before Behavior dispatch. Unknown fields are discarded during normalization. Validation failures are returned in the regular Stateflows event validation result and the event is not processed. Missing fields are not automatically rejected unless the definition includes a suitable validation attribute, such as RequiredAttribute.

Requests and responses

Use AddRequest to declare a structural request and its response contract. The response can be another registered structural event, or a CLR response type via AddRequest<TResponse>.

var result = await behavior.RequestAsync(
    eventFactory.Create("order-status", e => e.Set("orderId", "A-1042")));

var status = result.Response.Get<string>("status");

The responding Behavior calls Respond on the request. For a structural response, the name and fields must satisfy the declared response definition; for a CLR response, the declared CLR response type is enforced.

Use in behavior definitions

Structural event names are used directly by the string overloads of AddTransition and AddAcceptEventAction. Those callbacks receive StructuralEvent, not a generated CLR event class. See Transitions and Accept Event Action Node for complete usage examples.