ServiceStack – Writing C# clients for services

Today lets create a client application for our simple Flight Service using C# code. Writing clients for ServiceStack services using C# is super easy! If you have worked with older  web service related technologies, you may know by experience how difficult it is to create xml requests, serialise data, de-serialise data and etc. At the end of this example you’ll realise how easy it is writing C# client code to consume a service developed using ServiceStack.

First we need to add a consumer project into the solution. For this demonstration, I am going to use a Windows Console Application as my client and I name it “ServiceConsumer”.


Next, we should add a reference to ServiceStack.Client namespace within our client project. To get this done, right-click on the project and select Manage NuGet Packages… from the context menu.


Then search for ServiceStack.Client and click Install.


This will add the ServiceStack.Client and other supporting ServiceStack references into our client project.


Next, we should  add the reference to our service project (see below).


Now, we are ready to go ahead and write our client code.

If you could remember, our FlightRequest class included two properties, Departure and Arrival. Basically, I am going to write a console application that creates an instance of this request class, populates its Departure and Arrival properties with values passed into the application and pass that request into the service. Finally, I will be writing some code to display the content of the response returned from the service. The following piece of code does it all…


The most important lines in the above code are line 16 and 17. In line 16, I create a new JSON client. Here, I create a new JsonServiceClient object by passing in the base URI of the service. The best way to get the base URI is to launch the service and copy the base address from the service URL (see below).


You may create other types of clients that could be used with request types such as XML, CSV, SOAP and etc. too. I will show how to create such clients later in this post.

In line 17, I create a new FlightRequest object, assign its two properties with values passed into the application and then pass it to the Post() method of the client. The other parameter that I pass into the Post() method is the desired route to use. If you remember, I had two routes defined for FlightRequest class so, I specify which route that I need to use.  Also, note that I specify the response type in the method call in order to receive a strongly typed response back from the service.

Finally, I have written some code (line 22 to 31) to display the content of response I’ve got back. now, if you press F5 it will start debugging the service. To get the client application kicked off follow, right-click on the client project -> Debug -> Start new instance.


The following screenshot shows the output response for a sample run of the client application with two input parameters supplied.


In the above example, we used a JsonServiceClient class to initiate a JSON request to the service. As I mentioned before, there are other client classes available to us as well. You may replace line 16 with the following line of code to initiate an XML request. The client application should still function as before.

var client = new XmlServiceClient(“http://localhost:63808”);

The following code lines could be used to create JSV, SOAP 1.1 and SOAP 1.2 clients respectively.

var client = new JsvServiceClient(“http://localhost:63808”);

var client = new Soap11ServiceClient(“http://localhost:63808”);

var client = new Soap12ServiceClient(“http://localhost:63808”);

The client code that I’ve written worked fine but, we can further simplify this code to make it look more simple and sleek. We had to specify the response type in the Post() method but, with a small tweak in the FlightRequest class, we can get rid of this from our client code. All we have to do is to slightly change the FlightRequest class as shown below.


Here, we declare the expected response type related to our request type. Simply, we say that our FlightService returns an object of type FlightResponse when we post a FlightRequest object into the service.

We may even remove the route name parameter from the Post() method call as ServiceStack is intelligent enough to inspect the routes associate with the our request type and sort out the appropriate route to use! So, our simplified client code looks like the following.


And, our client program still runs with no troubles!


Posted in ServiceStack | Tagged | Leave a comment

ServiceStack – more on Routes

In my last post, we discovered Routes in ServiceStack. Today let’s go bit further and find out what’s more we could do with routes in ServiceStack. Remember we specified one route for FlightRequest class of our simple Flight Service. That doesn’t mean we are only allowed to add one route per request class in ServiceStack. We may define multiple routes for a selected request and enjoy variety of behaviours. Sounds cool isn’t it? Let’s go ahead and see how to do this.

Here, I am going to add one more route for our FlightRequest class. Since our request object just contains two properties (Departure and Arrival), I am going to define a new route to which, we could directly pass Departure and Arrival parameters instead of passing a populated request object (see below).We are going to use the POST verb for our new route too.


We may still use our first route with a request object that has been populated with Arrival and Departure fields. But, in this example, we are going to use our new route with Arrival and Departure parameters been directly passed into the service URL without using a request object at all.

Now press F5 to start debugging and you would see that our new route is available to use straight away.


Now let’s use this new service URL to invoke a service request via the REST Console tool. Let’s perform an XML request this time. All you need to do is to specify the Departure and Arrival cities within the URL, specify the content type as application/xml and press POST button. You don’t need to worry about the payload as we are not passing a request object this time.


You should be able to get the expected response as shown below.


It is important to take a step back and realise what actually happened here. One important thing to understand is that ServiceStack promotes convention based practice not configuration based practice. Have I done any configuration changes at all to get this behaviour? NO. All I did was specifying a new route with Departure and Arrival parameters built into it. However, when I was defining the new route, I used the exact names of the two properties of the request class.


By doing so, I signaled ServiceStack to use those two URL parameters in place of the actual request object. ServiceStack was smart enough to understand my “notation”, create a FlightRequest object behind the scenes and assign those two parameter values into the Departure and Arrival properties. I can prove my point by placing a breakpoint inside the FlightService operation method and invoking the same service request via the REST Console again!


As you can see, ServiceStack has managed to populate a FlightRequest object using the URL parameters supplied in the route URL.

Posted in ServiceStack | Tagged | Leave a comment

ServiceStack – Use routes to customise service endpoints

Today, let’s further enhance our simple Flight Service example that I have developed during my last two posts. One problem we have with our service is its service endpoint URL. If you could remember, last time we used a JSON specific request to test the service. Our service URL looked like the following.


But, if we want to test our service with an XML request then, we can’t use the above service endpoint since it is a JSON specific one. Therefore, we have to produce the XML specific URL using the operations’ XML request specifications.


Hence, our XML specific URL becomes the following.


Now, you get it! Our service URL differs based on the request format that we are willing to use. Isn’t it cool if we could define one service endpoint URL for all request formats? That is exactly what we are going to achieve today using the “Route” functionality of ServiceStack.

Remember, last time I mentioned you that ServiceStack is a very powerful tool that could be used to develop state of art REST APIs. The power of RESTful services hinges around the URL formats. Routes play a vital role when it comes to developing REST APIs using ServiceStack.

Now, let’s go ahead and add a route to our FlightRequest class (see below).


Remember, we add routes to request class not to service class. Hence, one service can have different service URLs that belong to different request types. In this example I have used the POST verb option for the route.

Now, press F5 to debug the service. If you go and inspect request details for JSON then, you’ll see that our newly defined route is available to use now.


Our service URL becomes much simpler too.


Please note that the port number of the above address (happen to be 63808 in my local environment) could be a different one if you run this demonstration in your local environment. So, make sure that you replace 63808 with your local port number.

Let’s use this new service URL in REST Console tool to perform a JSON request. Fill in the required REST Console fields as shown below and press POST button.


Inspect the response and see that we have received our expected response in JSON format.


Don’t’ worry about the ArrivalTime and DepartureTime response values as those values are encoded in JASON date/time format which is not very readable.

Now, let’s use the same service URL against an XML request. We can use the sample XML given in XML request specification of the service operation to produce the XML request.


We have to change the request details in REST Console as shown below. Remember, to keep the Request URI unchanged. Press POST button.


Inspect the response and verify that we have received the expected response in XML format.


That’s it! We specified a RESTful URL using Routes in ServiceStack and tested it with JSON and XML request successfully.

Posted in ServiceStack | Tagged , | 1 Comment

ServiceStack – Testing services with Chrome REST Console

My favourite tool for testing RESTful services is the Chrome plugin, “REST Console”. Since ServiceStack is an ideal framework to build REST APIs, REST Console is an excellent tool to accompany ServiceStack. Let’s see how to use free Chrome REST Console tool to test a service. For this demonstration, I am going to use the simple Flight Service that I created previously.

First and foremost, we must install REST Console into Chrome browser. If you don’t have Chrome browser installed in your computer please download it from Google and install it first. Visit using Chrome browser and search for “Chrome Web Store” and click on the relevant link to visit Chrome Web Store.

Now search for “REST Console” in Chrome Web Store and hit on the +FREE button to install it into the browser.


Now you’ll notice that REST Console is available in your Chrome Apps.


Click on the application icon to launch REST Console. You should now see something similar to the following.


Now, let’s launch the Flight Service that we have created during the previous demonstration.


In this example let’s try to replicate the JSON request through REST Console and see how it works. So, click on the JSON link on the Operations section to view the details that we need to perform a service call to our Flight Service via REST Console.


In order to generate the service URL of the service, we’ll have to combine the base address (http://localhost:63808) with the default service URL (/json/oneway/FlightRequest) so, the complete URL becomes the following.

Please note that the port number of the base address (happen to be 63808 in my local environment) could be a different one if you run this demonstration in your local environment. So, make sure that you replace 63808 with your local port number.

Specify the service URL in the Request URI box.


Next, enable the content-type by clicking on the checkbox and then, specify application/json request type.


Finally, we should specify our request payload in JSON format.


Now, we may go ahead and click on the POST button. This will cause REST Console to invoke our Flight Service with supplied request payload and, the resulting response should be observable in the response section.


As we have expected, Arrival and Departure fields are populated from the request that we sent and, values for other properties are also populated. Don’t’ worry about the ArrivalTime and DepartureTime values as those values are encoded in JASON format which is not very readable.

Posted in ServiceStack | Tagged | Leave a comment

Getting started with ServiceStack – Creating a service

ServiceStack is a powerful platform that allows developers to do lots of different thinks. It is an alternative to popular Microsoft technologies WCF, ASP.NET MVC and WebAPI. It promotes true platform independence, high performance, lesser configuration mess (oh yes!) and above all, simplicity. Let’s see how to get started with creating services using ServiceStack.
In this simple example I will be trying to replicate a Flight Service in the Travel industry. I am going to use an ASP.NET web application as the host of this service for simplicity. So, the first step is to add a new empty ASP.NET web application in a VisualStudio solution.


Next, we need to add required ServiceStack references into the project. I am using NuGet package manager to get this done.


Make sure that you have following references added into the project.


Next, change the content of Web.config of the web project as shown below in order to enable ServiceStack.


Now, we can go ahead and create the service. Creating a service using ServiceStack is super easy! As discussed earlier, let’s add a simple service to imitate the behaviour of a flight service. This service receives a request that specifies Arrival and Departure points and returns a response with the lowest fare. First, let’s add classes for request


As you can see, the request class is very simple. as it only specify departure and arrival ports. Now, lets define the response.


The response contains the lowest fare and other important data such as selected airline and times of departure and arrival at the destination.

Now we can create the service class. Creating a service in ServiceStack is very simple. All we need to do is to make sure that the service is inherited from ServiceStack.Service class. I have defined just one simple operation in the service called Post() that accepts a FlightRequest object and returns a FlightResponse object. We are not going to do anything intelligent inside the service operation in this demonstration. I have assigned some arbitrary values to the response object to mimic some business functionality.


We are done with the service now. See how easy it is! In order to host the newly designed service, we need to create an application host class. Let’s call it FlightAppHost.


This class inherits from ServiceStack.AppHostBase abstract class. We must override the Configure() method of this base class. Inside the Configure() method we have the option to configure the service. We’re going to skip that step for this example. Also, note that we are using an IoC container called Func which is one of the fastest IoC containers available at the present.

To get the service host bootstrapped, we need to start the application host that we’ve just developed. Let’s add the following piece of code into the Application_Start event in the Global.asax file so, that the service host is launched when the web application is started.


Now we are ready to fire up our service and test whether it is working. Just press F5 to start debugging the web application and you could see that the service starts in your default browser.


You can see that the request type used in the operation of the FlightService has been identified as the operation of the service (of course, we may add more operations if we wish to). You may also notice that different types of sample requests and responses (XML, JSON, JSV, etc.) that you may use with this operation can also be viewed by clicking on the corresponding link.
That’s it! You have just created a service using ServiceStack!

Posted in ServiceStack | Tagged | 4 Comments

Hello world!

Welcome to This is your first post. Edit or delete it and start blogging!

Posted in Uncategorized | 1 Comment