Eduzine© - WCF

Exploring Windows Communication Foundation - Part 2

eduzine@edujinionline.com (Eduzine) — Tue, 23 Jan 2007 12:47:34 -0700

In our second article of the series "Exploring Windows Communication Foundation", we explore the customization of the service and working with faults and errors. Specifically, we look at the following:

Hosting the service in IIS/ASP.Net Runtime
Customizing the details of a service contract, like the name of contract, namespace-URI to which it belongs etc
Customizing the details of an operation contract, like the name of contract, it's parameters, order etc

Downloads

The code for the project is available for download at Edujini Downloads in the Windows Communication Foundation category.

Hosting WCF Service in IIS/ASP.Net

To host a service in IIS/ASP.Net, we need to do the following:

Install IIS, if not already installed.
Register ASP.Net 2.0 with IIS, if not already registered.
Register WCF with IIS and ASP.Net 2.0.

If you have installed IIS and .Net Framework 2.0 Redistributable in this order, you do not need to register ASP.Net Runtime. You can check if ASP.Net Runtime is registered with a website or not by checking the properties of the website as shown below:

If the ASP.Net Runtime is not registered with IIS, execute the following on the commandline for the registration:

%windir%\Microsoft.Net\Framework\v2.0.50727\aspnet_regiis.exe -i

To register the WCF with IIS and ASP.Net 2.0, execute the following on the commandline:

ServiceModelReg.exe -i -x

The application ServiceModelReg.exe can be found in the folder "%windir%\Microsoft.Net\Framework\v3.0\Windows Communication Foundation". The -i option is for registering WCF with IIS and ASP.Net Runtime and -x option is to execute the custom action scripts also. The two important things that the registration does are registering .svc extension with IIS asking it to be handled by ASP.Net 2.0 Runtime and the registering .svc extension with the ASP.Net Runtime to be handled by its IHttpHandler.

The next step is to create an ASP.Net Website. Let's call it ShoppingCart. To the website created, add a new WCF service and name it ShoppingCartService.svc.

Incase you do not find the template for adding a new WCF service, don't be disheartened. You can simply add a new text file and name it ShoppingCartService.svc.

Open the ShoppingCartService.svc file if not already opened. Modify it to have the following contents:

<%@ ServiceHost Debug="true" Service="ShoppingCartLibrary.ShoppingCartImpl" %>

Create the folder Bin inside your project. Add the assembly ShoppingCartLibrary that we created in our previous article. If you don't have it, you can get it from the previous article. For all those working with Visual Studio, you may wish to delete the class ShoppingCartService created automatically for the code-behind, placed in App_Code folder. We don't need it.

Modify the configuration file web.config to include the following content:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <behaviors>
            <serviceBehaviors>
                <behavior name="HttpGetBehaviour">
                    <serviceMetadata httpGetEnabled="true"/>
                </behavior>
            </serviceBehaviors>
        </behaviors>
        <services>
            <service name="ShoppingCartLibrary.ShoppingCartImpl"
                behaviorConfiguration="HttpGetBehaviour">
                <endpoint binding="mexHttpBinding"
                    contract="ShoppingCartLibrary.IShoppingCartService" address=""/>
            </service>
        </services>
    </system.serviceModel>
</configuration>

Hurray! The service has been deployed. Browse to the location http://localhost/ShoppingCart/ShoppingCartService.svc. If you see the output as shown below, the scriptmaps are not registered appropriately.

In that case (or uncompiled output), execute the following on the commandline:

ServiceModelReg.exe -s:W3SVC/1/ROOT/ShoppingCart

Refresh the page in browser. Now, you should be able to see an output as shown below:

Updating the client

The next step is to update the client (proxy class and configuration) to connect to our new service.

Ah! We don't need to regenerate everything. Open the client application configuration file and modify the endpoint-address (in the section configuration/system.serviceModel/client/endpoint, the attribute address) with a value of http://localhost/ShoppingCart/ShoppingCartService.svc

The client should give identical results as what we got while working with self-hosted service (created in previous article).

Service Customization

Let us now look at important aspect of decoupling the WCF contract names and .Net names (data-types and/or parameters).

In general, we do not want to have dependency on the field/parameter/data-type names that we choose in .Net and what we publish to the world. Not only it may put under risk the application but also may be mandatorily required. Say, for example, if we need to have a parameter by the name in or for, we cannot have it because these are keywords in C# (technically speaking, yes we can have it in C# but what about C++.Net or VB.Net?). As such, we would like to remove this interdependency.

Service Contract Name

The first requirement that we look at it isolating the service name and the namespace-URI to which it belongs, and the name of the interface.

The ServiceContractAttribute has two properties - Name and Namespace that can be used to control this. The default of values of the two are the name of the interface and http://www.tempuri.org. Let us change them to Shopping-Cart-Service and http://www.edujinionline.com/ns/wcf/tutorial/scart.

Update the interface IShoppingCartService to as given below (code in bold are the changes done):

using System;
using System.ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceContract(Name="Shopping-Cart-Service",
        Namespace="http://www.edujinionline.com/ns/wcf/tutorial/scart")]
    public interface IShoppingCartService
    {
        [OperationContract]
        bool CheckUserExists(string username);

        [OperationContract]
        DateTime? GetLastTransactionTime(string username);
    }
}

Starting the hosting application that we created in the previous article. Browse to the location http://localhost:8080/ShoppingCartService?wsdl. You will notice that the WSDL generated is conspicuously short and has reference to another WSDL. Browse to http://localhost:8080/ShoppingCartService?wsdl=wsdl0. You will notice that all definitions of types, messages and operations (in portTypes section) now belong to the new namespace-URI that we gave.

Also notice that the new name of the portType is now Shopping-Cart-Service instead of IShoppingCart. Note that portType section is the one that defines the service-contract (operations and related messages). Also the bindings are now also from the type Shopping-Cart-Service.

However, if we need to change the name of the service (in service section of WSDL) and the namespace-URI of the same, we need to change the service-behaviour rather than the contract details. The default value of the same are the name of the implementation class and http://tempuri.org. Let us update them to Shopping-Cart-Impl and http://www.edujinionline.com/ns/wcf/tutorial/scart/impl respectively.

We shall make use of the System.ServiceModel.ServiceBehaviorAttribute to specify the name and namespace-uri of the service.

Update the class ShoppingCartImpl to as given below (code in bold are the changes done):

using System;
using System.ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceBehavior(Name="Shopping-Cart-Impl",
        Namespace="http://www.edujinionline.com/ns/wcf/tutorials/scart/impl")]
    public class ShoppingCartImpl : IShoppingCartService
    {
        //Other code not shown
    }
}

Operation Names

Similarly, to change the value of the operation, one can make use of Name property of System.ServiceModel.OperationContractAttribute. Let us update the name of the operations from their default names to UserExists and LastTransactionTime respectively. Update the interface IShoppingCartService to as shown below:

using System;
using System.ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceContract(Name="Shopping-Cart-Service",
        Namespace="http://www.edujinionline.com/ns/wcf/tutorial/scart")]
    public interface IShoppingCartService
    {
        [OperationContract(Name="UserExists")]
        bool CheckUserExists(string username);

        [OperationContract(Name="LastTransactionTime")]
        DateTime? GetLastTransactionTime(string username);
    }
}

Action URIs for input and output messages

Launch the hosting application and browse to http://localhost:8080/ShoppingCartService?wsdl=wsdl0. Look at the updated operation names. However, the Action of input and output messages doesn't look too good. Let us update them to http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExists and http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTransactionTime (input), and http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExistsOut and http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTransactionTimeOut (output) respectively.

The properties Action and ReplyAction may be used to customize the action-URI for the input and output operations. Again, make changes to the interface as shown below (code in bold are the changes done):

using System;
using System.ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceContract(Name="Shopping-Cart-Service",
        Namespace="http://www.edujinionline.com/ns/wcf/tutorial/scart")]
    public interface IShoppingCartService
    {
        [OperationContract(Name="UserExists",
            Action="http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExists",
            ReplyAction="http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExistsOut")]
        bool CheckUserExists(string username);

        [OperationContract(Name="LastTransactionTime",
            Action="http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTranactionTime",
            ReplyAction="http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTranactionTimeOut")]
        DateTime? GetLastTransactionTime(string username);
    }
}

Similarly, the order in which the operations should appear in the WSDL can be defined by setting the property Order of the System.ServiceModel.OperationContractAttribute appropriately. By default, the WCF engine would show the operations in the order it retrieves from the IL (using reflection).

Parameter Names

Let us say that our shopping cart works with email address as far the interface to the world is concerned. Internally, we would like to refer to it as username, like we have been doing so far.

System.ServiceModel.MessageParameterAttribute can be used to customize the name of the input parameters as well as that of the output paramter in the response. Update the code to look as follows (code in bold shows the changes made):

using System;
using System.ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceContract(Name="Shopping-Cart-Service",
        Namespace="http://www.edujinionline.com/ns/wcf/tutorial/scart")]
    public interface IShoppingCartService
    {
        [OperationContract(Name="UserExists",
            Action="http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExists",
            ReplyAction="http://www.edujinionline.com/wcf/tutorials/scart/actions/UserExistsOut")]
        [return: MessageParameter(Name="ExistsInfo")]
        bool CheckUserExists(
            [MessageParameter(Name="email")] string username);

        [OperationContract(Name="LastTransactionTime",
            Action="http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTranactionTime",
            ReplyAction="http://www.edujinionline.com/wcf/tutorials/scart/actions/LastTranactionTimeOut")]
        [return: MessageParameter(Name="TimeInfo")]
        DateTime? GetLastTransactionTime(
            [MessageParameter(Name="email")] string username);
    }
}

With all these changes, we need to regenerate the proxy-client (using svcutil). You will notice that the default class file generated this time is Shopping-Cart-Service.cs, which happens to be the name of our service!

Now, before proceeding ahead with any transaction, let us enable tracing to have a look at the message being transported. Update the application configuration file for the host to have the following entries:

<configuration>
    <system.diagnostics>
        <sources>
            <source name="System.ServiceModel.MessageLogging"
                switchValue="Verbose">
                <listeners>
                    <add name="xml"
                    type="System.Diagnostics.XmlWriterTraceListener"
                    initializeData="..\..\..\wcf_scart.svclog" />
                </listeners>
            </source>
        </sources>
        <trace autoflush="true" />
    </system.diagnostics>

    <system.serviceModel>
        <diagnostics>
            <messageLogging logEntireMessage="true" maxMessagesToLog="300"
                   logMessagesAtServiceLevel="false"
                   logMalformedMessages="true"
                   logMessagesAtTransportLevel="true" />
        </diagnostics>
        < ... >
    </system.ServiceModel>
</configuration>

Update the client application to as shown below (code in bold are the updates done):

using System;

namespace ShoppingCartConsumer
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            ShoppingCartServiceClient client = new ShoppingCartServiceClient();

            string[] users = new string[] { "gvaish", "edujini", "other" };

            foreach(string user in users)
            {
                Console.WriteLine("User: {0}", user);
                Console.WriteLine("\tExists:           {0}", client.UserExists(user));
                DateTime? time = client.LastTransactionTime(user);
                if(time.HasValue)
                {
                    Console.WriteLine("\tLast Transaction: {0}", time.Value);
                } else
                {
                    Console.WriteLine("\tNever transacted");
                }
            }

            Console.WriteLine();
        }
    }
}

Notice that there no longer exists the methods CheckUserExists and/or GetLastTransactionTime in the proxy-client generated.

Launch the Service Trace Viewer, the application SvcTraceViewer.exe found in the bin where the Windows SDK for Windows Vista and .Net Framework 3.0 Runtime Components was installed. Open the file wcf_scart.svclog generated. Notice the important changes in the request sent and response received.

Summary

We looked at how to host the service in IIS/ASP.Net. We also looked at how we can isolate the .Net parameter and operation paramter names. That's it for now. We would discuss about the faults and error-handling in WCF in the next article.

Exploring Windows Communication Foundation - Part 1

eduzine@edujinionline.com (Eduzine) — Mon, 22 Jan 2007 21:00:21 -0700

Starting with this article, we shall explore various aspects of WCF.

Introduction

Microsoft .Net Framework 3.0 introduces, among other components, Windows Communication Foundation or simply, WCF. The framework allows us, the development community, to build more service-oriented application. It incorporates several Web Service related specifications, mostly driven by W3C and OASIS consortiums. I will just list a few of them:

SOAP 1.1, 1.2 with Basic Profile 1.1
WSDL 1.1
MTOM
WS Policy and WS Policy Attachments
WS Metadata Exchange
WSS SOAP Message Security 1.0, 1.1
WSS SOAP Message Security Username Token Profile 1.0, 1.1
WSS SOAP Message Security X.509 Token Profile 1.0, 1.1
WS Addressing 2005/08
WSS SOAP Message Security Kerberos Token Profile 1.1
WS Secure Conversation
WS Reliable Messaging
WS Coordination
WS Atomic Transaction
WS Federation

Starting with this article, let us tour various key aspects of WCF.

Downloads

The code for the project is available for download at Edujini Downloads in the Windows Communication Foundation category.

Case Study

We shall take a simple shopping cart as a case-study. We start with simple data-types and slowly build on to work with custom, more complex data-types. In the sequence of articles, we shall explore various key aspects of WCF. The minimum features that I wish to explore in the series are:

Publishing WCF Service
Writing WCF Client
Customising the operation contract details, say decoupling the .Net and contract names or pushing part of the content in Headers of the Soap-Envelope
Working with faults and errors
Working with custom data-types
Working with generic data in operations
Working with interface-types in operations
Working with collections in operations
Working with large data in operations
Working with sessions and transactions

Yeah.. it's a long list, but I'll try to fulfil my promise. No, all the articles are not ready right now. Will keep posting as and when ready, and also update this article with references to them.

Ok.. so, let's start!

We will need the following items to work with WCF:

Microsoft .Net Framework 2.0 Redistributable
Microsoft .Net Framework 2.0 SDK
Microsoft .Net Framework 3.0 Redistributable
Microsoft Windows SDK for Windows Vista and .Net Framework 3.0 Runtime Components You may download the complete image here
If you are working with Visual Studio, download the Visual Studio Extensions

Service Definition

Our shopping-cart service, to begin with, publishes the following operations:

bool      CheckUserExists(string username);
DateTime? GetLastTransactionTime(string username);

The job of the first operation is to check whether or not the user is registered in our database or not. The second operation returns the date and time of last transaction done by the last user, if any. Yes, you note the operation correctly, the return type is not System.DateTime but System.DateTime?, the C# syntax for System.Nullable<System.DateTime>

To publish any service in WCF, we require four steps in general:

Service contract definition
Contract implementation
Service configuration
Service hosting

Service Contract Definition

In WCF, service contract is the term used for the final service being published. Note that a service may have one or more related operations, referred to as operation contracts in WCF.

If you are working in Visual Studio, create a new project of type "Class Library". Yes, you read it right, it is "Class Library" and not "WCF Service Library".

We start by creating an interface IShoppingCartService as follows:

using DateTime;

namespace ShoppingCartLibrary
{
    public interface IShoppingCartService
    {
        bool CheckUserExists(string username);

        DateTime? GetLastTransactionTime(string username);
    }
}

Contract Implementation

The next obvious step is to provide implementation to the service. We create a class ShoppingCartImpl that implements the interface IShoppingCartService.

using DateTime;

namespace ShoppingCartLibrary
{
    public class ShoppingCartImpl : IShoppingCartService
    {
        public bool CheckUserExists(string username)
        {
            if(username == "gvaish" || username == "edujini")
            {
                return true;
            }
            return false;
        }

        public DateTime? GetLastTransactionTime(string username)
        {
            if(username == "gvaish")
            {
                return DateTime.Now.AddDays(-3);
            }
            if(username == "edujini")
            {
                return DateTime.Now.AddHours(-3);
            }
            return null;
        }
    }
}

Service Configuration

We need configuration at two levels:

Using attributes, we need to tell WCF about the service contract and operation contracts. The information would be used to define service, operations, messages and types
Using configuration entries, we need to tell WCF about the implementation class to be used and binding details. These details would be used for hosting purpose.

Contract Configuration

If you are using Visual Studio, add a reference to the assembly System.ServiceModel.dll from GAC. Add the attribute System.ServiceModel.ServiceContractAttribute to the interface. It tells the WCF that there is a service associated with the corresponding type. Add the attribute System.ServiceModel.OperationContractAttribute to the methods in the interface. It informs the WCF about the operations to be published in the service. It will take care of messages and types associated on its own.

So, our final code looks as follows:

using DateTime;
using ServiceModel;

namespace ShoppingCartLibrary
{
    [ServiceContract]
    public interface IShoppingCartService
    {
        [OperationContract]
        bool CheckUserExists(string username);

        [OperationContract]
        DateTime? GetLastTransactionTime(string username);
    }
}

Service Configuration

We shall provide these details to our hosting application.

Compile the files to the assembly. I name it ShoppingCartLibrary.dll. If you are compiling the code at the commandline, do not forget to add reference to System.ServiceModel.dll.

Service Hosting

Having defined our service completely, we need a runtime (engine) to host the service - an application that can allow the clients to connect and invoke the operations. For this, we shall create a console application. The application has just one class, MainClass, with the Main method.

For Visual Studio users, we name the project as ShoppingCartHost. Rename the class Program to MainClass.

Add reference to System.ServiceModel.dll and to the ShoppingCartLibrary.dll Write the following code to the MainClass.

using System;
using System.ServiceModel;

using ShoppingCartLibrary;

namespace ShoppingCartHost
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            Uri uri = new Uri("http://localhost:8080/ShoppingCartService");

            using(ServiceHost host = new ServiceHost(typeof(ShoppingCartImpl), uri))
            {
                host.Open();

                Console.Write("Hit <enter> to stop service...");
                Console.ReadLine();
            }
        }
    }
}

Now, we need the service configuration as mentioned earlier. Write the following code to the application configuration file.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <behaviors>
            <serviceBehaviors>
                <behavior name="HttpGetBehaviour">
                    <serviceMetadata httpGetEnabled="true"/>
                </behavior>
            </serviceBehaviors>
        </behaviors>
        <services>
            <service name="ShoppingCartLibrary.ShoppingCartImpl"
                behaviorConfiguration="HttpGetBehaviour">
                <endpoint binding="mexHttpBinding"
                    contract="ShoppingCartLibrary.IShoppingCartService" address=""/>
            </service>
        </services>
    </system.serviceModel>
</configuration>

Compile your code. Start the console application. You should see your server up and running.

Browse to the location http://localhost:8080/ShoppingCartService.

Hurray! We are ready with our first service. Let's now design a client to consume the service.

Client Application

For our client, we need two items: the proxy client code and the configuration items. No no, you don't write any of them. You can generate them using the WCF tool svcutil.exe. You can locate this tool in the folder where your Visual Studio IDE is installed (default location being %PROGRAMFILES%\Microsoft Visual Studio 8\Common7\IDE) or where you install the .Net 3.0 SDK is installed (default location being %PROGRAMFILES%\Micrsofot Windows SDK\v6.0\bin).

Ensure that the location to svcutil.exe is in your path. Invoke the following at commandline.

svcutil.exe /nologo /config:App.config http://localhost:8080/ShoppingCartService?wsdl

It will generate two files: ShoppingCartImpl.cs and App.config. We just need a MainClass with Main method on the client side to consume the service published. Write the following code to the class:

using System;

namespace ShoppingCartConsumer
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            ShoppingCartServiceClient client = new ShoppingCartServiceClient();

            string[] users = new string[] { "gvaish", "edujini", "other" };

            foreach(string user in users)
            {
                Console.WriteLine("User: {0}", user);
                Console.WriteLine("\tExists:           {0}", client.CheckUserExists(user));
                DateTime? time = client.GetLastTransactionTime(user);
                if(time.HasValue)
                {
                    Console.WriteLine("\tLast Transaction: {0}", time.Value);
                } else
                {
                    Console.WriteLine("\tNever transacted");
                }
            }

            Console.WriteLine();
        }
    }
}

Don't forget to add reference to System.ServiceModel.dll. Build your project. Execute the client. You should get an output similar to shown below:

Note that this is only a start... so, please have a little patience if you are looking for advanced topics.

Notes

We chose to have an interface as our service contract. In general, we can have a class directly as a service contract. However, it is always a good idea to have an interface and then provide an implementation. In this way, we can keep and maintain the declaration of the contract and implementation of the contract independently and modularly.

Summary

With WCF, it is possible to publish and consume web services in a very simple way. Although publishing a web service is not as simple as in ASP.Net. However, as may be seemingly noticeable, the WCF may turn out to be much more flexible than ASP.Net service. One of the flexibilities that we saw was to host it outside ASP.Net Runtime.