Skip to content

Durable task identity and references

Every durable task is identified by the grain which hosts it and a hierarchical TaskId. Identity is how a replay finds each recorded operation, how a retried start reaches the same task, how a callee distinguishes its callers, and how other parties observe, cancel, and signal a task. This page lists every kind of ID which the runtime constructs, where each one is visible, which changes preserve it, and how to address a task from elsewhere.

A task ID is a path of segments separated by /: a root segment, followed by one segment per level of nesting. DurableTask.Current.Id reports the ID of the running execution, and TaskId.Child(segment), Parent(), and IsAncestorOf(other) navigate the path.

  • TaskId.ToString() returns the escaped path, which TaskId.Parse reads back. A / or \ inside a segment is escaped with \, so a segment which contains a grain ID, such as report/q3, appears as report\/q3.
  • TaskId.CreateRoot(segment) and the string rootId overloads, such as GetDurableTask<TResult>(rootId) and IDurableTaskManager.CancelAsync(rootId, reason), take one unescaped root segment.
  • Segments which the runtime generates begin with, or contain, $. Names which WithId and DurableTask.RunInline receive inside a durable task don’t contain $, so a name never equals a generated segment; see ORLEANS0207.

The following workflow creates most kinds of ID. Its comments name the ID which each operation records:

public sealed class ReportGrain(IDurableTaskManager tasks) : DurableGrain, IReportGrain
{
public static readonly DurableSignal<bool> Approved = new("approved");
private string ReportId => this.GetPrimaryKeyString();
public static string PublishTaskId(string reportId) => $"publish-{reportId}";
// The caller starts this task under the root ID "publish-{reportId}", which DurableTask.Current.Id reports.
public async DurableTask<PublishReceipt> PublishAsync(string[] sections)
{
// publish-{reportId}/version, a named recorded effect, as WithId("version") names a step.
var version = DurableTask.RunInline("version", () => DateTimeOffset.UtcNow.ToUnixTimeSeconds());
// publish-{reportId}/$child-1, the execution's first unnamed operation.
var draftId = DurableTask.RunInline(Guid.NewGuid);
// publish-{reportId}/render/0, render/1, and so on: a named combinator's inputs, in input order. Each renderer
// stores its call under the caller's scope, $caller/{reportGrainId}/{incarnation}/publish-{reportId}/render/{i},
// where {incarnation} identifies this run of publish-{reportId}.
await sections.Select(section => Renderer(section).RenderAsync(section)).WhenAll().WithId("render");
// publish-{reportId}/check, then check$2, check$3, and so on: one name which this run repeats.
foreach (var section in sections)
{
await Check(section, draftId).WithId("check");
}
// publish-{reportId}/$signal:approved, the signal's record beneath the invoked task.
if (!await Approved.WaitAsync())
{
return new(DurableTask.Current.Id, default, default, default);
}
// A named detached task: the root "archive-{reportId}" on the archive grain. The execution records the start as
// publish-{reportId}/$detach:{archiveGrainId}:archive-{reportId}, which the handle's Id reports.
var archive = await Archive().ArchiveAsync(ReportId, (int)version).Detached($"archive-{ReportId}")
.ScheduleAsync();
// An unnamed detached task: its root ID derives from this grain, this task, and the next unnamed operation,
// "{reportGrainId}/publish-{reportId}:$child-2".
var copy = Archive().ArchiveAsync($"{ReportId}-copy", (int)version).Detached().Post();
return new(DurableTask.Current.Id, archive.TargetTaskId, copy.TargetTaskId, archive.Id);
}
public async Task<DurableSignalResult> ApproveAsync(bool approved) =>
await tasks.TrySignalAsync(PublishTaskId(ReportId), Approved, approved);
private static async DurableTask<bool> Check(string section, Guid draftId) => section.Length > 0 && draftId != Guid.Empty;
private IRendererGrain Renderer(string section) => GrainFactory.GetGrain<IRendererGrain>(section);
private IArchiveGrain Archive() => GrainFactory.GetGrain<IArchiveGrain>("archive");
}

A root task has no parent on its grain. The party which starts it chooses its root ID:

Started byRoot IDExample
A client or an ordinary grain method, with WithId(name)name, verbatimpublish-q3
A client or an ordinary grain method, without WithIdA new GUID, formatted with "N"3f2a9c01b7e44d6b9a0c5e8f1d2b3a47
A durable task, with .Detached(name)name, verbatimarchive-q3
A durable task, with .Detached() and no nameOne segment, {grainId}/{taskId}/{segment}: the starting grain, the starting execution’s ID, and the generated segment of the execution’s next unnamed operation, each with its / and \ escapedreport\/q3/publish-q3/$child-2

The root ID $caller is reserved for the caller scopes described below: only calls from other grains create tasks beneath it, and a client’s or grain’s start under it throws ArgumentException. Outside a durable task, .Detached() changes nothing, because every task which a client starts is already a root. A derived detached root ID includes the starting grain, so workflows with the same task ID on different grains start different tasks; starters which must share one task name it with WithId.

Each operation which a body runs is recorded beneath the execution’s ID:

OperationSegmentExample
A child, delay, combinator, or subscription named with WithId(name), or a recorded effect, DurableTask.RunInline(name, effect)name; later occurrences of the same name in one run, name$2, name$3, and so onpublish-q3/check$2
An unnamed child, delay, DurableTask.Run step, subscription, or DurableTask.RunInline(effect)$child-{n}, numbered in the order in which the run creates thempublish-q3/$child-1
An unnamed combinator or timeout${kind}-{n}, where {kind} is when-all, when-any, race, schedule-all, when-all-completed, when-each, or timeoutpublish-q3/$race-1
A combinator’s input{combinator}/{index}, in input orderpublish-q3/render/0
A timeout’s work and delay, WaitAsync and WaitUntilAsync{timeout}/0 and {timeout}/1quote/0, quote/1
A selection which a durable completion order can’t decide{combinator}/$winner for WhenAny, Race, and timeouts, or {combinator}/$next-{n} for WhenEachfirst-quote/$winner
A version decision, DurableTask.GetVersion(name, ...)$version:name, once per executionpublish-q3/$version:carrier-booking
A detached start$detach:{targetGrainId}:{rootId}publish-q3/$detach:archive\/archive:archive-q3
A signal send from a durable task$send:{targetGrainId}:{taskId}:{name}; repeated sends, $2, $3place-order-42/$send:order\/42:place-order-42:shipped
A signal’s recorded value, beneath the invoked task$signal:{name}; DurableSignal<T>.For(suffix) names {name}/{suffix}publish-q3/$signal:approved, publish-q3/$signal:approved\/round-2
  • Named children, named combinators, and named effects share one identifier per occurrence of a name: DurableTask.RunInline("x", f) and await DurableTask.Run(g).WithId("x") both record under x. A replay which finds the other kind recorded under an identifier diverges instead of running the work again: its execution stalls, and the divergence names both kinds.
  • Unnamed children, unnamed effects, unnamed subscriptions, and the segment of an unnamed detached root share the $child-{n} count. Unnamed combinators and timeouts share the ${kind}-{n} count.
  • Inside the parts of $detach: and $send: segments, :, \, and $ are escaped with \.
  • A selection is recorded only when completion order can’t decide it, such as when an input completed without a completion sequence. Its ID appears in the SelectionWaitStarted diagnostic event whenever a selection waits.
  • Each local step has its own execution, so its operations nest beneath its ID, such as publish-q3/check/$child-1.

A call to another grain is recorded in the caller’s tree under the call’s segment, such as publish-q3/render/0. Messages between the grains name the call by its wire ID: the incarnation of the caller’s run, a GUID which the caller’s grain mints when it stores the root task’s invocation, formatted with "N", followed by the call’s segments. The callee stores the task under the caller’s scope, by that wire ID:

{incarnation}/{callerTaskId}
$caller/{callerGrainId}/{incarnation}/{callerTaskId}
$caller/report\/q3/9b1c0e4f2d7a4e8c8f3b5a6d1e2c3b4a/publish-q3/render/0

The scope keeps callers apart: two grains whose workflows have the same task ID call one callee under different IDs, so neither reattaches to the other’s task. The incarnation keeps runs apart: once a grain deletes a root task’s tree, scheduling the same root ID runs it again with a new incarnation, so its calls reach new tasks, its messages aren’t deduplicated against the earlier run’s, and replies for the earlier run, such as a late completion or delay resume, change nothing. Within one run, the mapping is a pure function of the caller, the incarnation, and the child ID, so replays and redeliveries of the call reach the same task. In the callee, DurableTask.Current.Id reports the scoped ID, and DurableTask.Current.Incarnation reports the run of each tree. A detached start sends a root ID instead, which the callee stores verbatim. Subscriptions and detached starts name their recording child by its wire ID too, as the subscriber which the result’s completion addresses.

A signal addresses an invoked task: a root task, or a task which another grain called. Its value is recorded beneath that task as $signal:{name}, where waits anywhere in the task’s tree find it. An unnamed wait runs as part of the waiting execution and records no operation; a wait which WithId names runs as a child under that name. Shielding a wait leaves its identity unchanged.

Awaiting a DurableTaskReference<TResult> inside a durable task, scheduling it, or passing it to a combinator records a subscription child under the ID which that operation assigns, such as $child-3 or a WithId name. The child completes with the referenced task’s outcome.

SourceReports
DurableTask.Current.IdThe running execution: a root, a step, or a callee’s scoped task.
ScheduledTask.IdThe operation in the execution which started or observes the task: a child ID, a $detach: record, or a subscription child. Outside a durable task, the root ID.
ScheduledTask.TargetTaskIdThe task on the grain which stores it, which other parties address: a detached task’s root ID, a callee’s $caller/... ID, or the task which a subscription observes. Outside a durable task, the root ID.
IDurableTaskReference.IdThe referenced task, with Target, its grain.
DurableTaskAddress.IdA task which other parties address, with Target, its grain.
DurableTaskEventsThe ID of each task, operation, signal wait, and selection which a transition concerns.

A client observes the IDs of its own start through the handle:

public static async Task<PublishReceipt> PublishAsync(IClusterClient client, string reportId, string[] sections)
{
// The root ID comes from the report's identity, so a retried request reaches the same task.
ScheduledTask<PublishReceipt> publish = await client.GetGrain<IReportGrain>(reportId)
.PublishAsync(sections)
.WithId(ReportGrain.PublishTaskId(reportId))
.ScheduleAsync();
// Outside a durable task, a handle's Id and TargetTaskId are both the root ID.
Console.WriteLine($"{publish.Id} {publish.TargetTaskId}");
return await publish;
}

The runtime also uses names which aren’t IDs and aren’t part of the programming model: the journaled state orleans.durable-tasks.runtime and the tables inside it, such as $tasks, $task-requests, and $task-results, and request fingerprints which begin with $, such as $effect, $version, $subscribe:, $signal-send:, and $completion-decision:. Diagnostics show some of them; their format can change between releases.

A replay finds each recorded operation under the ID which the new run computes, so an ID is stable when every run computes it from the same inputs:

IDStable when
A root ID which WithId namesAlways: callers derive it.
A named operation, name or name$nThe name is unchanged, and earlier occurrences of the same name are unchanged.
$child-{n} and ${kind}-{n}Every run creates the unnamed operations before it in the same order.
A combinator’s input, {combinator}/{index}The combinator’s ID and its input order are unchanged.
$detach:, $send:, and $signal: recordsAlways: they derive from the target, the task, and the name.
$version: recordsAlways: they derive from the change’s name, and every check of the name in an execution shares one record.
A derived detached root IDThe starting execution’s ID and its $child-{n} count before the start are unchanged.
A caller-scoped IDThe caller’s child ID is unchanged.

The ID locates a record; the record’s operation decides whether a replay matches it. A replay matches when it requests the same kind of operation with the same target: a call to the same interface method on the same grain, a detached start of the same method under the same root ID, a subscription to the same task, a delay, a step, or an effect. The runtime identifies a method by its generated invokable type and doesn’t compare arguments, so a deployment which changes how an argument serializes, such as by adding an optional field or upgrading a serializer, replays the same operations, and a replay which passes different arguments reads the outcome recorded for the original call. A retry of a root task under its ID matches likewise: the same method from the same caller reaches the stored task, whatever its arguments, and another method or caller conflicts. Each record also stores a fingerprint of its request’s serialized arguments, which divergence and conflict messages report.

Changes between deployments affect pending executions as follows:

  • Renaming a WithId name gives the operation a new ID. A replay finds no record under it, so it runs the operation again, and the record under the old name stays in the tree until the tree is deleted.
  • Adding an unnamed operation before existing unnamed ones shifts their generated IDs. A replay then finds another operation’s record under a shifted ID: a call to another method or grain diverges and stalls the execution, a call to the same method on the same grain returns the other call’s outcome, and a local step returns the other step’s result.
  • Changing an argument’s serialized form, or the arguments which a call passes, leaves every operation’s identity unchanged.
  • Adding a named operation with a new name leaves every other ID unchanged.
  • Adding or removing an occurrence of a repeated name before existing ones renumbers the later occurrences; see ORLEANS0208.

Name every operation which a later change might move, give new operations new names, and follow Version workflows safely. To change operations which pending executions already passed, branch on DurableTask.GetVersion; see Version durable tasks.

A task is addressed by its grain and its task ID. Every party which knows both can observe, cancel, abort, or signal the task, while the grain retains it.

Root tasks, which clients, ordinary grain methods, and detached starts create, have their own lifetimes: their grain retains them for ResultRetentionPeriod after completion, and until each subscriber’s completion is delivered. They make durable references.

An attached child, including a callee’s $caller/... task, belongs to its owner’s tree: the callee deletes it once the calling grain accepts its result, and the owner’s grain deletes the owner’s tree once the root is terminal. Use its handle within the execution which started it, and start work which other parties track as a root.

When a task’s grain and root ID derive from business values, every party computes the reference instead of storing it. The archive started above is addressed from the report’s ID alone:

public static async Task<DurableTaskStatus> GetArchiveStatusAsync(IClusterClient client, string reportId)
{
// A named root is addressed by its grain and its name, which every party derives from the report's identity.
var archive = client.GetGrain<IArchiveGrain>("archive").GetDurableTask<bool>($"archive-{reportId}");
return await archive.GetStatusAsync(new PollingOptions { PollTimeout = TimeSpan.Zero });
}

Derived references need no storage, and a start under the same name from a retried request reaches the same task. Choose names which identify the business operation, such as archive-{reportId}, and keep them stable across deployments.

A DurableTaskAddress is the value which names a task elsewhere: its Target grain and its task Id. Orleans serializes it in grain calls and journaled state, and System.Text.Json writes it as {"Target":"report/q3","Id":"publish-q3"} in JSON journals and HTTP payloads. A TaskId on its own serializes as its escaped path.

ToUse
Read a handle’s addresshandle.TryGetAddress(out var address), which returns true for a root task, a detached task, or a task which GetDurableTask observes, and whose Id is the handle’s TargetTaskId. An attached child’s handle has no address.
Read a reference’s addressDurableTaskReference<TResult>.Address, or Target and Id through IDurableTaskReference.
Resolve an addressGrainFactory.GetDurableTask<TResult>(address) in a grain, or client.GetDurableTask<TResult>(address) in a client.
Signal the taskGrainFactory.GetGrain(address.Target), then SignalDurableTaskAsync or TrySignalDurableTaskAsync with address.Id.

The reference which an address resolves to behaves as any other: a durable task awaits it to subscribe to the task’s result, and other code awaits, polls, cancels, or aborts the task through it. A grain which hands off a detached task stores its address, and reaches the task again after any number of reactivations:

public interface IPublisherGrain : IGrainWithStringKey
{
DurableTask HandOffAsync(string reportId);
DurableTask<bool> AwaitArchiveAsync();
Task<DurableTaskStatus?> GetArchiveStatusAsync();
Task CancelArchiveAsync(string reason);
}
public sealed class PublisherGrain : DurableGrain, IPublisherGrain
{
private readonly IDurableValue<DurableTaskAddress?> _archive;
public PublisherGrain() => _archive = StateManager.GetOrAddValue<DurableTaskAddress?>("archive");
public async DurableTask HandOffAsync(string reportId)
{
// A detached task is a root on the archive grain, so its handle has an address.
var archive = await GrainFactory.GetGrain<IArchiveGrain>("archive")
.ArchiveAsync(reportId, version: 1)
.Detached()
.ScheduleAsync();
archive.TryGetAddress(out var address);
// The synchronous tail: the address commits with this task's result.
_archive.Value = address;
}
// A durable task subscribes to the stored task, and the subscription is recorded for replay.
public async DurableTask<bool> AwaitArchiveAsync()
{
var archive = DurableTask.RunInline("archive", () => _archive.Value);
return archive is { } address && await GrainFactory.GetDurableTask<bool>(address).WithId("archived");
}
// An ordinary method polls or cancels the stored task through the same address.
public async Task<DurableTaskStatus?> GetArchiveStatusAsync() =>
_archive.Value is { } address
? await GrainFactory.GetDurableTask<bool>(address).GetStatusAsync(new PollingOptions { PollTimeout = TimeSpan.Zero })
: null;
public async Task CancelArchiveAsync(string reason)
{
if (_archive.Value is { } address)
{
await GrainFactory.GetDurableTask<bool>(address).CancelAsync(reason);
}
}
}

The workflow stores the address in its synchronous tail, so the address commits with the task’s result. AwaitArchiveAsync reads the stored address in a recorded effect, so a replay subscribes to the same task.

A client returns an address to an HTTP caller, and a later request carries it back to signal, await, or cancel the task:

// Returns the address to an HTTP caller: System.Text.Json writes {"Target":"report/q3","Id":"publish-q3"}.
public static async Task<DurableTaskAddress> StartPublishAsync(IClusterClient client, string reportId, string[] sections)
{
var publish = await client.GetGrain<IReportGrain>(reportId)
.PublishAsync(sections)
.WithId(ReportGrain.PublishTaskId(reportId))
.ScheduleAsync();
publish.TryGetAddress(out var address);
return address;
}
// A later request carries the address back, and signals, awaits, or cancels the task.
public static async Task<DurableSignalResult> ApproveAsync(IClusterClient client, DurableTaskAddress publish, bool approved) =>
await client.GetGrain(publish.Target).TrySignalDurableTaskAsync(publish.Id, ReportGrain.Approved, approved);
public static async Task<PublishReceipt> WaitAsync(IClusterClient client, DurableTaskAddress publish) =>
await client.GetDurableTask<PublishReceipt>(publish);

An address grants control of the task to whoever holds it: anyone who can call the grain can cancel, abort, or signal the task. Authorize requests which carry an address before acting on it, as for any grain call which an external request triggers.

A reference resolves while the grain retains the task:

  • A task without a calling grain, such as a client-started or detached root, is retained for ResultRetentionPeriod after completion, and until the completion to each subscribing durable task is delivered.
  • A task which another grain called is deleted once the calling grain has durably accepted its result.

After deletion, polls and subscriptions throw DurableTaskNotFoundException, signals return TaskNotFound, and a start under the same ID runs the request again as a new run with its own incarnation, even within Messaging’s DeduplicationWindow: the calls, cancellations, subscriptions, signals, and delay resumes of the new run have their own message IDs, and the earlier run’s late replies don’t reach it. A DurableTaskNotFoundException also reports a task which never started, or whose start hasn’t reached its grain yet; ScheduleAsync returns once the grain holds the task, so an ID which it returned is found until retention ends. See Retention and deletion.