Tutorial: Dapr.Actors.Next by example on Dapr Docs

Part 1: The cart, the modern baseline

Mon, 01 Jan 0001 00:00:00 +0000

The first example is the smallest real actor: a cart that adds items, returns a summary, and abandons itself after twenty minutes idle via a timer. It does nothing exotic, and that is the point. It is the side-by-side against Dapr.Actors that makes the modernization legible.

Code for this part: /examples/Actor.Next/01-Cart/.

What you build

[GenerateActorClient]
public interface ICartActor : IActor
{
 Task AddItem(CartItem item, CancellationToken ct = default);
 Task<CartSummary> GetSummary(CancellationToken ct = default);
 Task AbandonCart(CancellationToken ct = default);
}

public sealed record CartItem(string Sku, int Quantity);
public sealed record CartSummary(int ItemCount, decimal Total, bool Abandoned);

public interface IPricingClient
{
 ValueTask<decimal> GetPriceAsync(string sku, CancellationToken cancellationToken = default);
}

public sealed class CartState
{
 public Dictionary<string, int> Items { get; set; } = [];
 public Dictionary<string, decimal> Prices { get; set; } = [];
 public bool Abandoned { get; set; }
}

[DaprActor("Cart")]
public sealed class CartActor(
 ActorActivationContext context,
 IPricingClient pricing,
 IActorTimerScheduler timers) : Actor, ICartActor
{
 private static readonly TimeSpan AbandonAfter = TimeSpan.FromMinutes(20);

 protected override ActorId Id => context.ActorId;
 protected override IActorStateAccessor State => context.State;

 public async Task AddItem(CartItem item, CancellationToken ct = default)
 {
 var cart = await State.GetOrCreateAsync("cart", () => new CartState(), ct);
 cart.Value.Items[item.Sku] = cart.Value.Items.GetValueOrDefault(item.Sku) + item.Quantity; // mutate through .Value
 cart.Value.Prices[item.Sku] = await pricing.GetPriceAsync(item.Sku, ct); // injected per activation
 cart.Value.Abandoned = false;

 // Re-arm the idle timer on every add; its callback is the AbandonCart method.
 await timers.RescheduleAsync("Cart", Id, "abandon-cart", AbandonAfter, nameof(AbandonCart), string.Empty, cancellationToken: ct);
 }

 public async Task<CartSummary> GetSummary(CancellationToken ct = default)
 {
 var cart = await State.GetOrCreateAsync("cart", () => new CartState(), ct);
 var itemCount = cart.Value.Items.Values.Sum();
 var total = cart.Value.Items.Sum(entry => entry.Value * cart.Value.Prices.GetValueOrDefault(entry.Key));
 return new CartSummary(itemCount, total, cart.Value.Abandoned);
 }

 public async Task AbandonCart(CancellationToken ct = default)
 {
 var cart = await State.GetOrCreateAsync("cart", () => new CartState(), ct);
 cart.Value.Abandoned = true; // saved once at end of turn
 }
}

Startup is one line, with no endpoint mapping and no per-actor registration:

Part 2: Evolving the cart's state

Mon, 01 Jan 0001 00:00:00 +0000

The second example continues the same cart across a breaking state change. CartStateV1 stored a flat list of SKUs; CartStateV2 groups them into line items with quantities, and CartStateV3 adds a cached total. You ship each new shape with one small upcaster, and old carts fold forward on read with no data backfill.

Code for this part: /examples/Actor.Next/02-Migration/.

What you build

public sealed class CartStateV1ToV2 : IActorStateUpcaster<CartStateV1, CartStateV2>
{
 public ValueTask<CartStateV2> UpcastAsync(CartStateV1 state, CancellationToken cancellationToken = default)
 {
 var lines = state.Skus
 .GroupBy(sku => sku, StringComparer.Ordinal)
 .Select(group => new CartLine(group.Key, group.Count()))
 .ToList();

 return ValueTask.FromResult(new CartStateV2 { Lines = lines });
 }
}

public sealed class CartStateV2ToV3 : IActorStateUpcaster<CartStateV2, CartStateV3>
{
 public ValueTask<CartStateV3> UpcastAsync(CartStateV2 state, CancellationToken cancellationToken = default) =>
 ValueTask.FromResult(new CartStateV3
 {
 Lines = state.Lines.ToList(), TotalQuantity = state.Lines.Sum(line => line.Quantity),
 });
}

That is the entire migration: one small upcaster per shape change, and the chain composes. The source generator discovers and registers the upcasters; on read the runtime discovers whatever version is stored, folds it up to the shape your code asks for, and re-persists at the current shape lazily on the next save. Nothing in the actor branches on a version.

Part 3: The cart that reacts

Mon, 01 Jan 0001 00:00:00 +0000

The third example continues the cart. An inventory service publishes inventory-restocked events, and a cart waiting on an out-of-stock item should wake and mark it available. The subscription is declared on the actor method, and the event names which cart gets it.

Code for this part: /examples/Actor.Next/03-PubSub/.

What you build

[DaprActor("RestockingCart")]
public sealed class RestockingCartActor(ActorActivationContext context) : Actor, IRestockingCartActor
{
 protected override ActorId Id => context.ActorId;
 protected override IActorStateAccessor State => context.State;

 [Subscribe("orders-pubsub", "inventory-restocked", RouteBy = nameof(RestockEvent.CartId))]
 public async Task OnRestock(RestockEvent evt, CancellationToken ct = default)
 {
 var cart = await State.GetOrCreateAsync("cart", () => new RestockingCartState(), ct);

 // Delivery is at-least-once, so this must be safe to run more than once:
 // removing first makes a duplicate delivery a no-op after the first success.
 if (cart.Value.WaitingForStock.Remove(evt.Sku))
 {
 cart.Value.Available.Add(evt.Sku);
 }
 }
}

The host wires these subscriptions from [Subscribe] when you register the streams host alongside actors:

Part 4: The auction

Mon, 01 Jan 0001 00:00:00 +0000

The fourth example is the live auction: open and accepting bids, with a soft-close timer that each accepted bid resets; when it fires the auction transitions to sold and marks fulfillment as started. It looks like a workflow and is not, which is exactly what we’re seeking to illustrate. This is the example where the test is unambiguously the headline.

Code for this part: /examples/Actor.Next/04-Auction/.

What you build

[GenerateActorClient]
public interface IAuctionActor : IActor
{
 Task<BidResult> PlaceBid(Bid bid, CancellationToken cancellationToken = default);
 Task Close(CancellationToken cancellationToken = default);
 Task Expire(CancellationToken cancellationToken = default);
 Task<AuctionState> GetState(CancellationToken cancellationToken = default);
 Task<AuctionData> GetData(CancellationToken cancellationToken = default);
}

public enum AuctionState { Open, Sold, Expired }

public sealed record AuctionData(decimal HighBid, string? HighBidder, bool FulfillmentStarted)
{
 public static AuctionData Empty { get; } = new(0, null, false);
}

public sealed record Bid(decimal Amount, string Bidder);
public sealed record CloseAuction;
public sealed record ExpireAuction;
public enum BidResult { Accepted, TooLow, Closed }

[DaprActor("Auction")]
public sealed class AuctionActor(ActorActivationContext context, IActorTimerScheduler timers) : StateMachineActor<AuctionState, AuctionData>, IAuctionActor(context, timers, "Auction", AuctionData.Empty)
{
 private static readonly TimeSpan SoftClose = TimeSpan.FromSeconds(30);

 protected override void Configure(IStateMachine<AuctionState, AuctionData> sm)
 {
 sm.InitialState(AuctionState.Open);

 sm.In(AuctionState.Open)
 .On<Bid>()
 .When((data, bid) => bid.Amount > data.HighBid)
 .Do(async ctx =>
 {
 ctx.Update(data => data with { HighBid = ctx.Event.Amount, HighBidder = ctx.Event.Bidder });
 await timers.RescheduleAsync("Auction", Id, "soft-close", SoftClose, nameof(Close), string.Empty);
 ctx.Reply(BidResult.Accepted);
 })
 .Otherwise()
 .Reply(BidResult.TooLow);

 sm.In(AuctionState.Open)
 .On<CloseAuction>().GoTo(AuctionState.Sold);

 sm.In(AuctionState.Open)
 .On<ExpireAuction>().GoTo(AuctionState.Expired);

 sm.In(AuctionState.Sold)
 .OnEntry(ctx => ctx.Update(data => data with { FulfillmentStarted = true }))
 .Ignore<Bid>()
 .Ignore<CloseAuction>()
 .Ignore<ExpireAuction>();

 sm.In(AuctionState.Expired)
 .Ignore<Bid>()
 .Ignore<CloseAuction>()
 .Ignore<ExpireAuction>();
 }

 public Task<BidResult> PlaceBid(Bid bid, CancellationToken cancellationToken = default)
 {
 if (CurrentState != AuctionState.Open)
 {
 return Task.FromResult(BidResult.Closed);
 }

 return Raise<BidResult>(bid, cancellationToken);
 }

 public Task Close(CancellationToken cancellationToken = default) =>
 Raise<object?>(new CloseAuction(), cancellationToken);

 public Task Expire(CancellationToken cancellationToken = default) =>
 Raise<object?>(new ExpireAuction(), cancellationToken);

 public Task<AuctionState> GetState(CancellationToken cancellationToken = default) =>
 Task.FromResult(CurrentState);

 public Task<AuctionData> GetData(CancellationToken cancellationToken = default) =>
 Task.FromResult(Data);
}

Why a state machine, and where it ends

An auction is a long-lived, addressable entity with explicit states, not a finite process, so it belongs in a state-machine actor rather than a workflow. A high rate of bids would grow a workflow’s replay history without bound, every bidder needs an instant synchronous read of the current high bid, and the soft-close behavior is a race. The transition to Sold is where it hands off: its entry action marks fulfillment started, which is the point where a real deployment kicks off a fulfillment workflow for the finite, multi-step process (charge the winner, notify losers, arrange shipping), so the entity stays in the actor and the bounded orchestration goes to a workflow. That boundary is the thing to take away; the two compose rather than compete.

Part 5: Runtime-defined state machines

Mon, 01 Jan 0001 00:00:00 +0000

The fifth example is the destination the first four were building toward: state machines that are not compiled into your app at all, but supplied as data at runtime, verified before they go live, and driven without a compile-time contract.

The scenario is a device-management platform. You manage many kinds of devices, a smart lock, a thermostat, a valve, and each device type has its own state machine: a lock moves from Locked to Unlocking to Unlocked to Locking and back, driven by commands and sensor events. New device types are onboarded through configuration, not a code deploy, and each physical device is a long-lived, addressable entity, exactly the kind of thing Part 4 argued belongs in a state-machine actor. The difference here is that the machine is data, so one compiled actor runs every device type.

Part 6: Composing interpreted actors with workflows

Mon, 01 Jan 0001 00:00:00 +0000

The sixth example puts the interpreted runtime from Part 5 next to a Dapr Workflow and shows the two composing. An approval document is a long-lived, addressable entity, so it is an interpreted state-machine actor whose behavior is authored as data. Settling an approved document is a finite, failure-prone process, so it is a workflow. The entity starts the workflow, and the workflow drives the entity back; each does what it is good at.