TemporalCommunity.DurableObjects 0.1.1-preview.13

TemporalCommunity.DurableObjects

An object-based programming model built on top of the Temporal .NET SDK. Write stateful, durable actors backed by Temporal workflows — without managing workflow plumbing directly.

Requires Temporal Server v1.28.0 or later (Update-with-Start GA). Requires .NET 10.0. NativeAOT is not supported in v1 — see ADR 002.

Installation

dotnet add package TemporalCommunity.DurableObjects

Quick Start

Five steps from zero to a working DurableObject. No raw Temporal concepts in calling code.

Step 1: Define the contract

Every DurableObject starts with an interface extending IDurableObject. Decorate it with [Workflow] (the Temporal SDK uses this to derive the workflow type name). Updates are fire-and-confirm ([WorkflowUpdate]); queries are synchronous reads ([WorkflowQuery]).

using Temporalio.Workflows;
using TemporalCommunity.DurableObjects;

[Workflow]
public interface ICounter : IDurableObject
{
    [WorkflowUpdate] Task IncrementAsync();
    [WorkflowQuery]  int  GetCount();
}

Step 2: Implement it

Extend DurableObjectBase and implement your interface. The one mandatory boilerplate is [WorkflowRun] public Task RunAsync() => DurableObjectRunAsync(); — the SDK does not inherit [WorkflowRun] from the base class, so every concrete DurableObject must declare it. See BOILERPLATE.md for the full explanation.

[Workflow]
public class Counter : DurableObjectBase, ICounter
{
    private int _count;

    // Required boilerplate — see docs/BOILERPLATE.md
    [WorkflowRun] public Task RunAsync() => DurableObjectRunAsync();

    [WorkflowUpdate]
    public Task IncrementAsync()
    {
        _count++;
        return Task.CompletedTask;
    }

    [WorkflowQuery]
    public int GetCount() => _count;
}

Step 3: Register on the worker

AddDurableObjects registers IDurableObjectFactory in DI (client-side). AddDurableObjectWorkflows scans the assembly and registers the workflow types on the worker (worker-side). Both go in the same service configuration; they serve different roles.

// Using Temporalio.Extensions.Hosting
services.AddTemporalClient(opts => opts.TargetHost = "localhost:7233");

// Client-side: registers IDurableObjectFactory with DefaultTaskQueue = "my-task-queue"
services.AddDurableObjects("my-task-queue");

// Worker-side: scans the assembly, registers DurableObject workflow types
services.AddHostedTemporalWorker("my-task-queue")
        .AddDurableObjectWorkflows(typeof(Counter).Assembly);

Step 4: Call it

Inject IDurableObjectFactory, get a typed proxy, and call methods. No task queue, no workflow ID management, no SDK ceremony.

public class MyService(IDurableObjectFactory factory)
{
    public async Task RunAsync()
    {
        ICounter counter = factory.Get<ICounter>("my-counter");

        await counter.IncrementAsync();   // starts the object if not running; delivers the update
        int count = counter.GetCount();   // 1
    }
}

Step 5: Verify

dotnet run

The counter object starts on first call and persists across restarts. State survives worker crashes, ContinueAsNew history compaction, and re-deployments.

Key Concepts

Tier model

Objects have three lifecycle tiers. V1 ships Tier 1 and Tier 3. See TIER_MODEL.md.

DurableObject vs plain Temporal workflow

Use a DurableObject when you want an always-accessible stateful actor by stable ID — the mental model is a grain or entity, not a process. Use a plain Temporal workflow when the execution has a defined start and end with complex branching logic, or when you need child workflows, signals, or other SDK primitives not exposed by the DurableObject API surface.

Signals are banned — use updates

All methods on a DurableObject interface must be [WorkflowUpdate] or [WorkflowQuery]. [WorkflowSignal] is banned in v1, including on framework-provided methods. Signals bypass the authorization hook, give callers no confirmation, and offer no rollback on partial state mutation. See ADR 005.

NativeAOT limitation

DispatchProxy (used internally for the typed proxy) uses Reflection.Emit. NativeAOT strips this at publish time. Publishing a DurableObject worker with PublishAot=true will fail at runtime. A source-generator-based proxy is planned for v1.1. See ADR 002.

API Reference

IDurableObjectFactory methods

DurableObjectBase lifecycle hooks

Override any of these in your class. All have no-op defaults.

DurableObjectWorkerInterceptor options

Pass via AddDurableObjectWorkflows(assembly, options):

The interceptor is installed automatically by AddDurableObjectWorkflows. It also wraps arbitrary update handler exceptions into clean ApplicationFailureException rejections so the object does not wedge permanently. See FAILURE_HANDLING.md.

Failure Handling

Exception mapping, update handler failure taxonomy, lifecycle hook failure behavior, authorization patterns, and reminder idempotency — see FAILURE_HANDLING.md.

Versioning

Long-lived DurableObjects accumulate workflow history. Changes to handler names, signatures, and ContinueAsNew constructor schemas require care. See ADR 004 for the full versioning strategy: what is safe, what requires Workflow.Patched, and how to deploy new versions safely.

Object-to-Object Communication

Direct DurableObject-to-DurableObject messaging is deferred from v1. The v1 workaround is an Activity that calls the target object via ITemporalClient:

[Activity]
public class CallCounterActivity(IDurableObjectFactory factory)
{
    public async Task<int> GetRemoteCountAsync(string targetId)
    {
        var counter = factory.Get<ICounter>(targetId);
        return counter.GetCount();
    }
}

Execute it from inside an update handler:

[WorkflowUpdate]
public async Task SyncFromRemoteAsync(string remoteId)
{
    _count = await Workflow.ExecuteActivityAsync(
        (CallCounterActivity a) => a.GetRemoteCountAsync(remoteId),
        new ActivityOptions { StartToCloseTimeout = TimeSpan.FromSeconds(30) });
}

Three candidate designs (Activity-mediated, child workflows, Nexus) are under evaluation for v1.1. See ADR 003.

Building from Source

Prerequisites: .NET 10 SDK, just.

dotnet tool restore     # install minver-cli and reportgenerator
just build              # restore + compile (Release)
just test               # unit + integration tests
just pack               # produces artifacts/packages/*.nupkg
just doctor             # verify all prerequisites

Run just with no arguments to list all available recipes.

Common recipes

Contributing

1. Fork and clone.
2. dotnet tool restore once after cloning.
3. Run just ci before opening a PR — this is what CI runs.
4. For integration tests: just test-integration (no external Temporal server needed; it uses WorkflowEnvironment.StartLocalAsync()).
5. Add an ADR in docs/adr/ for any architectural decision, API surface change, or significant constraint. Follow the format in the existing ADRs.

License

MIT — see LICENSE.