Example of running and using virtual actors in the .NET SDK

    The Dapr actor package allows you to interact with Dapr virtual actors from a .NET application.

    Overview

    This document describes how to create an Actor () and invoke its methods on the client application.

    • 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 that is shared by the actor implementation and the clients calling the actor. Because client projects may depend on it, it typically makes sense to define it in an assembly that is separate from the actor implementation.

    • The actor service project(\MyActor\MyActorService). This project implements ASP.Net Core web service that is going to host the actor. It contains the implementation of the actor, MyActor.cs. An actor implementation is a class that derives from the base type Actor and 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.

    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
    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 -v 1.0.0
    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 System.Threading.Tasks;
    4. namespace MyActor.Interfaces
    5. {
    6.     public interface IMyActor : IActor
    7.     {       
    8.         Task<string> SetDataAsync(MyData data);
    9.         Task<MyData> GetDataAsync();
    10.         Task RegisterReminder();
    11.         Task UnregisterReminder();
    12.         Task RegisterTimer();
    13.         Task UnregisterTimer();
    14.     }
    16.     public class MyData
    17.     {
    18.         public string PropertyA { get; set; }
    19.         public string PropertyB { get; set; }
    21.         public override string ToString()
    22.         {
    23.             var propAValue = this.PropertyA == null ? "null" : this.PropertyA;
    24.             var propBValue = this.PropertyB == null ? "null" : this.PropertyB;
    25.             return $"PropertyA: {propAValue}, PropertyB: {propBValue}";
    26.         }
    27.     }
    28. }
    1. # Create ASP.Net Web service to host Dapr actor
    2. dotnet new web -o MyActorService
    5. # Add Dapr.Actors.AspNetCore nuget package. Please use the latest package version from nuget.org
    6. dotnet add package Dapr.Actors.AspNetCore -v 1.0.0
    8. # Add Actor Interface reference
    9. dotnet add reference ../MyActor.Interfaces/MyActor.Interfaces.csproj
    11. 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:

    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 .

    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.UseHttpsRedirection();
    28.             app.UseRouting();
    30.             app.UseEndpoints(endpoints =>
    31.             {
    32.                 // Register actors handlers that interface with the Dapr runtime.
    33.                 endpoints.MapActorsHandlers();
    34.             });
    35.         }
    36.     }
    37. }

    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 -v 1.0.0
    9. # Add Actor Interface reference
    10. dotnet add reference ../MyActor.Interfaces/MyActor.Interfaces.csproj
    12. cd ..

    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.     class Program
    9.     {
    10.         static async Task MainAsync(string[] args)
    11.         {
    14.             // Registered Actor Type in Actor Service
    15.             var actorType = "MyActor";
    17.             // An ActorId uniquely identifies an actor instance
    18.             // If the actor matching this id does not exist, it will be created
    19.             var actorId = new ActorId("1");
    21.             // Create the local proxy by using the same interface that the service implements.
    22.             //
    23.             // You need to provide the type and id so the actor can be located. 
    24.             var proxy = ActorProxy.Create<IMyActor>(actorId, actorType);
    26.             // Now you can use the actor interface to call the actor's methods.
    27.             Console.WriteLine($"Calling SetDataAsync on {actorType}:{actorId}...");
    28.             var response = await proxy.SetDataAsync(new MyData()
    29.             {
    30.                 PropertyA = "ValueA",
    31.                 PropertyB = "ValueB",
    32.             });
    33.             Console.WriteLine($"Got response: {response}");
    35.             Console.WriteLine($"Calling GetDataAsync on {actorType}:{actorId}...");
    36.             var savedData = await proxy.GetDataAsync();
    37.             Console.WriteLine($"Got response: {response}");
    38.         }
    39.     }
    40. }

    1. Run MyActorService

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

      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

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