The Actor Runtime Manager
This document covers installing and deploying the Actor Runtime, using the Actor Runtime Manager to deploy or stop actors, and setup for an Actor Application VS project template.
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
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 and using the Actor Runtime Manager are as follows:
- 64-bit OS
- Windows 7 or above
- .NET Framework 4.5
- Windows Azure SDK 1.8 (October 2012)
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:
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:
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:
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, and you re-launch the Actor Runtime Manager, it should look like this:
The “Scour” button was added in release 0.2, and it can come in handy when you upgrade your Actor Runtime. The purpose of the “Scour” button is to erase all traces of Actor software from your Actor Runtime cluster. The cluster should be “scoured” either
just before installing an Actor Runtime update or just after doing so; without performing a scour, it is possible that the ActorRuntime will get confused between some leftover bits from the old version and new bits from the new version. And note that, in order
for the “Scour” to be effective, you need to have stopped all actors and un-deployed all actor apps before running the “Scour”. Also notice that the “Scour” button is only enabled when the cluster is spun down.
Note further the addition of connection mode and connection string information to our UI in version 0.2. We are part of the way through enabling users to change the mode from “Local” to “Cloud”; once we have that fully supported, we will enable the “Change”
To “spin up” a simulated local Actor Runtime cluster, press the “Deploy” button. Upon doing so, you should notice that five command prompt windows are popped up, looking something
and your Actor Runtime Manager screen should indicate that the cluster has been deployed but is not yet accepting connections:
You will need to wait a while (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:
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:
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:
When the deployment of the Actor Application is complete, its existence will be noted in the Actor Runtime Manager window:
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
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.
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:
- 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!
Actors cannot currently be accessed from Windows Store applications. This is a limitation of the Actor Runtime that we intend to fix over time.
There are a couple of tools available for actor developers that come with the release. They are located in the application installation directory (“C:\Program Files (x86)\MSOpenTech\Actor Framework” on most boxes).
ActorDirectClient is a command-line application that allows you to connect to an actor and then call actor methods on that actor. By default, ActorDirectClient connects to the Actor Runtime cluster at 127.0.0.1:9000 (i.e., the local development cluster on
your machine). If you would like it to connect to some other Actor Runtime cluster (e.g., yourCloudService.cloudapp.net:9000), then run ActorClientDirect from the command line and pass the desired connection string as a parameter.
When the ActorDirectClient first comes up, you see something like this:
Welcome to the Direct Actor Client
To which actor would you like to connect?
Choose your desired actor (make sure to choose an actor, not an application), and hit return. You are then asked:
Would you like to use a Gateway Service to connect to the Windows Fabric Service?
Windows Gateway Service enables users to use Windows Fabric Services running in
Azure from outside of Azure
Enter ‘y’ if you are connecting to a service running on Azure, ‘n’ if you are connecting to a service running locally in a development environment.
After that, you can call actor methods on your chosen actor, where the first entry on the line is the name of the actor method and the remaining entries are parameters for that method, and get results back:
Enter method and parameters: Length ListDeployer
Enter method and parameters: Enumerate ListDeployer 0 -1
Note that all parameters are passed to the chosen actor as strings, so the actor methods called must be able to accept string parameters.
In addition to calling actor methods, there are some other special-purpose commands that can be useful for testing:
- “AddAssembly”: Ships the current assembly (i.e., ActorDirectClient.exe) over to your actor. You should then be able to call some actor methods defined within the assembly, like SayHello.
- “SUBSCRIBE <eventType>”: Requests that the actor publish all events of type <eventType> to this client. You will then be notified each time that such an event type is received.
- “UNSUBSCRIBE <eventType”: Requests that the actor cease publishing events of type <eventType> to this client.
- “TIME <iterations> <command>”: Allows you to time how long it takes for <iterations> repetitions of <command> to complete. Sample usage:
TIME 1000 Push ListDeployer right xxx
The example above runs “Push ListDeployer right xxx” 1000 times, and tells you how long it took to do so.
Actors produce ETW information for certain events. The ActorAnalyzer is a GUI application that allows you to connect to one or more actors and see the recent ETW history on that actor, as well as monitor newly emitted ETW events in real time.
The ActorAnalyzer looks like this when it first comes up:
Make sure that the “Fabric Address” matches the Actor Runtime cluster that contains your actor (by default, it points to a local development cluster), and then press the “Connect to Actor…” button. You see a list of available actors to monitor (in this case,
Choose the desired actor and press “Select”. You return to the main GUI, which should now have a tabbed pane with events from your chosen actor:
This pane will be updated in real time as new actor events are emitted. If you so desire, you can proceed to connect to other actors and have multiple panes showing.
Note that, as of the 0.3 release, the following ETW events are produced by actors:
Emitted every time that an assembly is added to an actor.
Signifies that one or more types failed to load while ingesting an assembly.
Signifies that an actor method within an assembly was rejected due to having an unrecognized signature.
Signifies that an actor method was successfully loaded as part of an assembly.
Signifies that an actor method has successfully been called.
Signifies that an actor method call was unsuccessful.
Also note that, since our default filter for ETW events is “Informational”, you should never see any ActorMethodCompleted events.
Finally, please take note that we plan on expanding ETW coverage in the future so that the data obtainable through this tool is richer and more informative.
 Our aim is to have production Azure cluster support built into the Actor Runtime Manager very soon.