Quickstart

January 23, 2026 · View on GitHub

This guide walks you through creating your first Durable Task Framework (DTFx) orchestration.

Overview

In this quickstart, you'll create:

  1. An activity that performs a simple greeting
  2. An orchestration that calls the activity
  3. A host that runs the orchestration

Step 1: Create a New Project

dotnet new console -n HelloDurableTask
cd HelloDurableTask

Step 2: Install Packages

For this quickstart, we'll use the in-memory emulator:

dotnet add package Microsoft.Azure.DurableTask.Core
dotnet add package Microsoft.Azure.DurableTask.Emulator

💡 For production, see Choosing a Backend to select an appropriate provider.

Step 3: Create an Activity

Activities are the basic unit of work in DTFx. Create a file named GreetActivity.cs:

using DurableTask.Core;

public class GreetActivity : TaskActivity<string, string>
{
    protected override string Execute(TaskContext context, string name)
    {
        return $"Hello, {name}!";
    }
}

Step 4: Create an Orchestration

Orchestrations coordinate activities. Create a file named GreetingOrchestration.cs:

using DurableTask.Core;

public class GreetingOrchestration : TaskOrchestration<string, string>
{
    public override async Task<string> RunTask(OrchestrationContext context, string input)
    {
        // Call the GreetActivity
        string greeting = await context.ScheduleTask<string>(typeof(GreetActivity), input);
        return greeting;
    }
}

Step 5: Create the Host

Update Program.cs to create and run the orchestration:

using DurableTask.Core;
using DurableTask.Emulator;
using Microsoft.Extensions.Logging;

// Create logger factory for diagnostics
using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

// Create the in-memory orchestration service
var service = new LocalOrchestrationService();

// Create and configure the worker
var worker = new TaskHubWorker(service, loggerFactory);
worker.AddTaskOrchestrations(typeof(GreetingOrchestration));
worker.AddTaskActivities(typeof(GreetActivity));

// Start the worker
await worker.StartAsync();
Console.WriteLine("Worker started.");

// Create a client to start orchestrations
var client = new TaskHubClient(service, loggerFactory: loggerFactory);

// Start a new orchestration instance
var instance = await client.CreateOrchestrationInstanceAsync(
    typeof(GreetingOrchestration),
    "World");

Console.WriteLine($"Started orchestration: {instance.InstanceId}");

// Wait for completion
var result = await client.WaitForOrchestrationAsync(
    instance,
    TimeSpan.FromSeconds(30));

Console.WriteLine($"Result: {result.Output}");
Console.WriteLine($"Status: {result.OrchestrationStatus}");

// Stop the worker
await worker.StopAsync();

Step 6: Run the Application

dotnet run

Expected output:

Worker started.
Started orchestration: <guid>
Result: "Hello, World!"
Status: Completed

Understanding the Code

TaskActivity

public class GreetActivity : TaskActivity<string, string>
  • TaskActivity<TInput, TOutput> — Base class for activities
  • Activities contain the actual work logic
  • They are automatically retried on failure (configurable)

TaskOrchestration

public class GreetingOrchestration : TaskOrchestration<string, string>
  • TaskOrchestration<TResult, TInput> — Base class for orchestrations
  • Orchestrations coordinate activities and sub-orchestrations
  • They must be deterministic

OrchestrationContext

await context.ScheduleTask<string>(typeof(GreetActivity), input);
  • OrchestrationContext provides APIs for scheduling work
  • ScheduleTask — Schedule an activity
  • CreateSubOrchestrationInstance — Start a sub-orchestration
  • CreateTimer — Create a durable timer
  • WaitForExternalEvent — Wait for an external event

TaskHubWorker and TaskHubClient

  • TaskHubWorker — Hosts orchestrations and activities
  • TaskHubClient — Starts and manages orchestration instances

Next Steps