How to: Run and use virtual actors in the .NET SDK

Try out .NET Dapr virtual actors with this example

The Dapr actor package allows you to interact with Dapr virtual actors from a .NET application. In this guide, you learn how to:

  • Create an Actor (MyActor).
  • Invoke its methods on the client application.
  1. MyActor --- MyActor.Interfaces
  2.          |
  3.          +- MyActorService
  4.          |
  5.          +- MyActorClient

The interface project (\MyActor\MyActor.Interfaces)

This project contains the interface definition for the actor. Actor interfaces can be defined in any project with any name. The interface defines the actor contract shared by:

  • The actor implementation
  • The clients calling the actor

Because client projects may depend on it, it’s better to define it in an assembly separate from the actor implementation.

The actor service project (\MyActor\MyActorService)

This project implements the ASP.Net Core web service that hosts the actor. It contains the implementation of the actor, MyActor.cs. An actor implementation is a class that:

  • Derives from the base type Actor
  • Implements the interfaces defined in the MyActor.Interfaces project.

An actor class must also implement a constructor that accepts an ActorService instance and an ActorId, and passes them to the base Actor class.

The actor client project (\MyActor\MyActorClient)

This project contains the implementation of the actor client which calls MyActor’s method defined in Actor Interfaces.

Prerequisites

Step 0: Prepare

Since we’ll be creating 3 projects, choose an empty directory to start from, and open it in your terminal of choice.

Step 1: Create actor interfaces

Actor interface defines the actor contract that is shared by the actor implementation and the clients calling the actor.

Actor interface is defined with the below requirements:

  • Actor interface must inherit Dapr.Actors.IActor interface
  • The return type of Actor method must be Task or Task<object>
  • Actor method can have one argument at a maximum

Create interface project and add dependencies

  1. # Create Actor Interfaces
  2. dotnet new classlib -o MyActor.Interfaces
  4. cd MyActor.Interfaces
  6. # Add Dapr.Actors nuget package. Please use the latest package version from nuget.org
  7. dotnet add package Dapr.Actors
  9. cd ..

Implement IMyActor interface

Define IMyActor interface and MyData data object. Paste the following code into MyActor.cs in the MyActor.Interfaces project.

  1. using Dapr.Actors;
  2. using Dapr.Actors.Runtime;
  3. using System.Threading.Tasks;
  5. namespace MyActor.Interfaces
  6. {
  7.     public interface IMyActor : IActor
  8.     {       
  9.         Task<string> SetDataAsync(MyData data);
  10.         Task<MyData> GetDataAsync();
  11.         Task RegisterReminder();
  12.         Task UnregisterReminder();
  13.         Task<IActorReminder> GetReminder();
  14.         Task RegisterTimer();
  15.         Task UnregisterTimer();
  16.     }
  18.     public class MyData
  19.     {
  20.         public string PropertyA { get; set; }
  21.         public string PropertyB { get; set; }
  23.         public override string ToString()
  24.         {
  25.             var propAValue = this.PropertyA == null ? "null" : this.PropertyA;
  26.             var propBValue = this.PropertyB == null ? "null" : this.PropertyB;
  27.             return $"PropertyA: {propAValue}, PropertyB: {propBValue}";
  28.         }
  29.     }
  30. }

Step 2: Create actor service

Dapr uses ASP.NET web service to host Actor service. This section will implement IMyActor actor interface and register Actor to Dapr Runtime.

Create actor service project and add dependencies

  1. # Create ASP.Net Web service to host Dapr actor
  2. dotnet new web -o MyActorService
  4. cd MyActorService
  6. # Add Dapr.Actors.AspNetCore nuget package. Please use the latest package version from nuget.org
  7. dotnet add package Dapr.Actors.AspNetCore
  9. # Add Actor Interface reference
  10. dotnet add reference ../MyActor.Interfaces/MyActor.Interfaces.csproj
  12. cd ..

Add actor implementation

Implement IMyActor interface and derive from Dapr.Actors.Actor class. Following example shows how to use Actor Reminders as well. For Actors to use Reminders, it must derive from IRemindable. If you don’t intend to use Reminder feature, you can skip implementing IRemindable and reminder specific methods which are shown in the code below.

Paste the following code into MyActor.cs in the MyActorService project:

  1. using Dapr.Actors;
  2. using Dapr.Actors.Runtime;
  3. using MyActor.Interfaces;
  4. using System;
  5. using System.Threading.Tasks;
  7. namespace MyActorService
  8. {
  9.     internal class MyActor : Actor, IMyActor, IRemindable
  10.     {
  11.         // The constructor must accept ActorHost as a parameter, and can also accept additional
  12.         // parameters that will be retrieved from the dependency injection container
  13.         //
  14.         /// <summary>
  15.         /// Initializes a new instance of MyActor
  16.         /// </summary>
  17.         /// <param name="host">The Dapr.Actors.Runtime.ActorHost that will host this actor instance.</param>
  18.         public MyActor(ActorHost host)
  19.             : base(host)
  20.         {
  21.         }
  23.         /// <summary>
  24.         /// This method is called whenever an actor is activated.
  25.         /// An actor is activated the first time any of its methods are invoked.
  26.         /// </summary>
  27.         protected override Task OnActivateAsync()
  28.         {
  29.             // Provides opportunity to perform some optional setup.
  30.             Console.WriteLine($"Activating actor id: {this.Id}");
  31.             return Task.CompletedTask;
  32.         }
  34.         /// <summary>
  35.         /// This method is called whenever an actor is deactivated after a period of inactivity.
  36.         /// </summary>
  37.         protected override Task OnDeactivateAsync()
  38.         {
  39.             // Provides Opporunity to perform optional cleanup.
  40.             Console.WriteLine($"Deactivating actor id: {this.Id}");
  41.             return Task.CompletedTask;
  42.         }
  44.         /// <summary>
  45.         /// Set MyData into actor's private state store
  46.         /// </summary>
  47.         /// <param name="data">the user-defined MyData which will be stored into state store as "my_data" state</param>
  48.         public async Task<string> SetDataAsync(MyData data)
  49.         {
  50.             // Data is saved to configured state store implicitly after each method execution by Actor's runtime.
  51.             // Data can also be saved explicitly by calling this.StateManager.SaveStateAsync();
  52.             // State to be saved must be DataContract serializable.
  53.             await this.StateManager.SetStateAsync<MyData>(
  54.                 "my_data",  // state name
  55.                 data);      // data saved for the named state "my_data"
  57.             return "Success";
  58.         }
  60.         /// <summary>
  61.         /// Get MyData from actor's private state store
  62.         /// </summary>
  63.         /// <return>the user-defined MyData which is stored into state store as "my_data" state</return>
  64.         public Task<MyData> GetDataAsync()
  65.         {
  66.             // Gets state from the state store.
  67.             return this.StateManager.GetStateAsync<MyData>("my_data");
  68.         }
  70.         /// <summary>
  71.         /// Register MyReminder reminder with the actor
  72.         /// </summary>
  73.         public async Task RegisterReminder()
  74.         {
  75.             await this.RegisterReminderAsync(
  76.                 "MyReminder",              // The name of the reminder
  77.                 null,                      // User state passed to IRemindable.ReceiveReminderAsync()
  78.                 TimeSpan.FromSeconds(5),   // Time to delay before invoking the reminder for the first time
  79.                 TimeSpan.FromSeconds(5));  // Time interval between reminder invocations after the first invocation
  80.         }
  82.         /// <summary>
  83.         /// Get MyReminder reminder details with the actor
  84.         /// </summary>
  85.         public async Task<IActorReminder> GetReminder()
  86.         {
  87.             await this.GetReminderAsync("MyReminder");
  88.         }
  90.         /// <summary>
  91.         /// Unregister MyReminder reminder with the actor
  92.         /// </summary>
  93.         public Task UnregisterReminder()
  94.         {
  95.             Console.WriteLine("Unregistering MyReminder...");
  96.             return this.UnregisterReminderAsync("MyReminder");
  97.         }
  99.         // <summary>
  100.         // Implement IRemindeable.ReceiveReminderAsync() which is call back invoked when an actor reminder is triggered.
  101.         // </summary>
  102.         public Task ReceiveReminderAsync(string reminderName, byte[] state, TimeSpan dueTime, TimeSpan period)
  103.         {
  104.             Console.WriteLine("ReceiveReminderAsync is called!");
  105.             return Task.CompletedTask;
  106.         }
  108.         /// <summary>
  109.         /// Register MyTimer timer with the actor
  110.         /// </summary>
  111.         public Task RegisterTimer()
  112.         {
  113.             return this.RegisterTimerAsync(
  114.                 "MyTimer",                  // The name of the timer
  115.                 nameof(this.OnTimerCallBack),       // Timer callback
  116.                 null,                       // User state passed to OnTimerCallback()
  117.                 TimeSpan.FromSeconds(5),    // Time to delay before the async callback is first invoked
  118.                 TimeSpan.FromSeconds(5));   // Time interval between invocations of the async callback
  119.         }
  121.         /// <summary>
  122.         /// Unregister MyTimer timer with the actor
  123.         /// </summary>
  124.         public Task UnregisterTimer()
  125.         {
  126.             Console.WriteLine("Unregistering MyTimer...");
  127.             return this.UnregisterTimerAsync("MyTimer");
  128.         }
  130.         /// <summary>
  131.         /// Timer callback once timer is expired
  132.         /// </summary>
  133.         private Task OnTimerCallBack(byte[] data)
  134.         {
  135.             Console.WriteLine("OnTimerCallBack is called!");
  136.             return Task.CompletedTask;
  137.         }
  138.     }
  139. }

Register actor runtime with ASP.NET Core startup

The Actor runtime is configured through ASP.NET Core Startup.cs.

The runtime uses the ASP.NET Core dependency injection system to register actor types and essential services. This integration is provided through the AddActors(...) method call in ConfigureServices(...). Use the delegate passed to AddActors(...) to register actor types and configure actor runtime settings. You can register additional types for dependency injection inside ConfigureServices(...). These will be available to be injected into the constructors of your Actor types.

Actors are implemented via HTTP calls with the Dapr runtime. This functionality is part of the application’s HTTP processing pipeline and is registered inside UseEndpoints(...) inside Configure(...).

Paste the following code into Startup.cs in the MyActorService project:

  1. using Microsoft.AspNetCore.Builder;
  2. using Microsoft.AspNetCore.Hosting;
  3. using Microsoft.Extensions.DependencyInjection;
  4. using Microsoft.Extensions.Hosting;
  6. namespace MyActorService
  7. {
  8.     public class Startup
  9.     {
  10.         public void ConfigureServices(IServiceCollection services)
  11.         {
  12.             services.AddActors(options =>
  13.             {
  14.                 // Register actor types and configure actor settings
  15.                 options.Actors.RegisterActor<MyActor>();
  16.             });
  17.         }
  19.         public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  20.         {
  21.             if (env.IsDevelopment())
  22.             {
  23.                 app.UseDeveloperExceptionPage();
  24.             }
  26.             app.UseRouting();
  28.             app.UseEndpoints(endpoints =>
  29.             {
  30.                 // Register actors handlers that interface with the Dapr runtime.
  31.                 endpoints.MapActorsHandlers();
  32.             });
  33.         }
  34.     }
  35. }

Step 3: Add a client

Create a simple console app to call the actor service. Dapr SDK provides Actor Proxy client to invoke actor methods defined in Actor Interface.

Create actor client project and add dependencies

  1. # Create Actor's Client
  2. dotnet new console -o MyActorClient
  4. cd MyActorClient
  6. # Add Dapr.Actors nuget package. Please use the latest package version from nuget.org
  7. dotnet add package Dapr.Actors
  9. # Add Actor Interface reference
  10. dotnet add reference ../MyActor.Interfaces/MyActor.Interfaces.csproj
  12. cd ..

Invoke actor methods with strongly-typed client

You can use ActorProxy.Create<IMyActor>(..) to create a strongly-typed client and invoke methods on the actor.

Paste the following code into Program.cs in the MyActorClient project:

  1. using System;
  2. using System.Threading.Tasks;
  3. using Dapr.Actors;
  4. using Dapr.Actors.Client;
  5. using MyActor.Interfaces;
  7. namespace MyActorClient
  8. {
  9.     class Program
  10.     {
  11.         static async Task MainAsync(string[] args)
  12.         {
  13.             Console.WriteLine("Startup up...");
  15.             // Registered Actor Type in Actor Service
  16.             var actorType = "MyActor";
  18.             // An ActorId uniquely identifies an actor instance
  19.             // If the actor matching this id does not exist, it will be created
  20.             var actorId = new ActorId("1");
  22.             // Create the local proxy by using the same interface that the service implements.
  23.             //
  24.             // You need to provide the type and id so the actor can be located. 
  25.             var proxy = ActorProxy.Create<IMyActor>(actorId, actorType);
  27.             // Now you can use the actor interface to call the actor's methods.
  28.             Console.WriteLine($"Calling SetDataAsync on {actorType}:{actorId}...");
  29.             var response = await proxy.SetDataAsync(new MyData()
  30.             {
  31.                 PropertyA = "ValueA",
  32.                 PropertyB = "ValueB",
  33.             });
  34.             Console.WriteLine($"Got response: {response}");
  36.             Console.WriteLine($"Calling GetDataAsync on {actorType}:{actorId}...");
  37.             var savedData = await proxy.GetDataAsync();
  38.             Console.WriteLine($"Got response: {response}");
  39.         }
  40.     }
  41. }

Running the code

The projects that you’ve created can now to test the sample.

  1. Run MyActorService

    Since MyActorService is hosting actors, it needs to be run with the Dapr CLI.

    1. cd MyActorService
    2. dapr run --app-id myapp --app-port 5000 --dapr-http-port 3500 -- dotnet run

    You will see commandline output from both daprd and MyActorService in this terminal. You should see something like the following, which indicates that the application started successfully.

    1. ...
    2. ℹ️  Updating metadata for app command: dotnet run
    3. ✅  You're up and running! Both Dapr and your app logs will appear here.
    5. == APP == info: Microsoft.Hosting.Lifetime[0]
    7. == APP ==       Now listening on: https://localhost:5001
    9. == APP == info: Microsoft.Hosting.Lifetime[0]
    11. == APP ==       Now listening on: http://localhost:5000
    13. == APP == info: Microsoft.Hosting.Lifetime[0]
    15. == APP ==       Application started. Press Ctrl+C to shut down.
    17. == APP == info: Microsoft.Hosting.Lifetime[0]
    19. == APP ==       Hosting environment: Development
    21. == APP == info: Microsoft.Hosting.Lifetime[0]
    23. == APP ==       Content root path: /Users/ryan/actortest/MyActorService

  2. Run MyActorClient

    MyActorClient is acting as the client, and it can be run normally with dotnet run.

    Open a new terminal an navigate to the MyActorClient directory. Then run the project with:

    1. dotnet run

    You should see commandline output like:

    1. Startup up...
    2. Calling SetDataAsync on MyActor:1...
    3. Got response: Success
    4. Calling GetDataAsync on MyActor:1...
    5. Got response: Success

💡 This sample relies on a few assumptions. The default listening port for an ASP.NET Core web project is 5000, which is being passed to dapr run as --app-port 5000. The default HTTP port for the Dapr sidecar is 3500. We’re telling the sidecar for MyActorService to use 3500 so that MyActorClient can rely on the default value.

Now you have successfully created an actor service and client. See the related links section to learn more.