*Words of Wisdom From The Elder

Windows Communication Foundation (henceforth abbreviated as WCF) supports multiple bindings that allows developers to expose their services in a variety of ways.  What this means is a developer can create a service once and then expose it to support net.tcp:// or http:// and various versions of http:// (Soap1.1, Soap1.2, WS*, JSON, etc).  This can be useful if a service crosses boundaries between intranet and extranet applications for example.  This article walks through the steps to configure a service to support multiple bindings with Visual Studio 2008 and the .Net 3.5 framework.  For those that want to jump directly to the sample solution it can be found at the end of this article.

Setting Up The Test Solution

Below you will find the steps used to create the sample solution.  I’ll explain a few WCF concepts along the way but probably not all of them.  I will however link to relevant documentation where applicable.  To get started, within Visual Studio 2008 create a new WCF Service Application project.  This template can be found within the web section of Visual Studio 2008 as seen here.

After the project is initialized modify it so it contains four files, note this will require deleting the default files:  IMyService.cs, Service.cs, Service.svc, and Web.Config.  Once you have cleaned up the default template, it should look like this:

Creating Our Service Contract
The IMyService.cs file will contain our service contract.   In old ASMX services, in order to expose a method as a service one would attribute the method with the attribute of [WebMethod].  In WCF, everything is tied to a Service Contract.   By defining our service contract as an interface, any class that implements that interface can be exposed as a WCF service.  In order to achieve this a ServiceContract attribute will be placed on the interface and an OperationContract attribute will be placed on the method we want to expose for our service.  Our interface is going to be simple and will just contain one method to add two numbers.  Here is the sample.

[ServiceContract(Namespace="http://keithelder.net/Learn/WCF")]

    public interface IMyService

    {

        [OperationContract]

        int AddTwoNumbers(int x, int y);

    }

Implementing The Contract
The Service.cs file will contain the implementation of the IMyService interface.  Again, since we defined our contract as an interface our service class doesn’t need or have any attributes on it.  Here is the code:

    public class Service : IMyService
    {
        public int AddTwoNumbers(int x, int y)
        {
            return x + y;
        }
    }

Creating The Service Host
The file Service.svc will provide the endpoint for our URL that will be exposed by IIS.   Within this file, we only need one line which identifies the class that contains our service using the ServiceHost directive.  Here is the code for this file.

<%@ ServiceHost Language="C#" Debug="true" Service="WcfService1.Service" CodeBehind="Service.cs" %>

Now that we have the contract specified and implemented along with an endpoint to host the service everything from here on out is just configuration.  This is the beauty of WCF.   How we want the service to be exposed is stored within the web.config file.  There a lot of options in WCF and those just learning WCF are typically overwhelmed at the amount of options.  Luckily Microsoft has a tool to help us along.  The upside to this approach is we do not have to code how our service is secured as we did in older ASMX services.

Setting Up Basic Http Binding

Before we add multiple bindings to our single service, let’s focus on adding one binding.  In order to configure our service we are going to use the Microsoft Service Configuration Editor.  This editor allows us to configure our WCF service and can be launched right from Visual Studio.  To launch the editor, right click on the web.config file.  An option should be in the menu that says “Edit WCF Configuration”.  If it doesn’t don’t worry, sometimes, Visual Studio doesn’t pickup this option.  A trick is to go to the tools menu in Visual Studio and select the editor from there.  After the editor is launched it will then show up in the menu when you right click the web.config file.

For this example I have removed everything from the web.config file before launching so I can configure the service completely from scratch.  Opening the web.config with the editor shows a blank configuration as follows.

Follow the steps to initialize the configuration.

Step 1
Make sure your solution builds.

Step 2
Click “Create a New Service” in the right panel of the editor.

Step 3
Browse to the bin directory and select the WcfService1.dll (if the file doesn’t show up, go back to step 1)

Double click this file and select your service implementation.

Step 4
The service type should be displayed on the previous screen.  Press Next->.

Step 5
Select the contract.  This should automatically be selected to WcfService1.IMyService.  Press Next->.

Step 6
Since we are using IIS to host our service select the HTTP option for the communication mode.

Step 7
Select the basic web services interoperability.  We’ll come back later on and add advance web services interoperability.

Step 8
Delete the “http://” from the address field.  Since we are developing we don’t know which port this will get assigned as of yet.

Press Next->.  A dialog will appear.  Select Yes.

Press Finish on the next screen.

At this point we have an almost configured service.  If you drill down into the Services folder within the tool down to the end point the configuration should look something like this.

Step 9
Let’s clean up our configuration.  In the screen shot above in the configuration section.  Give this endpoint a name of “Basic”.  This will let us know later on this endpoint is our BasicHttpBinding configuration which supports the SOAP1.1 protocol.

Step 10
Click on the “Services” folder in the editor.

Step 11
Next to the binding configuration there is a link that says “Click to Create”.  Click this link to create a binding configuration.  While this isn’t necessary in all instances it is a good practice to have a binding configuration.  This gives you more control over how your binding is configured and is a good practice to initialize early on.

Clicking this link will create a new binding.  In the name field under the configuration section, give it a name of “Basic”.  The defaults for this example are fine.

Note:  Clicking on the Security tab in the above screen the Mode should be set to None. 

At this point you should be able to save your configuration and press F5 in Visual Studio to launch your service in debug mode.  You should be presented with a web page that looks like the following:

Exposing Our Service’s WSDL

Unlike previous ASMX services, the WSDL (web service definition language) for WCF services is not automatically generated.  The previous image even tells us that “Metadata publishing for this service is currently disabled.”.  This is because we haven’t configured our service to expose any meta data about it.  To expose a WSDL for a service we need to configure our service to provide meta information.  Note:  The mexHttpBinding is also used to share meta information about a service.  While the name isn’t very “gump” it stands for Meta Data Exchange.  To get started configuring the service to expose the WSDL follow the following steps.

Step 1
Under the Advanced folder in the editor, select the “Service Behaviors”.

Click the “New Service Behavior Configuration” link in the right pane.

Step 2
Name the behavior “ServiceBehavior”.  In the bottom section press the add button and select the “serviceMetaData” option and press Add.

The end result should look like the following.

Step 3
Under the “Service Behaviors” folder, select the newly created “ServiceBehavior” option and then the “serviceMetadata” option underneath that.  In the right pane change the HttpGetEnabled to True.

Step 4
Select the service under the Services folder and apply the new service behavior to the service.

Step 5
Save the configuration and reload the service in the browser.  The page should be changed to the following:

Clicking on the link should display the WSDL for the service.

At this point our service is configured to support the SOAP1.1 protocol through the BasicHttpBinding and is also exposing the WSDL for the service. What if we want to also expose the service with the SOAP1.2 protocol and support secure and non-secure messages?  No problem.  We can expose the service all of those ways without touching any code only the configuration.

Adding More Bindings and Endpoints To Our Service

Now that we have the basic binding working let’s expose two additional endpoints for our service which support the WS* protocol but are configured differently.  We’ll expose a plain SOAP1.2 protocol message using the wsHttpBinding that is a plain message as well as a secured message using the wsHttpBinding.

Step 1
Under the Services folder select the EndPoints folder for the service and add a new service endpoint.  Give it a name of WsPlain.  This endpoint will serve as a standard SOAP1.2 message that isn’t encrypted.  Change the binding to wsHttpBinding.  In the address field, copy the address from your browser.  In my case, my project used the address of http://localhost:5606/Service.svc.  Paste this into the address field and add /WsPlain to the end of it so it looks like the following:

http://localhost:5606/Service.svc/WsPlain 

Each binding for each endpoint has to have a separate address.  Doing it this way allows us to keep our one service file and offer it up in various configurations.  In the contract option browse to the DLL in the bin directory and select the contract used previously.  The end result should look similar to this:

Step 2
Just as we did previously, click on the Services folder and create a binding configuration for this endpoint.  Refer to step 10 and 11 above.

Provide a name of WsPlain for the new binding.  In the security tab change the mode to “None” and set all other options to false or none.  This is setting up our binding so there is no security on our message.  By default the binding is configured to be secure.

The final settings for the WsPlain endpoint should be similar to this.

Step 3
To configure a secure binding using wsHttpBinding follow these same steps above but leave the default values in the security tab of the binding configuration.  Call this end point and binding WsSecured.  The new endpoint should look like this:

That’s it, our service is now configured three different ways and is configured to support SOAP1.1, SOAP1.2 and WS*.  Pretty cool huh?

Testing Our Service

Now that our service is configured with three different bindings, let’s look at the messages as they go back and forth across the wire.  In order to do this we are going to borrow knowledge from a previous article I did called “How to Get Around WCF’s Lack of a Preview Web Page and Viewing WCF Messages“.  From this article we are going to borrow the MessageViewerInspector class and build a small windows application to view our messages.

If you are still following along, add a new project of type Windows Application to the existing solution and then copy the MessageViewerInspector class from the referenced article and add it to the project.

If you have been following along you may have noticed that we only have one WSDL.  The WSDL contains all of our endpoints.  Even though we have three endpoints, we still only have one WSDL.  In testing with some third party clients my experience has been that clients only generate proxies for the endpoints they understand.  Add a service reference to the service to the windows application.

For the user interface I decided to use several split panels and create a three panel layout.  Here is what it looks like.

The idea is simple.  When I click on each button I want it to invoke my service and then display the request and response messages the service is using.  To do this I created one service method called CallService which is passed the end point name the service is to invoke.

        private void CallService(string endPoint)
        {
            MessageViewerInspector inspector = new MessageViewerInspector();

            ServiceReference1.MyServiceClient proxy = new WindowsFormsApplication1.ServiceReference1.MyServiceClient(endPoint);

            proxy.Endpoint.Behaviors.Add(inspector);
            proxy.AddTwoNumbers(12332, 12323);
            proxy.Close();

            richTextBox1.Text = inspector.RequestMessage;
            richTextBox2.Text = inspector.ResponseMessage;
        }

The endpoint is the name of the endpoint we specified in our configuration.  For example to invoke the secure wsHttpBinding it is called like this.

CallService("WsSecured");

The first thing created is create the inspector so messages can be viewed coming in and out of the proxy class.  Once the proxy method is called we can then grab the messages and put them into the RichTextBox control on the form.  Here are screen shots of each call to the service.

BasicHttpBinding – SOAP1.1

WsHttpBinding – SOAP1.2 Plain / Unsecured

WsHttpBinding – SOAP1.2 Secured

Conclusion

WCF services are powerful as you have just seen.  It is possible to expose a single service in more ways than just one.  This allows developers to support things like net.tcp binary messages and SOAP messages from the same service.  If you are an enterprise developer supporting multiple clients this is a blessing since it means .Net consumers of your service can use TCP while other consumers use WS*.  The nice thing is the developer doesn’t have to code it, just declaratively express how he wants the service configured. 

Download Sample Solution:

Like this article?