HXF Web Services Quick Tutorial
This tutorial shows how to create a light-weight web service based on HXF.
Download HXF release 1.2 from here.
Create a new solution in Visual Studio, the "ASP.NET Empty Web Application" is the recommended template for this tutorial. Set the name of the web project to something like "HXFWebService" and the solution name to "HXFTest".
Add the following assemblies to your newly created project.
- HXF.Common.dll
- HXF.WebServices.dll
- HXF.WebServices.Server.dll
- Newtonsoft.Json.dll
HXF allows you to expose any POCI (Plain Old C# Interface, or to be more accurate any .net interface written in any .net language) as a web service, you are not required to implement any custom interfaces nor using any special attributes, and there is no restriction on the types you can return from your web methods.
Create a new interface and name it as ISampleService, add two methods to the interface as below.
public interface ISampleService
{
string SayHello(string name);
int Sum(int x, int y);
}Create also a new class named SampleService that implements the above interface as below.
public class SampleService: ISampleService
{
public string SayHello(string name)
{
return "Hello, " + name;
}
public int Sum(int x, int y)
{
return x + y;
}
}That's all you need from your side. It is time now to expose the above interface as a HXF web service.
Add a Generic Handler to your project and name it as "Service.ashx" for example, the code for the new handler will look like below.
public class Service : IHttpHandler
{
public void ProcessRequest(HttpContext context)
{
context.Response.ContentType = "text/plain";
context.Response.Write("Hello World");
}
public bool IsReusable
{
get
{
return false;
}
}
}The core of HXF-WS depends on a the HxfHandler class which implements IHttpHandler. So, You are going to change your handler code to make it extend HxfHandler instead of implementing IHttpHandler directly. You will also write a constructor in your handler to tell the HXF what interfaces are you going to expose as services. Note that you can use a single handler to expose multiple interfaces as one service.
Change your handler code to look as below.
public class Service : HxfHandler
{
public Service()
{
ServiceConfig sconf = new ServiceConfig("sample", "Sample HXF Service");
sconf.AddInterfaceConfig("SampleService", "sample service", typeof(ISampleService), typeof(SampleService));
this.runtimeConfig.ServiceConfig = sconf;
}
}The above code shows how simple it is to expose an interface as a web service, as you can see, you need only to create a ServiceConfig instance and add the interfaces you need to be exposed to it, the last line assigns your ServiceConfig instance to the runtimeConfig property of HxfHandler. You can use runtimeConfig to customize the handler such as enabling CORS or adding a latency to your service. This is covered in other tutorials.
It is now the time to check if your service is running correctly. To do this, run your web project and navigate to your generic handler, Visual Studio doesn't allow a handler to be set as a start up page so you might need to enter the URL for the handler manually in your browser. The image below shows what you should see when you navigate to the handler URL.
HXF-WS depends on a simple JSON-based language to describe the web service, the service descriptor serves as a standard way to describe the service. Click on "View Service Description" link to see the service description of your service, you should see something like this:
{
"Name": "sample",
"Platform": "DOTNET",
"Description": "Sample HXF Service",
"Url": null,
"Interfaces": [
{
"Name": "SampleService",
"Description": "sample service",
"Methods": [
{
"Name": "SayHello",
"Description": null,
"Parameters": [
{
"Name": "name",
"Description": null,
"Type": "String"
}
],
"ReturnType": "String"
},
{
"Name": "Sum",
"Description": null,
"Parameters": [
{
"Name": "x",
"Description": null,
"Type": "Int32"
},
{
"Name": "y",
"Description": null,
"Type": "Int32"
}
],
"ReturnType": "Int32"
}
]
}
]
}The next section will show you how to consume the service you created.
HXF-WS promotes support for several types of clients as you may noticed. It is possible to consume the same service from several clients such as .net, Java, Android, JavaScript and others. The simplicity of the used standards in HXF-WS allows to add support to other types of clients easily while preserving functionality and efficiency.
In this section you are going to consume the above service from a console application.
Add a new console application to your solution and name it something like "TestClient", add the "Newtonsoft.Json.dll" assembly to your console application. it can be found in the downloaded archive of HXF.
Download the proxy source code for C# from the web service handler page (Click on C# link), extract the downloaded zip archive. The archive will contain one C# file for each exposed interface. Add the extracted C# file to your project. this file will contain the proxy source code to make it easy to consume your service, note that you need to set the correct URL for your service, so change the line:
private const string SERVICE_URL = "";to have SERVICE_URL assigned to your service URL, in our case it becomes:
private const string SERVICE_URL = "http://localhost:53144/Service.ashx";The code below shows how to consume the service.
static void Main(string[] args)
{
SampleServiceClient client = new SampleServiceClient();
JObject j1 = client.SayHello("HXF");
Console.WriteLine(j1["Value"]);
JObject j2 = client.Sum(5, 3);
Console.WriteLine(j2["Value"]);
}You should have your console print "Hello, HXF" and 8.
This tutorial explained how to consume a simple HXF service from a C# client, it is up to you to try consuming the service from other supported clients as well.