Dapr actors .NET SDK on Dapr 文档库

IActorProxyFactory 接口

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

在使用 actor 类或 ASP.NET Core 项目时，推荐使用 IActorProxyFactory 接口来创建 actor 客户端。

通过 AddActors(...) 方法，actor 服务将通过 ASP.NET Core 的依赖注入机制进行注册。

在 actor 实例之外： IActorProxyFactory 实例作为单例服务通过依赖注入提供。
在 actor 实例内部： IActorProxyFactory 实例作为属性 (this.ProxyFactory) 提供。

以下是在 actor 内部创建代理的示例：

public Task<MyData> GetDataAsync()
{
 var proxy = this.ProxyFactory.CreateActorProxy<IOtherActor>(ActorId.CreateRandom(), "OtherActor");
 await proxy.DoSomethingGreat();

 return this.StateManager.GetStateAsync<MyData>("my_data");
}

在本指南中，您将学习如何使用 IActorProxyFactory。

提示

对于不使用依赖注入的应用程序，您可以使用 ActorProxy 的静态方法。由于 ActorProxy 方法容易出错，建议在配置自定义设置时尽量避免使用。

确定 actor

IActorProxyFactory 的所有 API 都需要提供 actor 的类型和 id 以便与其通信。对于强类型客户端，您还需要提供其接口之一。

actor 类型 在整个应用程序中唯一标识 actor 实现。
actor id 唯一标识该类型的一个实例。

如果您没有 actor id 并希望与新实例通信，可以使用 ActorId.CreateRandom() 创建一个随机 id。随机 id 是一个加密强标识符，运行时将在您与其交互时创建一个新的 actor 实例。

编写和运行actor

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

编写actor

ActorHost

ActorHost：

是所有actor构造函数所需的参数
由运行时提供的
必须传递给基类的构造函数
包含允许该actor实例与运行时通信的所有状态信息

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host) // 在构造函数中接收ActorHost
 : base(host) // 将ActorHost传递给基类的构造函数
 {
 }
}

由于ActorHost包含actor特有的状态信息，您不需要将其实例传递给代码的其他部分。建议仅在测试中创建您自己的ActorHost实例。

依赖注入

actor支持通过依赖注入将额外的参数传递到构造函数中。您定义的任何其他参数都将从依赖注入容器中获取其值。

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host, BankService bank) // 在构造函数中接收BankService
 : base(host)
 {
 ...
 }
}

一个actor类型应该只有一个public构造函数。actor系统使用ActivatorUtilities模式来创建actor实例。

您可以在Startup.cs中注册类型以进行依赖注入以使其可用。阅读更多关于注册类型的不同方法。

// 在Startup.cs中
public void ConfigureServices(IServiceCollection services)
{
 ...

 // 使用依赖注入注册额外的类型。
 services.AddSingleton<BankService>();
}

每个actor实例都有其自己的依赖注入范围，并在执行操作后在内存中保留一段时间。在此期间，与actor关联的依赖注入范围也被视为活动状态。该范围将在actor被停用时释放。

如果actor在构造函数中注入IServiceProvider，actor将接收到与其范围关联的IServiceProvider的引用。IServiceProvider可以用于将来动态解析服务。

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host, IServiceProvider services) // 在构造函数中接收IServiceProvider
 : base(host)
 {
 ...
 }
}

使用此模式时，避免创建许多实现IDisposable的瞬态服务。由于与actor关联的范围可能被视为有效时间较长，您可能会在内存中积累许多服务。有关更多信息，请参阅依赖注入指南。

IDisposable和actor

actor可以实现IDisposable或IAsyncDisposable。建议您依赖依赖注入进行资源管理，而不是在应用程序代码中实现释放功能。仅在确实必要的情况下提供释放支持。

日志记录

在actor类内部，您可以通过基类Actor上的属性访问ILogger实例。此实例连接到ASP.NET Core日志系统，应该用于actor内部的所有日志记录。阅读更多关于日志记录。您可以配置各种不同的日志格式和输出接收器。

使用_结构化日志记录_和_命名占位符_，如下例所示：

public Task<MyData> GetDataAsync()
{
 this.Logger.LogInformation("获取状态时间为 {CurrentTime}", DateTime.UtcNow);
 return this.StateManager.GetStateAsync<MyData>("my_data");
}

记录日志时，避免使用格式字符串，如：$"获取状态时间为 {DateTime.UtcNow}"

日志记录应使用命名占位符语法，这提供了更好的性能和与日志系统的集成。

使用显式actor类型名称

默认情况下，客户端看到的actor的_类型_是从actor实现类的_名称_派生的。默认名称将是类名（不包括命名空间）。

如果需要，您可以通过将ActorAttribute属性附加到actor实现类来指定显式类型名称。

.NET SDK 中的 Actor 序列化

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

Actor 序列化

Dapr actor 包使您能够在 .NET 应用程序中使用 Dapr 虚拟 actor，您可以选择使用弱类型或强类型客户端。每种方式都有不同的序列化方法。本文档将回顾这些差异，并传达一些在任一场景中需要理解的关键基本规则。

请注意，由于序列化方法的不同，弱类型和强类型 actor 客户端不能交替使用。使用一个 actor 客户端持久化的数据将无法通过另一个 actor 客户端访问，因此在整个应用程序中选择一种并一致使用非常重要。

弱类型 Dapr Actor 客户端

本节将介绍如何配置 C# 类型，以便在使用弱类型 actor 客户端时正确进行序列化和反序列化。这些客户端使用基于字符串的方法名称，并通过 System.Text.Json 序列化器来处理请求和响应负载。请注意，这个序列化框架并不是 Dapr 特有的，而是由 .NET 团队在 .NET GitHub 仓库中单独维护的。

当使用弱类型 Dapr Actor 客户端从各种 actor 调用方法时，不需要独立序列化或反序列化方法负载，因为 SDK 会透明地为您处理这些操作。

客户端将使用您构建的 .NET 版本中可用的最新 System.Text.Json 版本，序列化受相关 .NET 文档中提供的所有固有功能的影响。

序列化器将配置为使用 JsonSerializerOptions.Web 默认选项，除非通过自定义选项配置覆盖，这意味着将应用以下内容：

属性名称的反序列化以不区分大小写的方式进行
属性名称的序列化使用驼峰命名法，除非属性被 [JsonPropertyName] 属性覆盖
反序列化将从数字和/或字符串值读取数值

基本序列化

在以下示例中，我们展示了一个名为 Doodad 的简单类，尽管它也可以是一个记录。

public class Doodad
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public int Count { get; set; }
}

默认情况下，这将使用类型中成员的名称以及实例化时的值进行序列化：

{"id": "a06ced64-4f42-48ad-84dd-46ae6a7e333d", "name": "DoodadName", "count": 5}

覆盖序列化属性名称

可以通过将 [JsonPropertyName] 属性应用于所需属性来覆盖默认属性名称。

如何：在 .NET SDK 中运行和使用虚拟 actor

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

Dapr actor 包使您能够从 .NET 应用程序中与 Dapr 虚拟 actor 交互。在本指南中，您将学习如何：

创建一个 actor (MyActor)。
在客户端应用程序上调用其方法。

MyActor --- MyActor.Interfaces
 |
 +- MyActorService
 |
 +- MyActorClient

接口项目 (\MyActor\MyActor.Interfaces)

此项目包含 actor 的接口定义。actor 接口可以在任何项目中定义，名称不限。接口定义了 actor 实现和调用 actor 的客户端共享的 actor 合约：

actor 实现
调用 actor 的客户端

由于客户端项目可能依赖于它，最好将其定义在与 actor 实现分开的程序集内。

actor 服务项目 (\MyActor\MyActorService)

此项目实现了托管 actor 的 ASP.Net Core Web 服务。它包含 actor 的实现，MyActor.cs。actor 实现是一个类，它：

派生自基础类型 actor
实现 MyActor.Interfaces 项目中定义的接口。

actor 类还必须实现一个构造函数，该构造函数接受一个 ActorService 实例和一个 ActorId，并将它们传递给基础 actor 类。

actor 客户端项目 (\MyActor\MyActorClient)

此项目包含 actor 客户端的实现，该客户端调用在 actor 接口中定义的 MyActor 的方法。