temporalio__skill-temporal-developer/references/dotnet/determinism.md

.NET SDK Determinism

Overview

The .NET SDK has NO runtime sandbox (unlike Python/TypeScript). Workflows must be deterministic for replay, and determinism is enforced by developer convention and runtime task detection via an EventListener (see references/dotnet/determinism-protection.md).

Why Determinism Matters: History Replay

Temporal provides durable execution through History Replay. When a Worker restores workflow state, it re-executes workflow code from the beginning. This requires the code to be deterministic. See references/core/determinism.md for a deep explanation.

Forbidden Operations in Workflows

The following are forbidden inside workflow code but are appropriate to use in activities.

// DO NOT do these in workflows:
await Task.Run(() => { });              // Uses default scheduler
await Task.Delay(TimeSpan.FromSeconds(1)); // System timer
var now = DateTime.UtcNow;              // System clock
var r = new Random().Next();            // Non-deterministic
var id = Guid.NewGuid();               // Non-deterministic
File.ReadAllText("file.txt");           // I/O
await httpClient.GetAsync("...");       // Network I/O

Most non-determinism and side effects should be wrapped in Activities.

Safe Builtin Alternatives

Forbidden	Safe Alternative
DateTime.Now / DateTime.UtcNow	Workflow.UtcNow
Random	Workflow.Random
Guid.NewGuid()	Workflow.NewGuid()
Task.Delay	Workflow.DelayAsync
Thread.Sleep	Workflow.DelayAsync
Task.Run	Workflow.RunTaskAsync
Task.WhenAll	Workflow.WhenAllAsync
Task.WhenAny	Workflow.WhenAnyAsync
System.Threading.Mutex	Temporalio.Workflows.Mutex
System.Threading.Semaphore	Temporalio.Workflows.Semaphore
CancellationTokenSource.CancelAsync	CancellationTokenSource.Cancel

Testing Replay Compatibility

Use WorkflowReplayer to verify your code changes are compatible with existing histories. See the Workflow Replay Testing section of references/dotnet/testing.md.

Best Practices

1. Always use Workflow.* APIs instead of standard .NET equivalents (see table above)
2. Never use ConfigureAwait(false) in workflows
3. Use SortedDictionary or sort before iterating collections
4. Move all I/O operations (network, filesystem, database) into activities
5. Use Workflow.Logger instead of Console.WriteLine for replay-safe logging
6. Keep workflow code focused on orchestration; delegate non-deterministic work to activities
7. Test with replay after making changes to workflow definitions