Azure Service Fabric is a distributed systems platform that makes it easy to package, deploy, and manage scalable and reliable microservices and addresses the significant challenges in developing and managing cloud applications. By using Service Fabric, developers and administrators can avoid solving complex infrastructure problems and focus instead on implementing mission-critical, demanding workloads knowing that they are scalable, reliable, and manageable. Service Fabric represents the next-generation middleware platform for building and managing these enterprise-class, Tier-1 cloud-scale applications.
In this tutorial, UK Technical Evangelist Joni Collinge we will guide you through creating a simple application hosted on top of the Azure Service Fabric platform.
Step 1. Prerequisites
Before we get started we need to ensure we have the correct environment configured to complete this tutorial.
Currently Azure Service Fabric only supports the following operating system versions:
– Windows 7 (requires PowerShell 3.0 or higher installed)
– Windows 8/Windows 8.1
– Windows Server 2012 R2
– Windows 10
Note: At the time of writing, the Linux support is still in preview and not due for release until later this year. (show date and expected date if any known)
If you do not have the correct operating system installed on your local machine, you can head over to http://portal.azure.com and create a Virtual Machine with one of the supported versions installed. Once created, you can connect to the machine via a Remote Desktop Protocol client.
Now you should have a machine with one of the supported operating systems installed and ready.
Service Fabric runtime, SDK and tooling
Enable PowerShell script execution
Service Fabric uses Windows PowerShell scripts for creating a local development cluster and deploying application from Visual Studio. By default, Windows will block these scripts from executing. Therefore, we need to run a simple line of PowerShell to allow them to execute.
Open PowerShell as administrator and enter the following command:
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force -Scope CurrentUser
Step 2. Creating the application
Now that we have setup the environment correctly, we can begin to develop our first Service Fabric application. Before we start to write any code we need to understand the topology of applications in Service Fabric.
Service Fabric cluster topology
The cluster is the root of the hierarchy. The cluster can host 0 to many application types. These application types can have 0 to many application instances. Each of the application instances can have 1 to many services.
An individual service consists of 3 components; code, configuration and data.
Everything within this topology can be individually versioned and thus individually updated. This gives us much greater flexibility and agility when developing large multi-service applications.
Step 3. Creating a new Service Fabric application project
1. Open Visual Studio as an administrator.
2. Click File > New Project > Cloud > Service Fabric Application.
a. Provide a name for your application
b. Select a location to save the solution folder
c. Provide a solution name
d. Click OK
3. A dialogue box will pop up with a selection of Service Templates. Select the Stateful Service template.
a. Provide a service name
b. Click OK
Visual Studio will now create an application project and a stateful service project. These should now be visible in the Solution Explorer within Visual Studio.
The application project exists to help knit all the underlying services together into a single application. It does not contain code directly. Rather, it contains references to a set of service projects (at the moment this set only consists of the 1 stateful service you just created). The application project also contains;
Publish profiles: Used to manage configuration for publishing this application to different clusters.
Scripts: Includes PowerShell scripts to deploy/upgrade the application. Don’t worry, Visual Studio will invoke these scripts for you.
Application Parameters: An application parameters file.
Application Manifest: A manifest file to describe your application and reference each of the comprising services and their versions. This file resides in the ApplicationPackageRoot folder.
Step 4. Understanding the application
Let’s dig into the stateful service project that was created during the previous step. Expand the stateful service in the Solution Explorer and you should a number of files inside. The 2 we’re interested in are the Program.cs and MyStatefulService.cs (or whatever you named the service). Let’s open the Program.cs file up and inspect its contents.
1. Double click on the Program.cs file in the Solution Explorer.
The boilerplate code is well documented with comments so do please read them. I’ll attempt to add a little context to them as we go. Like any C# .NET application, the entry point is the static void Main() method. The code registers your stateful service with the Service Fabric runtime by providing a unique service type name and a service factory which the runtime can invoke in order to instantiate the service. If you are familiar with the concept of dependency injection, this is where you would provide your service’s dependencies.
Line 26 is simply reporting that an event has happened to the system.
Finally, as the comment states, we have an infinite sleep. This stops this particular thread from terminating and thus killing the service’s host process.
We don’t need to change anything in this file for our tutorial, but it’s important to know that it exists and what it is doing.
2. Open up the MyStatefulService.cs from the Solution Explorer.
This class consists of a constructor and 2 methods;
– RunAsync: This method will be invoked once your service is ready to begin ‘doing work’. This is an optional method which is intended to do continuous processing i.e. pulling jobs off a queue, processing and storing.
Step 5. Reliable Collections
The Service Fabric Stateful Services application model provides Reliable Collections. These are similar data structures to collections you make have used in standard C# or other programming languages. There are currently 2 reliable collections;
– ReliableDictionary<TKey, KValue>
These collections behave like you might expect – however, under the covers they are harnessing Service Fabric’s in built cluster replication and persistence sub-system to store the data in a highly available and reliable way. In some cases, this can mean you don’t need to write that data out to an external data store at all and can keep the data right next to the code in the cluster.
Note: as the operation against the sub-system are performed asynchronously and with transactional consistency, we too have to work with our collections in the same manner.
The responsibility for managing our service’s reliable collections is given to a class called the ReliableStateManager. Each stateful service inherits from an abstract class called StatefulService, this abstract class contains an instance of ReliableStateManager.
As the ReliableStateManager is responsible for our reliable collections, we must request the collection from it. This is evident on line 44.
Each collection is stored in the ReliableStateManager using a string identifier, in this case, “myDictionary”. Now that we have our reliable collection, we can operate on our data.
On line 46 we enter an ‘infinite’ loop… or do we? It is important to understand how Service Fabric manages its services. Notice how we pass in a CancellationToken to the RunAsync method. If Service Fabric wants to kill its request to RunAsync for whatever reason it will use this token to do so, therefore, it is important for our service to comply. We can either do this by checking the token’s IsCancellationRequested property on each loop iteration or by using the ThrowIfCancellationRequested method as is shown on line 48.
Next we have a using statement that uses the ReliableStateManager to create a transaction. This allows us to operate on our collections atomically i.e. every operation on the collection in the code block either completes or none of them do. This is very important for keeping our collections in a consistent state without having to worry about partially performed operations.
Inside this transaction there are 2 operations performed on the collection. Both of which are fairly self-explanatory.
The add or update operation performed on line 57 checks if the key “Counter” exists in the dictionary, if it does, it invokes the factory method (4th parameter), if it doesn’t it adds it.
Once we have finished all our operations on the collection, we commit our transaction.
Finally, we perform a simple delay to give the CPU a chance to context switch, notice we’re still respecting the cancellation token.
So what is this service actually doing? Well it’s simply getting a counter that is stored in a reliable collection, incrementing it, logging it as an event, and saving it back to the reliable collection. Let’s see this in action.
Ensure your application is set as the StartUp project in the Solution Explorer and that you have the build target set as follows;
3. Click on Start.
Note: The first time you do this, it will take a little while as Visual Studio needs to create a local development cluster. Subsequent deployments should be quicker as the cluster will already be built.
4. Open the Diagnostic Events tab in Visual Studio if it did not automatically do so.
5. Double click on an event in the trace to expand it.
We can see in this event that is says the nodeName is “_Node_4” (this will be unique to your running instance). In this development environment we are running the equivalent of a 5 node cluster on a single machine. Normally this would be deployed across a 5 machine cluster.
6. Open a web browser and go to the URL: http://localhost:19080/Explorer
This should open the Service Fabric Explorer (SFX). SFX gives you a simple dashboard to monitor the health and status of all the applications and services running in your cluster.
7. Expand Cluster > Nodes
8. Select the Node with the same name as the node that was reported to be running the service in your Diagnostic Event viewer i.e. “_Node_4” in my case.
9. Once selected, you should be able to see an “Actions” button in the upper right hand side of the panel. Click on that button, it should load a menu similar to the one shown here.
10. Click on Deactive (restart). This is simulating a machine restarting due to failure or OS upgrade.
11. Reopen the Diagnostic Events viewer in Visual Studio.
12. You should see the numbers still climbing and the service continuing as if nothing has happened. It’s important to notice the counter value has stay continuous even though the machine that value was counting on has been restarted. Service Fabric’s persistence sub system has handled the state replication for you seamlessly. During the restart you may see a handful of system service messages be spat out whilst the service handles the initialisation – but this shouldn’t take very long at all.
13. Now double click on a new event in the Diagnostic Events viewer to expand its payload. You should notice the nodeName has now changed as the service was more or less instantly migrated to a new node. In my case it moved to “_Node_2”.
Once you’ve stop developing and no longer need the cluster, it’s very important to clean everything up and give those resource back to your system.
1. Stop debugging in Visual Studio.
2. Expand your Windows System Tray and you should see a Service Fabric icon.
Note: I have a vertical task bar
3. Right click on the Service Fabric icon and click ‘stop local cluster’.
4. Once it notifies you that the cluster has been successfully stopped, right click the same icon and click ‘Remove local cluster’
In this tutorial we’ve covered the very basics of how we can create and deploy a Service Fabric application and demonstrated the stateful capabilities it affords us. However, Service Fabric has so much more to offer and can enable you to build application you simply couldn’t build any other way.
Service Fabric documentation http://aka.ms/servicefabricdocs
Free hosted Service Fabric party cluster at http://aka.ms/tryazureservicefabric.
Learn more by watching content at http://Channel9.msdn.com
Service Fabric resources https://azure.microsoft.com/en-us/documentation/videos/index/?services=service-fabric