The Actor Runtime Manager

The Actor Runtime is an execution fabric that designed for highly available actor services, allowing for multiple service replicas and providing data replication functionality and fail-over logic. When you launch an actor service, you launch it to the Actor Runtime.

The Actor Runtime works in terms of actor applications and actor services. An actor application can be thought of as the logic for a service. An actor service is an instance of an actor application. These are the actor applications provided “out-of-the-box” with this release:

  • EmptyActorApp: This actor application allows you to launch “empty” actor services, which are actor services with no built-in intelligence. Intelligence can be provided to these actors by transferring ActorMethod-containing assemblies to them.
  • ListActorApp: This actor application allows you to launch list actor services, which are actor services that have built-in intelligence for supporting list operations.

The Actor Runtime Manager is an application that, as you might guess, allows you to manage the Actor Runtime. The provided functionality includes installing the Actor Runtime software, deploying and bringing down an Actor Runtime cluster, deploying and un-deploying actor applications on an Actor Runtime cluster, and killing actor services.

This document contains instructions and information pertaining to the installation and operation of the Actor Runtime Manager.

Installing the Actor Runtime Manager

The Actor Runtime Manager is installed as part of the Actor Framework, which is installed by running ActorFramework.msi. The prerequisites for installing the Actor Framework are as follows:

  • 64-bit OS
  • Windows 7 or above
  • .NET 4.5

Starting the Actor Runtime Manager

When the Actor Framework is installed, an Administrator-mode shortcut to the Actor Runtime Manager is created on the desktop. Double-click that shortcut, and the Actor Runtime Manager should pop up.

Installing the Actor Runtime Software

The first time that you start up the Actor Runtime Manager, it will look like this:

ActorManager1

Before you do anything else, you need to install the Actor Runtime software. Do so by pressing the “Install” button. This results in running the .msi file associated with the Actor Runtime, and the ensuing process is mostly self-explanatory. When the installation is near completion, though, there are some specific directions that you need to follow:

  • Windows’ “Services” Control Panel is popped up, along with this message from the installer:

clip_image003

Follow those instructions. Note that if you change your password, you’ll need to re-enter your new password. Go to the Services Control Panel (Start -> Run -> Services, or type services.msc at a command prompt), find the “Windows Fabric Host Service”, open Properties then enter your new password.

  • When you follow the instructions and then shut down the “Services” Control Panel and the “Special Instructions” popup, you will see another popup:

clip_image004

Do as the pop-up says – press “OK”, log out, log back in, and re-launch the ActorRuntimeManager.

Deploying the Actor Runtime Cluster

Once the Actor Runtime Software is installed, the Actor Runtime Manager should look like this:

clip_image005

To “spin up” a simulated local[1] Actor Runtime cluster, press the “Deploy” button. Upon doing so, you should notice that five command prompt windows are popped up, looking something like this:

clip_image007

and your Actor Runtime Manager screen should indicate that the cluster has been deployed but is not yet accepting connections:

ActorManager2

You will need to wait awhile (between 1 and 5 minutes) as the cluster spins up and readies itself for Actor operations. Once the cluster is ready, you see that the Actor Runtime Manager screen now indicates that the cluster is deployed and connected:

ActorManager3

At this point, you can launch actor applications.

To un-deploy the Actor Runtime Cluster, press the “Undeploy” button (which used to be the “Deploy” button). Note that any actor applications and actor services that are deployed at the time that you take down the Actor Runtime Cluster will be brought back up the next time that you bring up the cluster.

Deploying Actor Applications

Pressing the “DeployActorApp…” button will result in a dialog being popped up:

clip_image012

Choose which type of Actor Application (ListActorApp or EmptyActorApp) to deploy, and then hit the “Deploy” button. The dialog will briefly stay up and give information about the progress of the deployment. When it pops down, five more command prompts will be popped up for the ListActorApp or EmptyActorApp, each of which should look something like this:

clip_image014

When the deployment of the Actor Application is complete, its existence will be noted in the Actor Runtime Manager window:

ActorManager4

To un-deploy an actor application, check it’s entry in the “Deployed Actor Apps” list and press the “Undeploy Checked Apps” button. Note that it’s good form to first stop all actor services associated with an actor application before un-deploying the actor application.

Stopping Actor Services

To stop an actor service, check its entry in the “Running Actors” list and then press the “Stop Checked Actors” button. It is legal to take down multiple services at once. Note that though the resulting operation may appear to be nearly instantaneous, it may take some time for the actor service to be fully brought down.

 

Development Environment

Setup

After installing the Actor Runtime Manager and deploying an actor, you’ll want to create a VS project that interacts with the actor. We have provided a VS project template. Install it like this:

  • Create the following directory on your machine:

“C:\Users\%USERNAME%\Documents\Visual Studio 2012\Templates\ProjectTemplates\Visual C#\Cloud”

  • Copy the Actor Application.zip to the directory above.
  • Launch VS2012.
  • Create a new project. Look in Visual C# -> Cloud for a template called “Actor Application”, like this:

clip_image002

  • Choose that template and call your new project whatever you like.
  • If the Actor Runtime is running, and you have deployed the “EmptyActorApp” from the Actor Runtime Manager, then you should be able to run the project.

From there, feel free to tweak the application as you see fit, changing the behavior of the provided actor methods or adding some of your own. The possibilities are endless!

Current Limitations

In our initial release, all client applications must target x64. Our intention is to support compilation on other platforms in the future via .NET portable libraries, and eventually Javascript as well.

Actors cannot currently be accessed from Windows Store applications. This is a limitation of the Actor Runtime that we intend to fix over time.


[1] Our aim is to have production Azure cluster support built into the Actor Runtime Manager very soon.

Last edited Dec 7, 2012 at 5:59 AM by claudioc, version 5

Comments

darrellt May 25, 2013 at 10:19 PM 
This is fantastic news and just what we need to drive our Knowledge Management tools and systems.

Thanks for all that you do Microsoft!

Tavi