| name | temporal-dotnet-sdk |
| description | This skill should be used when the user asks to 'create a Temporal workflow in C#', 'write a .NET activity', 'use Temporalio', 'fix .NET workflow determinism', 'debug workflow replay', '.NET workflow logging', or mentions 'Temporal .NET SDK' or 'Temporal C#'. Provides .NET-specific patterns, CRITICAL Task scheduling guidance, and observability patterns. |
| version | 0.1.0 |
Temporal .NET SDK Best Practices
Overview
The Temporal .NET SDK provides strongly-typed async/await workflows for .NET applications.
CRITICAL: Workflows use a custom TaskScheduler. Many standard Task patterns break determinism.
How Temporal Works: History Replay
Understanding how Temporal achieves durable execution is essential for writing correct workflows.
The Replay Mechanism
When a Worker executes workflow code, it creates Commands (requests for operations like starting an Activity or Timer) and sends them to the Temporal Cluster. The Cluster maintains an Event History - a durable log of everything that happened during the workflow execution.
Key insight: During replay, the Worker re-executes your workflow code but uses the Event History to restore state instead of re-executing Activities. When it encounters an Activity call that has a corresponding ActivityTaskCompleted event in history, it returns the stored result instead of scheduling a new execution.
This is why determinism matters: The Worker validates that Commands generated during replay match the Events in history. A mismatch causes a non-deterministic error because the Worker cannot reliably restore state.
.NET SDK has no sandbox - you must ensure determinism through code review and using the safe alternatives documented below. The custom helps enforce some constraints but cannot catch all non-deterministic code.
