Reliable Actors 入门Getting started with Reliable Actors

本文演示在 Visual Studio 中创建和调试简单的 Reliable Actor 应用程序。This article walks through creating and debugging a simple Reliable Actor application in Visual Studio. 有关 Reliable Actors 的详细信息,请参阅 Service Fabric Reliable Actors 简介For more information on Reliable Actors, see Introduction to Service Fabric Reliable Actors.

先决条件Prerequisites

在开始之前,确保计算机上已设置 Service Fabric 开发环境(包括 Visual Studio)。Before you start, ensure that you have the Service Fabric development environment, including Visual Studio, set up on your machine. 有关详细信息,请参阅如何设置开发环境For details, see how to set up the development environment.

在 Visual Studio 中创建新项目Create a new project in Visual Studio

以管理员身份启动 Visual Studio 2019 或更高版本,然后新建一个“Service Fabric 应用程序” 项目:Launch Visual Studio 2019 or later as an administrator, and then create a new Service Fabric Application project:

适用于 Visual Studio 的 Service Fabric 工具 - 新建项目

在下一对话框中,选择 .NET Core 2.0 下的“执行组件服务” ,并输入服务的名称。In the next dialog box, choose Actor Service under .NET Core 2.0 and enter a name for the service.

Service Fabric 项目模板

创建的项目显示以下结构:The created project shows the following structure:

Service Fabric 项目结构

检查解决方案Examine the solution

该解决方案包含三个项目:The solution contains three projects:

  • 应用程序项目 (MyApplication) 。The application project (MyApplication). 此项目将所有服务打包在一起以进行部署。This project packages all of the services together for deployment. 它包含用于管理应用程序的 ApplicationManifest.xml 和 PowerShell 脚本。It contains the ApplicationManifest.xml and PowerShell scripts for managing the application.

  • 接口项目 (HelloWorld.Interfaces) 。The interface project (HelloWorld.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.

  • 执行组件服务项目 (HelloWorld) 。The actor service project (HelloWorld). 此项目定义要托管执行组件的 Service Fabric 服务。This project defines the Service Fabric service that is going to host the actor. 它包含执行组件的实现 HelloWorld.cs 。It contains the implementation of the actor, HelloWorld.cs. 执行组件实现是派生自基类型 Actor 的一个类,用于实现 MyActor.Interfaces 项目中定义的接口。An actor implementation is a class that derives from the base type Actor and implements the interfaces defined in the MyActor.Interfaces project. 执行组件类还必须实现一个接受 ActorService 实例和 ActorId 并将其传递给基本 Actor 类的构造函数。An actor class must also implement a constructor that accepts an ActorService instance and an ActorId and passes them to the base Actor class.

    此项目还包含 Program.cs ,它使用 ActorRuntime.RegisterActorAsync<T>() 向 Service Fabric 运行时注册执行组件类。This project also contains Program.cs, which registers actor classes with the Service Fabric runtime using ActorRuntime.RegisterActorAsync<T>(). HelloWorld 类已注册。The HelloWorld class is already registered. 还必须使用 Main() 方法来注册添加到项目中的任何其他执行组件实现。Any additional actor implementations added to the project must also be registered in the Main() method.

自定义 HelloWorld 执行组件Customize the HelloWorld actor

项目模板定义 IHelloWorld 接口中的某些方法,并在 HelloWorld 执行组件实现中实现这些方法。The project template defines some methods in the IHelloWorld interface and implements them in the HelloWorld actor implementation. 替换这些方法,以便执行组件服务返回简单的“Hello World”字符串。Replace those methods so the actor service returns a simple "Hello World" string.

在 HelloWorld.Interfaces 项目中的 IHelloWorld.cs 文件上,替换接口定义,如下所示:In the HelloWorld.Interfaces project, in the IHelloWorld.cs file, replace the interface definition as follows:

public interface IHelloWorld : IActor
{
    Task<string> GetHelloWorldAsync();
}

在 HelloWorld 项目中的 HelloWorld.cs 上,替换整个类定义,如下所示:In the HelloWorld project, in HelloWorld.cs, replace the entire class definition as follows:

[StatePersistence(StatePersistence.Persisted)]
internal class HelloWorld : Actor, IHelloWorld
{
    public HelloWorld(ActorService actorService, ActorId actorId)
        : base(actorService, actorId)
    {
    }

    public Task<string> GetHelloWorldAsync()
    {
        return Task.FromResult("Hello from my reliable actor!");
    }
}

按 Ctrl-Shift-B 以生成项目并确保编译所有内容。Press Ctrl-Shift-B to build the project and make sure everything compiles.

添加客户端Add a client

创建一个简单的控制台应用程序,以调用执行组件服务。Create a simple console application to call the actor service.

  1. 右键单击“解决方案资源管理器”中的解决方案,并单击“添加” > “新建项目...” 。Right-click on the solution in Solution Explorer > Add > New Project....

  2. 在“.NET Core” 项目类型下,选择“控制台应用(.NET Core)” 。Under the .NET Core project types, choose Console App (.NET Core). 将项目命名为 ActorClient 。Name the project ActorClient.

    “添加新项目”对话框

    Note

    控制台应用程序不是通常在 Service Fabric 中用作客户端的那种应用,但它非常便于使用本地 Service Fabric 群集进行调试和测试。A console application is not the type of app you would typically use as a client in Service Fabric, but it makes a convenient example for debugging and testing using the local Service Fabric cluster.

  3. 控制台应用程序必须为 64 位的应用程序,以保持与接口项目和其他依赖项的兼容性。The console application must be a 64-bit application to maintain compatibility with the interface project and other dependencies. 在“解决方案资源管理器”中,右键单击“ActorClient” 项目,并单击“属性” 。In Solution Explorer, right-click the ActorClient project, and then click Properties. 在“生成” 选项卡上,将“平台目标” 设置为“x64” 。On the Build tab, set Platform target to x64.

    生成属性

  4. 客户端项目需要 Reliable Actors NuGet 包。The client project requires the reliable actors NuGet package. 单击“工具” > “NuGet 包管理器” > “包管理器控制台” 。Click Tools > NuGet Package Manager > Package Manager Console. 在“包管理器控制台”中,输入以下命令:In the Package Manager Console, enter the following command:

    Install-Package Microsoft.ServiceFabric.Actors -IncludePrerelease -ProjectName ActorClient
    

    NuGet 包及其所有依赖项都安装在 ActorClient 项目中。The NuGet package and all its dependencies are installed in the ActorClient project.

  5. 客户端项目还需要对接口项目的引用。The client project also requires a reference to the interfaces project. 在 ActorClient 项目中,右键单击“依赖项” ,然后单击“添加引用...” 。选择“项目”>“解决方案” (如果尚未选择),然后勾选“HelloWorld.Interfaces” 旁边的复选框。In the ActorClient project, right-click Dependencies and then click Add reference.... Select Projects > Solution (if not already selected), and then tick the checkbox next to HelloWorld.Interfaces. 单击 “确定”Click OK.

    “添加引用”对话框

  6. 在 ActorClient 项目中,将 Program.cs 的整个内容替换为以下代码:In the ActorClient project, replace the entire contents of Program.cs with the following code:

    using System;
    using System.Threading.Tasks;
    using Microsoft.ServiceFabric.Actors;
    using Microsoft.ServiceFabric.Actors.Client;
    using HelloWorld.Interfaces;
    
    namespace ActorClient
    {
        class Program
        {
            static void Main(string[] args)
            {
                IHelloWorld actor = ActorProxy.Create<IHelloWorld>(ActorId.CreateRandom(), new Uri("fabric:/MyApplication/HelloWorldActorService"));
                Task<string> retval = actor.GetHelloWorldAsync();
                Console.Write(retval.Result);
                Console.ReadLine();
            }
        }
    }
    

运行和调试Running and debugging

按 F5 在 Service Fabric 开发群集中本地生成、部署和运行应用程序。Press F5 to build, deploy, and run the application locally in the Service Fabric development cluster. 在部署过程中,可以在“输出”窗口中查看进度。During the deployment process, you can see the progress in the Output window.

Service Fabric 调试输出窗口

当输出包含文本“应用程序已准备就绪” 时,可使用 ActorClient 应用程序来测试服务。When the output contains the text, The application is ready, it's possible to test the service using the ActorClient application. 在“解决方案资源管理器”中,右键单击“ActorClient” 项目,然后单击“调试” > “启动新实例” 。In Solution Explorer, right-click on the ActorClient project, then click Debug > Start new instance. 命令行应用程序应显示执行组件服务中的输出。The command line application should display the output from the actor service.

应用程序输出

Tip

Service Fabric 执行组件运行时发出一些与执行组件方法相关的事件和性能计数器The Service Fabric Actors runtime emits some events and performance counters related to actor methods. 它们可用于进行诊断和性能监视。They are useful in diagnostics and performance monitoring.

后续步骤Next steps

了解有关 Reliable Actors 如何使用 Service Fabric 平台的详细信息。Learn more about how Reliable Actors use the Service Fabric platform.