Skip to content

Cratis Chronicle captures with C# builders

The Cratis Chronicle .NET capture builder describes how changes in external data become events. Use it to keep the source, identity key, and event append rules together in a C# class.

Implement ICapturer and define the capture in Define(ICaptureBuilder builder). CaptureBuilder.Build() produces a CaptureDefinition, but implementing ICapturer does not register or start a capture. IEventStore does not expose capture management; the kernel’s management contract accepts Capture Declaration Language (CDL) text.

The example below describes a status-change event for invoices keyed by id. The $context.occurred assignment illustrates syntax the API-polling engine does not accept; executable API declarations must use supported item paths or literals.

public class InvoiceCapture : ICapturer
{
public void Define(ICaptureBuilder builder) => builder
.FromApi("InvoicingApi", _ => _
.OnRoute("/invoices")
.PollEvery("10m"))
.Key("id")
.Append<InvoiceStatusChanged>(_ => _
.WhenPropertyChanges("status")
.Set(e => e.Status, "$.status")
.Set(e => e.ChangedAt, "$context.occurred"));
}

Choose a source with one of these methods:

  • FromApi(api, configure?)
  • FromWebhook(path, configure?)
  • FromMessageTopic(topic)

The engine runs API-polling captures. It rejects webhook and message-topic sources during validation, so those builder methods describe sources the engine cannot run.

For an API source, configure the route and polling interval:

  • OnRoute(route)
  • PollEvery(interval)

Register the HTTP External Service before using its name in FromApi(api, ...). In the example, InvoicingApi identifies that service, /invoices selects the data to poll, and 10m sets a ten-minute polling interval. The service holds the base URL and authentication. If you omit the route, the capture uses the base URL directly. See the .NET registration example to configure the service.

Webhook sources take no options today. The former WithBasicAuth, WithBearerToken and WithOAuth methods are obsolete. Webhook sources are not read, and the capture contract carries only the declaration text, so the kernel never received, stored or enforced these settings. Remove those calls. Authentication is never part of the capture declaration text, so that secrets and tokens do not live in capture definitions.

Use Key(propertyPath) to identify the same item across observations. With Key("id"), Chronicle compares an invoice’s current payload with the previous payload for that invoice, rather than comparing unrelated invoices.

The builder can describe Map(...) operations on root, nested, or children scopes. The engine rejects map operations during validation; these methods describe authoring syntax only:

  • Rename(source, target)
  • Template(target, template)
  • Translate(target, source, entries => ...)
  • Split(source, separator, targets...)

Use Append<TEvent>(...) to name the event to emit, choose a condition, and assign its fields. In the invoice example, a change to status selects InvoiceStatusChanged, and $.status supplies its Status value.

Condition methods:

  • WhenPropertyChanges(property)
  • WhenAnyOf(properties...)
  • WhenAllOf(properties...)
  • WhenTransition(property, from, to)
  • WhenAdded()
  • WhenRemoved()
  • WhenExpression(expression)

The engine rejects expression-based conditions declared with WhenExpression(expression). The other condition methods describe property changes, value transitions, additions, and removals.

Assign fields with Set(targetPropertyExpression, sourceExpression). API captures support item-property paths such as $.status and literal values, not $context or template expressions. See the CDL execution limits before choosing expressions.

  • Nested(objectPath, configure) for nested object rules
  • Children(collectionPath, identifiedBy, configure) for child collection rules

Both builders expose local Map(...) and Append<TEvent>(...) blocks. The engine rejects nested and children scopes during validation; only root-level append rules execute.

The [Capture("guid")] attribute carries an explicit capture ID on an ICapturer type. The attribute does not register the capture.