REST services

Sometimes SOAP might actually be overkilled for particular web service scenarios. In many cases the developer may need high range of interoperability. So, in order to increase interoperability, they have to restrict themselfs to basic XML message that they transmit over HTTP and they can take advantage of advance WS* specifications that are part of these protocols.

For security, they simply use HTTPS that provides facility of SSL for all the security needs.This is most common today. Most of the developer are using SOAP without WS* and this is often referred to as simple SOAP. Main benefit of doing this is it increases interoperability. Also, there is large number of tool support for generating clients & services from WSDL definition. We can take WSDL schema definition and automatically generate the code that we need without our framework and that code will hide all the underlying XML & HTTP details. This is why, most of the developer still use SOAP.

Some developer decide that they really don't need SOAP at all & just want to exchange XML messages over HTTP without SOAP framing element. This is often referred as plain-old XML (POX). This is usually used in combination with HTTP. When you take this approach, the interoperability is virtually guaranteed because you can easily find HTTP & XML stack on any platform in demand today. But it does require some direct XML / HTML coding.

In order to use POX, you should be comfortable writing XML based code using various XML APIs to produce & consume messages and you also need to be comfortable with HTTP stack for programming the logic to send & receive messages.

POX applications can also be defined in a REST-ful way. If you design your services around HTTP and if you are adhered to restful design principals and you define all your actions in terms of HTTP method & verbs, then indeed you are going to use what we call as RESTful architecture that happens to use plain-old XML messages over wire. 

WCF - Handling Exceptions

There may be many different kinds of exceptions that may occur at the client side. But client channels need to be prepared for two main exception types :

1. Communication Exceptions - This is a base class that represent various runtime communication errors. This exception is a generalize exception to catch any type of communication exception that is thrown by your service operation also known as Fault Exception. They typically represent business oriented exceptions.

2. Timeout Exception - It is not delivered from communication exception. This represents the error that occurs when send timeout limit exceeded. So when you are writing your client side communication logic, you need to take it into account these various types of exceptions that can occur. Remember that after certain exceptions, the client side channel may enter into "faulted" state which will require you to call abort on the channel instead of close.

To Catch Communication Exception :

catch(CommunicationException ce)
{
       client.Abort();
}

To Catch Timeout Exception :
catch(TimeoutException te)
{
       client.Abort();
}

Configure Client Channel - through Binding & Behaviors

You can configure client channel through both binding & behaviors applied to client scenario. The binding configures the wire level protocol detail, whereas , the behavior configures local execution environment.

Key things that you might configure on the client side binding :-

1. Send Timeout Value : this influence when the time out exception happens.

2. Transport Protocol specific setting : that usually has to be sync with service setting as well.

There are also some client side behavior that you can apply to your client side endpoints. That's why they are called client side endpoint behavior in WCF.

I. Configure client side binding :-

II. Configure client side behavior :-

Channel Life Cycle - How to Create, Use, Close and Abort a Channel in WCF

You create a channel by calling create ChannelFactory. Behind the scene when you say create channel, WCF will actually build the underline WCF runtime for transferring a message on the wire to the service. It returns you an object and implement the service contract type. When you do method calls, these method calls are translated into message on the wire through that underline channel stack. Now, all channels will also implement another interface called IClientChannel. This is a special interface in the channel life cycle. This will provide both - Close and Abort method you can use when you need to shut things down.

Let me take this example :

Here I have a ChannelFactory of type IInvoiceService as my service contract type which is targeting tcpEndpoint defined in web.config file.

To create a ChannelFactory I will simply call :

IInvoiceService channel = factory.CreateChannel(); 

This will give me an object back of IInvoiceService. Then, I actually want to send a message to the service that I will send by simply calling a method on the service contract type :

channel.SubmitInvoice(invoice);

And when I am done with my this channel, I can cast the channel object to IClientChannel and then call close method :

((IClientChannel)channel).Close();

Difference between Close and Abort

Close : 

1. Close performs graceful shutdown of the client channel

2. It waits for In-Progress calls to complete before closing things down

3. It closes underlying n/w resources

4. It doesn't close the channel before all the operations are completed

5. Close can throw few Exceptions (Communication Exception & Timeout Exception)

Abort:

1. It doesn't wait for anything to happen

2. When you are calling Abort, system assumes that you want to abort In-Progress calls & want to close the channel immediately. 

3. You call abort in a situation where something has gone wrong and you just need to clean the things as soon as possible.

4. Typically you call abort when you have "faulted" channels. In fact, you must call abort in this situation. If you try to call close on "faulted" channel, that will actually throw an another exception.

Both close & abort are found on IClientChannel interface and that interface will be available to all the channel objects returned by your ChannelFactory.

Note : You have to cast to IClientChannel inorder to call close/abort.

Specify Client Side Endpoints in WCF

When we create a ChannelFactory at the client side, we need to specify the client side endpoint. We can achive this at code as well as at the configuration page.

Through Code :

This code allow you to specify the binding type as well as the endpoint address.

This approach is used when we want to force a client to use a particular endpoint or you want to create a channel at runtime. You need to pass this endpoint information at the runtime.

The other way to do this is, tell the ChannelFactory to go and read the endpoint from the configuration file.

Through Config file :

 

httpEndpoint is a string. It is name of the endpoint found in the configuration file.

 

Let us see our configuration file, which will make the picture more clear :

 

 



It looks very similar to the server side config model except the tag '<'Client'>' specified in the config file which contain the endpoint .

Second difference is that here at client side we have an endpoint name, which we don't find in a service side endpoint tags in its config file.

We do specify the name of the endpoint at client side to refer that in our code.

 

How to Program Channels of WCF

To program channel of WCF, you need to first create & configure a ChannelFactory (a class) based upon one of the endpoint exposed by the service.

Then you create a channel instance through that ChannelFactory. Once you have channel, you can make method call through that channel calling the method contract.

Once you are done with the channel, you need to Close / Abort the channel.

Let me explain, how to create a ChannelFactory based upon a particular endpoint :

This is achieved through a special class called ChannelFactory :

ChannelFactory '<'ServiceContractName'>' ObjOfChannelFactory = new ChannelFactory'<'ServiceContractName'>' ("NameOfEndpoint") ;

 This allows you to create Channel, based upon specific contract type.

When you are done with construction of ChannelFactory of a particular type of ServiceContractName, you also supply target endpoint in its constructor ie, NameOfEndpoint.

Example :

 ChannelFactory '<'IInvoiceService'>' cf = new  ChannelFactory '<'IInvoiceService'>' ("HttpEndpoint");





Note : I have used single quote for angle bracket to avoid creating it a html tag. Don't include single quotes around the Service Contract Name while coding.
 
 

 

WCF Client Retrieving Endpoint definition

When we take a reference of a service at the client side, the client automatically generates endpoint definitions from WSDL. It can generate two things :

a. Code containing an equivalent service contract definition

b. Config information containing the endpoint definition

Let us take the following example : 

Here we have a service exposing several endpoints in the form of WSDL definition. Client retrieves that using metadata import tool, which generates two things : 

a. configuration file containing the client side endpoint definitions. 

b. .net contract definitions in the code format

These two things need to be compiled at the client side application & thus the programming model becomes symmetric to what is there at the service side.

How to do : 

1. Right click on the client project, add reference. 

2. Type the address of your metadata and hit enter. This will download the metadata and generate the code in the configuration file necessary for your client side endpoints.

3. Thus it automatically add those code lines and configuration in the project for you by merging the configuration file.

4. Finally it add a new thing in your project called a service reference.

WCF Architecture

A Step-by-Step approach of learning WCF architecture :

In any communication oriented scenario, there is always a service waits for messages to arrive and a client tries to consume the service. In WCF this happens with the help of metadata,WSDL definition, endpoint and channel. Let me take you to a step-by-step approach of WCF architecture and its functionality.

1. Service waits for message to arrive and on other side client wants to consume the service.

2. Like in network programming, we have sockets exposed by the server, here we have service exposing the metadata. To consume the service, client must be able to retrieve the metadata.

3. Service exposes the metadata, typically in the format of WSDL definition.

4. Client retrieve the WSDL definition & then run it through a client side metadata import tool.

5. This will produce client side endpoints that represents the information to communicate that service through one of the endpoints.

6. Client once has those endpoint definitions, can then choose any of the endpoint.

7. Client construct a channel based on the endpoint going to be used. Once the client has constructed the channel based on the endpoint, it can then begin sending messages to the service through that channel & can make method calls on the channel instance.

This completes the flow of WCF architecture (refer the figure above).

Introduction to WCF

Windows Communication Foundation (WCF) is formally know as "Indigo".

Following are the features of WCF :

1. WCF is truely service-oriented, loosely coupled and interoperable platform.

2. It simplifies service-oriented system design by removing the design dependencies between business functionality and actual implementation of the business functionality.

3.WCF promotes loose coupling not only between services and the functionality they expose, but also for choice of protocol, message encoding formats & hosting environment. For ex, services can be accessed over a variety of supported protocols (named pipes, TCP, HTTP and MSMQ)

4. WCF also support all of the core and emerging web service standards, which make it a highly interoperable platform.

5. Messages can always be represented in a format consistent with a set of well-adapted standards to communicate with other platforms.

6. You can now choose a single communication stack to gain access to the system services necessary to build a distributed system.

7. WCF unifies the disparity in the programming paradigm namely .net remoting, asp.net web services (.asmx) & enterprises services.