Setup

Configure your local development environment to get started developing with Temporal.

Install .NET

The .NET SDK requires .NET 6.0 or later. Install .NET by following the official .NET instructions.

The .NET SDK requires .NET 6.0 or later.

Install .NET by following the official .NET instructions.

Install the Temporal .NET SDK

Create a new .NET project and install the Temporal SDK package.

Switch to the new directory for your project.

Then, install the Temporal .NET SDK.

Next, you'll configure a local Temporal service for development.

dotnet new console -n temporalidotnet

cd temporalidotnet

dotnet add package Temporalio

Install Temporal CLI

The fastest way to get a development version of the Temporal Service running on your local machine is to use Temporal CLI.

Temporal CLI is a tool for interacting with the Temporal Service from the command-line interface. It includes a self-contained distribution of the Temporal Service and Web UI that you can use for local development.

Choose your operating system to install Temporal CLI:

macOS

Using Homebrew:

brew install temporal

Or using curl:

curl -sSf https://temporal.download/cli.sh | sh

Linux

curl -sSf https://temporal.download/cli.sh | sh

Windows

curl.exe -sSf https://temporal.download/cli.ps1 | pwsh

Start the development server

Once you've installed Temporal CLI and added it to your PATH, open a new Terminal window and run the following command.

This command starts a local Temporal Service. It starts the Web UI, creates the default Namespace, and uses an in-memory database.

The Temporal Service will be available on localhost:7233. The Temporal Web UI will be available at http://localhost:8233.

Leave the local Temporal Service running as you work through tutorials and other projects. You can stop the Temporal Service at any time by pressing CTRL+C.

Once you have everything installed, you're ready to build apps with Temporal on your local machine.

temporal server start-dev

Change the Web UI port

The Temporal Web UI may be on a different port in some examples or tutorials. To change the port for the Web UI, use the --ui-port option when starting the server:

temporal server start-dev --ui-port 8080

The Temporal Web UI will now be available at http://localhost:8080.

Run Hello World: Test Your Installation

Now let's verify your setup is working by creating and running a complete Temporal application with both a Workflow and Activity.

This test will confirm that:

• Your .NET SDK installation is working
• The Temporal .NET SDK is properly installed
• Your local Temporal Service is running
• You can successfully create and execute Workflows and Activities
• The communication between components is functioning correctly

Create the Activity

Activities contain your business logic. Create a file called MyActivities.cs:

Create an Activity file (MyActivities.cs):

namespace MyNamespace;

using Temporalio.Activities;

public class MyActivities
{
// Activities can be async and/or static too! We just demonstrate instance
// methods since many will use them that way.
[Activity]
public string SayHello(string name) => $"Hello, {name}!";
}

Create the Workflow

Workflows orchestrate Activities and contain the application logic. Create a file called SayHelloWorkflow.cs:

Create a Workflow file (SayHelloWorkflow.cs):

namespace MyNamespace;

using Temporalio.Workflows;

[Workflow]
public class SayHelloWorkflow
{
[WorkflowRun]
public async Task<string> RunAsync(string name)
{
// This workflow just runs a simple activity to completion.
// StartActivityAsync could be used to just start and there are many
// other things that you can do inside a workflow.
return await Workflow.ExecuteActivityAsync(
// This is a lambda expression where the instance is typed. If this
// were static, you wouldn't need a parameter.
(MyActivities act) => act.SayHello(name),
new() { StartToCloseTimeout = TimeSpan.FromMinutes(5) });
}
}

Create and Run the Worker

The Worker hosts your Workflows and Activities. Replace the contents of Program.cs with:

Keep this terminal running - you should see "Running worker" displayed.

Create a Worker file (Program.cs):

using MyNamespace;
using Temporalio.Client;
using Temporalio.Worker;

// Create a client to localhost on "default" namespace
var client = await TemporalClient.ConnectAsync(new("localhost:7233"));

// Cancellation token to shutdown worker on ctrl+c
using var tokenSource = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
tokenSource.Cancel();
eventArgs.Cancel = true;
};

// Create an activity instance since we have instance activities. If we had
// all static activities, we could just reference those directly.
var activities = new MyActivities();

// Create worker with the activity and workflow registered
using var worker = new TemporalWorker(
client,
new TemporalWorkerOptions("my-task-queue").
AddActivity(activities.SayHello).
AddWorkflow<SayHelloWorkflow>());

// Run worker until cancelled
Console.WriteLine("Running worker");
try
{
await worker.ExecuteAsync(tokenSource.Token);
}
catch (OperationCanceledException)
{
Console.WriteLine("Worker cancelled");
}

Run the Worker:

dotnet run

Execute the Workflow

Now that your worker is running, it's time to start a workflow execution.

Choose Your Execution Method

With the worker running, you can start a workflow in two ways:

Option 1: Using Temporal CLI (Recommended for testing)

Open a new terminal and run:

temporal workflow start --type SayHelloWorkflow --task-queue my-task-queue --input '"Temporal"'

Option 2: Create a Client Program

Create a separate file called `Client.cs` for a more programmatic approach:

using MyNamespace;
using Temporalio.Client;

// Create a client to localhost on "default" namespace
var client = await TemporalClient.ConnectAsync(new("localhost:7233"));

// Run workflow
var result = await client.ExecuteWorkflowAsync(
(SayHelloWorkflow wf) => wf.RunAsync("Temporal"),
new(id: "my-workflow-id", taskQueue: "my-task-queue"));

Console.WriteLine("Workflow result: {0}", result);

Then run: dotnet run Client.cs

Verify Success

If everything is working correctly, you should see:

• Worker processing the workflow and activity
• Output: Workflow result: Hello, Temporal!
• Workflow execution details in the Temporal Web UI

Next: Run your first Temporal Application

Learn how to create a basic Workflow and run it with the Temporal .NET SDK

→