As part of the introduction to this chapter, we looked at the difference between stateful and stateless microservices. The Service Fabric application templates available are then further divided into Reliable Services (stateful/stateless) and Reliable Actors (stateful/stateless). When to use which one is something that will depend on the specific business requirement of your application.
To put it simply though, if you wanted to create a service that should be exposed to many users of your application at any one time, a Reliable Service would probably be a good fit. Think of a service exposing the latest exchange rates that can be consumed by many users or applications at once.
Again, looking back to the introduction of this chapter, we used the example of an online web store with a shopping cart. A Reliable Actor could be a good fit for every customer buying items, so you could have a shopping cart actor. The Reliable Actor as part of the Service Fabric framework is based on the Virtual Actor pattern. Have a look at the article on the Virtual Actor pattern at http://research.microsoft.com/en-us/projects/orleans/.
To show you how easy it is to create a microservice using a stateless actor service as an example, we will use Visual Studio to publish a service to the Service Fabric cluster and call that service from a console (client) application.
To complete this recipe, you must ensure that you have installed your local Service Fabric cluster on your local machine.
- In Visual Studio, create a new project by going to File | New | Project:
- From the Visual C# node, expand the nodes until you see the Cloud node. When you click on it, you will see that Visual Studio now lists a new Service Fabric Application template. Select the Service Fabric Application template, call it
sfApp, and click on OK:
- Next, select Stateless Reliable Actor from the Create a Service window that pops up. We just called ours
UtilitiesActor:
- Once your solution is created, you will notice that it consists of three projects. These are:
sfAppUtilitiesActorUtilitiesActor.Interfaces
- We will start off by modifying the
IUtilitiesActorinterface. This interface will simply require thatUtilitiesActorimplements a method calledValidateEmailAsyncthat takes an e-mail address as a parameter and returns a Boolean value indicating whether it is a valid email address or not:namespace UtilitiesActor.Interfaces { public interface IUtilitiesActor : IActor { Task<bool> ValidateEmailAsync(string emailToValidate); } } - Next, open up your
UtilitiesActorproject and view the class. It will be underlined with a red squiggly line because it does not implement the interface memberValidateEmailAsync():
- Using Ctrl + . (period), implement the interface. Remove all the other unnecessary default code (if any):
- The implemented interface code inserted for you should look like this. At the moment, it only contains
NotImplementedException. It is here that we will implement the code to validate the e-mail address:namespace UtilitiesActor { internal class UtilitiesActor : StatelessActor, IUtilitiesActor { public Task<bool> ValidateEmailAsync(string emailToValidate) { throw new NotImplementedException(); } } } - We will use a regular expression to validate the e-mail address passed to this method via the parameter. Regular expressions are very powerful. I have, however, in all my years of programming, never written my own expression. These are readily available on the Internet, and you can create a utilities class (or extension methods class) for your own projects to reuse. You can make use of regular expressions and other code that is often used.
Finally, you will notice the
ActorEventSourcecode. This is simply just to create Event Tracing for Windows (ETW) events that will help you see what is happening in your application from the diagnostic events window in Visual Studio. To open the diagnostic events window, go to View, Other Windows and click on Diagnostic Events Viewer:internal class UtilitiesActor : StatelessActor, IUtilitiesActor { public async Task<bool> ValidateEmailAsync(string emailToValidate) { ActorEventSource.Current.ActorMessage(this, "Email Validation"); return await Task.FromResult(Regex.IsMatch(emailToValidate, @"A(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:.[a-z0- 9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9- ]*[a-z0-9])?.)+[a-z0-9](?:[a-z0-9-]*[a-z0- 9])?)", RegexOptions.IgnoreCase)); } } - Be sure to add a reference to the
System.Text.RegularExpressionsnamespace. Without it, you will not be able to use the regular expressions. If you added the regular expression in your code without adding the reference, Visual Studio will display a red squiggly line under theRegexmethod:
- Using Ctrl + . (period), add the
usingstatement to your project. This will bring the regular expression namespace into scope:
- Now that we have created the interface and also added the implementation of that interface, it is time to add a client application that we will use for testing. Right-click on your solution and add a new project:
- The easiest way is to add a simple console application. Call your client application
sfApp.Clientand click on the OK button:
- After you have added your console application to your solution, your solution should look like this:
- You will now need to add references to your client application. Right-click the References node in your
sfApp.Clientproject and select Add Reference from the context menu:
- Start off by adding a reference to the
UtilitiesActor.Interfacesproject:
- You will also need to add references to several Service Fabric dynamic link libraries (DLLs). When you created your Service Fabric application, it should have added a folder called
packagesto your project folder structure. Browse to this folder and add your Service Fabric DLLs from there. After you have added the required DLLs, your project should look like this:
- In the
Program.csfile of your console application, you need to add the following code to theMainmethod:namespace sfApp.Client { class Program { static void Main(string[] args) { var actProxy = ActorProxy.Create<IUtilitiesActor> (ActorId.NewId(), "fabric:/sfApp"); WriteLine("Utilities Actor {0} - Valid Email?: {1}", actProxy.GetActorId(), actProxy.ValidateEmailAsync ("[email protected]").Result); WriteLine("Utilities Actor {0} - Valid Email?: {1}", actProxy.GetActorId(), actProxy.ValidateEmailAsync ("invalid@[email protected]").Result); ReadLine(); } } }All we are doing is creating a proxy for our actor and writing the output of the e-mail validation to the console window. Your client application is now ready.
- Before we can run the client application, however, we need to publish our service first. In Solution Explorer, right-click on the
sfAppservice and click on Publish from the context menu:
- The Publish Service Fabric Application window will now be displayed. Click on the Select… button next to the Connection endpoint text box:
- Select Local Cluster as your Connection endpoint and click on OK:
- Change Target profile and Application Parameters File to
Local.xml. When you are done, click on the Publish button:
- If you navigate to
http://localhost:19080/Explorer, you will notice that the service you created has been published to your local Service Fabric cluster:
- You are now ready to run your client application. Right-click on the
sfApp.Clientproject, and select Debug and Start new instance from the context menu:
- The console application calls the validate method to check the e-mail addresses, and displays the results to the console window. The results are as expected:
- We can, however, be more specific when creating the actor ID. We can give it a specific name. Modify your proxy code and create a new
ActorIdmethod, and give it any string value:var actProxy = ActorProxy.Create<IUtilitiesActor>(new ActorId("Utilities"), "fabric:/sfApp"); WriteLine("Utilities Actor {0} - Valid Email?: {1}", actProxy.GetActorId(), actProxy.ValidateEmailAsync("[email protected]").Result) ; WriteLine("Utilities Actor {0} - Valid Email?: {1}", actProxy.GetActorId(), actProxy.ValidateEmailAsync("invalid@[email protected]").Resu lt); ReadLine(); - When you debug your client application again, you will notice that
Utilities Actornow has a logical name (the same name you passed as a string value when creating a newActorIdmethod):
Creating your Service Fabric application and publishing it locally is a perfect solution for testing your application before publishing it to the cloud. Creating small independent microservices allows developers many benefits related to testing, debugging, and deploying efficient and robust code that your applications can leverage to ensure maximum availability.