elsa-core/doc/wiki/extension-guide.md

Extension Guide

Elsa is designed to be extended by adding modules, features, activities, stores, expression providers, API endpoints, and runtime integration points. This page collects the common patterns.

Add A Code-First Feature

1. Create Features/MyFeature.cs.
2. Derive from FeatureBase.
3. Add [DependsOn] attributes for required features.
4. Use Configure() for feature graph changes and activity scanning.
5. Use ConfigureHostedServices() for hosted services.
6. Use Apply() for service registration.
7. Add Extensions/ModuleExtensions.cs with UseMyFeature.
8. Add unit tests that prove core services register.

Use HttpFeature, SchedulingFeature, and StructuredLogsFeature as examples.

Add A Shell Feature

Shell features live in ShellFeatures and implement CShells interfaces such as IShellFeature, IFastEndpointsShellFeature, or IMiddlewareShellFeature.

Use shell features when modular server/package configuration needs to activate the feature without code-first AddElsa calls.

Examples:

• Elsa.Shells.Api/ShellFeatures/ShellsApiFeature.cs
• Elsa.Diagnostics.StructuredLogs/ShellFeatures/StructuredLogsFeature.cs
• EF Core provider shell features

Add An Activity

1. Put the activity in the owning module's Activities folder.
2. Derive from Activity, Activity<T>, CodeActivity, or a module-specific base.
3. Use Input<T> and Output<T> for designer/runtime compatibility.
4. Register the activity with workflow management.
5. Add descriptor/UI hint handlers if the designer needs dynamic options.
6. Test activity-only behavior with ActivityTestFixture.
7. Add integration/component tests for bookmarks, triggers, persistence, or transport behavior.

Good examples:

• SetVariable
• HttpEndpoint
• RunCSharp

Add An Expression Provider

Expression providers need:

• evaluator contract and implementation
• expression descriptor provider
• optional activity for running scripts
• optional UI hint handler
• option type
• feature registration
• tests for evaluator behavior and workflow integration

Compare existing language modules:

• JavaScriptFeature
• CSharpFeature
• PythonFeature
• LiquidFeature

Add An API Endpoint

1. Create a folder under the relevant Endpoints category.
2. Add Endpoint.cs and local Models.cs when needed.
3. Derive from the Elsa endpoint base used by nearby endpoints.
4. Configure verb, route, permissions, and summary.
5. Inject service contracts, not concrete internals when possible.
6. Add endpoint tests or component coverage if behavior is important.
7. Update client models if the endpoint is part of the public client surface.

Use route prefixing from UseWorkflowsApi; endpoint routes should usually be written without /elsa/api.

Add A Store Or Persistence Provider

For an EF Core-backed store:

1. Add the entity/configuration/store to the shared EF Core module slice if it is a common Elsa domain.
2. Add provider-specific migrations if persisted shape changes.
3. Replace the owning feature's store factory in the persistence feature.
4. Add tests for query/filter/order behavior.
5. Add provider integration tests for migrations or SQL differences.

For diagnostics structured log relational providers:

1. Reference the relational structured-log package.
2. Implement IRelationalStructuredLogConnectionFactory.
3. Implement IRelationalStructuredLogDialect.
4. Implement IStructuredLogSchemaMigrator.
5. Register those services and call AddRelationalStructuredLogPersistence.

See SqliteStructuredLogsModuleExtensions.

Add A Runtime Ingress Source

External event sources should participate in graceful shutdown. Add an ingress source when a module feeds work into the runtime from outside the engine.

Steps:

1. Implement the runtime IIngressSource contract in the owning module.
2. Register it as a singleton service.
3. Make dispatch loops or middleware honor paused state.
4. Add tests for pause/resume/drain behavior.

Existing first-party examples are HTTP and Scheduling ingress source registrations.

Add A Workflow Provider

Workflow providers bring definitions from external storage. Existing examples:

• Elsa.WorkflowProviders.BlobStorage
• Elsa.WorkflowProviders.BlobStorage.ElsaScript

Keep provider modules focused on discovery/materialization and leave execution to runtime.

Add Documentation

Update docs when changing:

• public APIs
• options/configuration
• endpoint routes
• persistence schema or provider setup
• runtime behavior
• security/authorization behavior
• developer workflows

Good locations:

• module README
• relevant spec quickstart
• this wiki
• ADR for architectural decisions

Design Rules Of Thumb

• Keep core provider-neutral.
• Use feature configuration instead of direct cross-module service replacement.
• Add dependencies explicitly with [DependsOn].
• Prefer contracts at module boundaries.
• Put tests near the module whose behavior changed.
• Avoid adding shared abstractions until at least two real modules need them.