Workable 1.1.0

Workable

Workable is a .NET work orchestration library for applications that need more than "run this in the background." It turns background jobs, operational tasks, recurring work, and user-triggered actions into first-class work the host can queue, observe, control, and configure.

Most applications eventually grow work that does not fit cleanly inside the request, controller action, message handler, or command that started it. Sending email, refreshing caches, synchronizing data, running maintenance tasks, retrying transient failures, and coordinating long-running operations all need identity, state, cancellation, status, events, and a way to be found later. Workable gives that work a consistent runtime model instead of leaving each feature to invent its own.

Workable is useful when you want feature code to define work near the feature that needs it, while the host application keeps control of execution. Feature assemblies can declare their own work with Workable.Sdk. Libraries that need to use a hosted system can depend on Workable.Abstractions and accept IWorkSystem from the host. The host application owns the actual Workable systems, decides which work belongs in each system, and controls how workers start, retry, recur, respect concurrency, and stay available for inspection.

That split lets teams add work near the feature that needs it without forcing every feature library to know how the application hosts work. At runtime, the host gets a consistent surface for queueing work, awaiting completion, pausing, canceling, reconfiguring workers, and subscribing to work events.

Workable also gives applications a path to expose the same authored work through more than one channel. Direct .NET callers, HTTP endpoints, MCP clients, and realtime SignalR clients can all work against the same catalog while preserving request context, structured outcomes, worker history, and invocation rules.

Why Use Workable?

• Define work once and invoke it through .NET, HTTP, or MCP when those channels are enabled.
• Keep feature libraries independent from the host runtime while still letting them contribute work.
• Queue fire-and-forget work without losing the ability to query, observe, cancel, pause, retry, or purge it.
• Attach runtime behavior such as recurrence, transient retry, idempotency, concurrency, retention, logging, profiling, initialization, and start policy.
• Use structured inputs, outputs, messages, worker snapshots, event payloads, and status summaries instead of ad hoc task tracking.
• Preserve who or what started work through request context and origin metadata for HTTP, MCP, SignalR, and direct .NET calls.

Packages

• Workable.Sdk: contracts and registration helpers for assemblies that author work.
• Workable.Abstractions: contracts for libraries that consume an already-hosted work system.
• Workable: in-process host and runtime for Workable systems.
• Workable.AspNetCore: ASP.NET Core request-context and authorization integration for custom endpoints and hosts.
• Workable.Entra: Microsoft Entra ID bearer-token validation and Workable authorization claim mapping for ASP.NET Core target apps.
• Workable.Views: shared component-view contracts and projections used by HTTP and SignalR adapters.
• Workable.HttpApi: standard HTTP endpoints for queueing, querying, and controlling work.
• Workable.Mcp: MCP server adapter for authored work, query tools, and worker action tools.
• Workable.SignalR: realtime worker events and component-view updates for ASP.NET Core clients.

Documentation

Using Workable

• Getting Started: package split, work author setup, host setup, and queueing work.
• Work Registration: define work in feature assemblies, generate definitions from sources, queue startup work, target named systems, and isolate catalogs.
• Work Queueing: queue work by name or id, pass input, set queue options, and await completion.
• Work Authorization: security model, work and system authorization, ASP.NET Core integration, and adapter behavior.
• Work Configuration: configuration sources, override order, and runtime reconfiguration rules.
  • Start: automatic start behavior and when queue calls return.
  • Idempotency: duplicate prevention by WorkSubjectId.
  • Recurrence: repeated execution and recurrence circuit behavior.
  • Transient Retry: transient exception classification and retry behavior.
  • Logging: worker-scoped logging behavior.
  • Retention: automatic purge timing for completed and canceled workers.
  • Concurrency: capacity limits by definition, subject, or concurrency key.
  • Queue Durability: persist accepted queue requests and replay interrupted durable work.
  • Invocation: channels allowed to start a work definition.
  • Interactions: non-obvious behavior when configuration types are combined.
• Work Querying: build admin views, status summaries, and definition browsers.
• Work Observability: subscribe to work events.
• Work Diagnostics: understand queue rejection, read-model lag, retention lag, and system warning signals.
• Work Profiling: capture per-worker execution profile trees.
• Workable HTTP API: expose registered work through HTTP endpoints.
• Workable MCP: expose registered work and read-only query tools through an MCP server.
• Workable Realtime: stream worker events, component-view updates, diagnostics, and admin event-viewer traffic through SignalR.
• Sample Host: run HTTP and MCP adapters together in one ASP.NET Core app.

Under The Hood

These docs explain what happens inside Workable after work is registered or queued.

• Core API Surface: understand systems, queues, workers, actions, queries, events, and public contracts.
• Work Authorization: security model, request-context sessions, and how the adapters apply authorization.
• Project Structure: source layout, package boundary, and namespace convention.
• Work Lifecycle: queue acceptance, execution, worker handles, and lifecycle diagrams.
• Execution Engine: dispatcher, execution strategies, concurrency coordination, event stream, and retention behavior.
• Work Diagnostics: runtime diagnostics, warning thresholds, and admin UI notification behavior.