You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn all about using the actor client with the .NET SDK
6
+
description: Learn how to create actor clients with the IActorProxyFactory interface
7
7
---
8
8
9
-
## Using the IActorProxyFactory
9
+
Inside of an `Actor` class or an ASP.NET Core project, the `IActorProxyFactory` interface is recommended to create actor clients.
10
10
11
-
Inside of an `Actor` class or otherwise inside of an ASP.NET Core project you should use the `IActorProxyFactory` interface to create actor clients.
11
+
The `AddActors(...)` method will register actor services with ASP.NET Core dependency injection.
12
12
13
-
The `AddActors(...)` method will register actor services with ASP.NET Core dependency injection.
14
-
15
-
- Outside of an actor instance, the `IActorProxyFactory` instance is available through dependency injection as a singleton service.
16
-
- Inside an actor instance, the `IActorProxyFactory` instance is available as a property (`this.ProxyFactory`).
13
+
-**Outside of an actor instance:** The `IActorProxyFactory` instance is available through dependency injection as a singleton service.
14
+
-**Inside an actor instance:** The `IActorProxyFactory` instance is available as a property (`this.ProxyFactory`).
17
15
18
16
The following is an example of creating a proxy inside an actor:
19
17
@@ -27,30 +25,35 @@ public Task<MyData> GetDataAsync()
27
25
}
28
26
```
29
27
30
-
> 💡 For a non-dependency-injected application you can use the static methods on `ActorProxy`. These methods are error prone when you need to configure custom settings, and should be avoided when possible.
28
+
In this guide, you will learn how to use `IActorProxyFactory`.
31
29
32
-
The guidance in this document will focus on `IActorProxyFactory`. `ActorProxy`'s static method functionality is identical except for the ability to manage configuration centrally.
30
+
{{% alert title="Tip" color="primary" %}}
31
+
For a non-dependency-injected application, you can use the static methods on `ActorProxy`. Since the `ActorProxy` methods are error prone, try to avoid using them when configuring custom settings.
32
+
{{% /alert %}}
33
33
34
34
## Identifying an actor
35
35
36
-
In order to communicate with an actor, you will need to know its type and id, and for a strongly-typed client one of its interfaces. All of the APIs on `IActorProxyFactory` will require an actor type and actor id.
36
+
All of the APIs on `IActorProxyFactory` will require an actor _type_ and actor _id_ to communicate with an actor. For strongly-typed clients, you also need one of its interfaces.
37
37
38
-
-The actor type uniquely identifies the actor implementation across the whole application.
39
-
-The actor id uniquely identifies an instance of that type.
38
+
-**Actor type** uniquely identifies the actor implementation across the whole application.
39
+
-**Actor id** uniquely identifies an instance of that type.
40
40
41
-
If you do not have an actor id and want to communicate with a new instance, you can use `ActorId.CreateRandom()` to create a randomized id. Since the random id is a cryptographically strong identifier, the runtime will create a new actor instance when you interact with it.
41
+
If you don't have an actor `id` and want to communicate with a new instance, create a random id with `ActorId.CreateRandom()`. Since the random id is a cryptographically strong identifier, the runtime will create a new actor instance when you interact with it.
42
42
43
-
You can use the type `ActorReference` to exchange an actor type and actor id with other actors as part of messages.
43
+
You can use the type `ActorReference` to exchange an actor type and actor id with other actors as part of messages.
44
44
45
45
## Two styles of actor client
46
46
47
-
The actor client supports two different styles of invocation: *strongly-typed* clients that use .NET interfaces and *weakly-typed* clients that use the `ActorProxy` class.
47
+
The actor client supports two different styles of invocation:
48
48
49
-
Since *strongly-typed* clients are based on .NET interfaces provide the typical benefits of strong-typing, however they do not work with non-.NET actors. You should use the *weakly-typed* client only when required for interop or other advanced reasons.
49
+
| Actor client style | Description |
50
+
| ------------------ | ----------- |
51
+
| Strongly-typed | Strongly-typed clients are based on .NET interfaces and provide the typical benefits of strong-typing. They don't work with non-.NET actors. |
52
+
| Weakly-typed | Weakly-typed clients use the `ActorProxy` class. It is recommended to use these only when required for interop or other advanced reasons. |
50
53
51
54
### Using a strongly-typed client
52
55
53
-
Use the `CreateActorProxy<>` method to create a strongly-typed client like the following example. `CreateActorProxy<>` requires an actor interface type, and will return an instance of that interface.
56
+
The following example uses the `CreateActorProxy<>` method to create a strongly-typed client. `CreateActorProxy<>` requires an actor interface type, and will return an instance of that interface.
54
57
55
58
```csharp
56
59
// Create a proxy for IOtherActor to type OtherActor with a random id
@@ -64,7 +67,7 @@ await proxy.DoSomethingGreat();
64
67
65
68
### Using a weakly-typed client
66
69
67
-
Use the `Create` method to create a weakly-typed client like the following example. `Create` returns an instance of `ActorProxy`.
70
+
The following example uses the `Create` method to create a weakly-typed client. `Create` returns an instance of `ActorProxy`.
68
71
69
72
```csharp
70
73
// Create a proxy for type OtherActor with a random id
@@ -76,9 +79,9 @@ var proxy = this.ProxyFactory.Create(ActorId.CreateRandom(), "OtherActor");
76
79
awaitproxy.InvokeMethodAsync("DoSomethingGreat");
77
80
```
78
81
79
-
Since `ActorProxy` is a weakly-typed proxy you need to pass in the actor method name as a string.
82
+
Since `ActorProxy` is a weakly-typed proxy, you need to pass in the actor method name as a string.
80
83
81
-
You can also use `ActorProxy` to invoke methods with a request message and response message. Request and response messages will be serialized using the `System.Text.Json` serializer.
84
+
You can also use `ActorProxy` to invoke methods with both a request and a response message. Request and response messages will be serialized using the `System.Text.Json` serializer.
82
85
83
86
```csharp
84
87
// Create a proxy for type OtherActor with a random id
@@ -91,4 +94,21 @@ var request = new MyRequest() { Message = "Hi, it's me.", };
When using a weakly-typed proxy, it is your responsibility to define the correct actor method names and message types. This is done for you when using a strongly-typed proxy since the names and types are part of the interface definition.
97
+
When using a weakly-typed proxy, you _must_ proactively define the correct actor method names and message types. When using a strongly-typed proxy, these names and types are defined for you as part of the interface definition.
98
+
99
+
### Actor method invocation exception details
100
+
101
+
The actor method invocation exception details are surfaced to the caller and the callee, providing an entry point to track down the issue. Exception details include:
102
+
- Method name
103
+
- Line number
104
+
- Exception type
105
+
- UUID
106
+
107
+
You use the UUID to match the exception on the caller and callee side. Below is an example of exception details:
108
+
```
109
+
Dapr.Actors.ActorMethodInvocationException: Remote Actor Method Exception, DETAILS: Exception: NotImplementedException, Method Name: ExceptionExample, Line Number: 14, Exception uuid: d291a006-84d5-42c4-b39e-d6300e9ac38b
110
+
```
111
+
112
+
## Next steps
113
+
114
+
[Learn how to author and run actors with `ActorHost`]({{< ref dotnet-actors-usage.md >}}).
***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.
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:
25
+
26
+
- The actor implementation
27
+
- The clients calling the actor
28
+
29
+
Because client projects may depend on it, it's better to define it in an assembly separate from the actor implementation.
30
30
31
-
***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.
31
+
**The actor service project (\MyActor\MyActorService)**
32
+
33
+
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:
34
+
35
+
- Derives from the base type Actor
36
+
- Implements the interfaces defined in the `MyActor.Interfaces` project.
37
+
38
+
An actor class must also implement a constructor that accepts an `ActorService` instance and an `ActorId`, and passes them to the base Actor class.
39
+
40
+
**The actor client project (\MyActor\MyActorClient)**
41
+
42
+
This project contains the implementation of the actor client which calls MyActor's method defined in Actor Interfaces.
43
+
44
+
## Prerequisites
32
45
33
-
***The actor client project(\MyActor\MyActorClient)** This project contains the implementation of the actor client which calls MyActor's method defined in Actor Interfaces.
0 commit comments