Eduzine© - Web Services

Web Service Specifications

eduzine@edujinionline.com (Eduzine) — Sat, 30 Jun 2007 00:08:27 -0700

Introduction

This article enlists the various specifications related to web services. The list covers both the first generation specifications as well as second generation specifications.

The article also provides hyperlinks to the specifications and their maintainers.

1^st Generation Specifications

The web-service framework by W3C consists of a foundation built on three core XML-based specifications: WSDL, SOAP, and UDDI. The standards, in conjunction with SO-Design Principles, form a basic XML-based web-service driven SOA.

The 1^st generation architecture allows for the creation of independent web-services. It has several limitations addressed in 2^nd generation specifications.

Simple Object Acccess Protocol: Establishes a standard message format that consists of an XML document capable of hosting RPC and document-centric data.

SOAP v1.1: Maintained by W3C. Specification is available here.
SOAP v1.2: Maintained by W3C. Specification is divided in four parts - Primer, Messaging, Adjuncts and Assertions and Test Collection

Web Service Description Language: Providing the foremost language for the description of Web service definitions.

WSDL v1.1: Mantained by W3C. Specification available here
WSDL v1.2: Maintained by W3C. Specification available in two parts - Core Language and Message Patterns.

2^nd Generation Specifications

The 2^nd generation specifications position SOA as a viable successor to the prior distributed-platforms.

Reliability and Messaging: Propose features that deal with reliabile delivery, self-governing messaging, message attachments, and message transmission performance.

WS-ReliableMessaging: Available at MSDN and DeveloperWorks
WS-Addressing: Available at MSDN
MTOM, DIME: Available at MSDN
MTOM and XOP: Available at W3C
WS-Attachments: Available at DeveloperWorks

Policies and Metadata: The WS-Policy framework comprises of a set of specifications that allow for the description of policies like business-rules, security etc

WS-Policy: Available at XML-SOAP.org, and a newer proposed version at W3C. Also available at DeveloperWorks
WS-PolicyAssertions: Available at DeveloperWorks
WS-MetadatExchange: Aavailable at MSDN

Security: The WS-Security framework provides a thorough security model consisting of a host of specifications

WS-Security: Maintained by OASIS
WS-SecureConversation, WS-Federation, WS-Trust: All maintained by OASIS
XML Encryption, XML Signature, XKMS, XACML, SAML: Maintained by W3C
WS-I Basic Security Profile: Maintained by WS-I

Context and Transaction Management: The WS-Coordination specification provides a context management system. Supports atomic and long-running transactions.

WS-Coordination: Maintained by OASIS
WS-Transaction: Maintained by OASIS
WS-AtomicTransaction: Maintained by OASIS
WS-BusinessActivity: Maintained by OASIS

Business Process Definitions: Provides support for workflow - orchestration and choreography.

BPEL: Maintained by OASIS
WSCI: Maintained by W3C
BPML: Maintained by BPMI (Note that there are not many takers for BPML. BPEL has a wider acceptance.

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.

HOWTO: Web Service Transactions

eduzine@edujinionline.com (Eduzine) — Mon, 09 Oct 2006 00:01:00 -0700

How do I access two separate methods of same class publishing multiple operations in a webservice with the state being maintained?

The answer to this question, put in the newsgroup, is making use of transaction techniques. What you are trying to say is that I would like to have operations being done successfully to indicate that my job is done.

Strictly speaking, the problem does not make a concrete sense in the realm of web services since multiple operations at an end-point may or may not be implemented by a single class. So, let me rephrase the problem so that it becomes technically correct w.r.t. Web Services.

How to do I share information across two operations in one or more web services?

There are multiple ways in which this can be achieved. For extreme cases, you may want to look into the WS-Transactions Web Services Transactions Specification @IBM

For simple cases as the original query above, one may want to use simple techniques of server side caching.

Let us assume that there are two classes involved in the complete transaction. One is WebService and another is InternalData. Let us also say that WebService class publishes two operations PerformTaskOne and PerformTaskTwo. And also that execution of PerformTaskTwo require some information of PerformTaskOne, and PerformTaskOne is to return DataOne.

What we do is a simple trick. Along with DataOne, we also return a Token when PerformTaskOne is executed. On the server side, we cache DataOne and InternalData with the key as Token. Note that the Token has to be generated randomly and must be unique for each visit to PerformTaskOne.

For PerformTaskTwo, apart from other inputs may be required, we also ask another parameter as Token.

In PerformTaskTwo, before starting execution, we rebuilt InternalData and DataOne using the Token from the cache.

Now that we have rebuilt the previous state, we can go ahead and complete our PerformTaskTwo.

We have put a small working demo at CodeProject. You may download the code and play with it. Please note that if the article gets approved, the URL may change. Please do vote for the article if you like it.

"405 - Method Not Allowed" error with ASP.Net based Web Service

eduzine@edujinionline.com (Eduzine) — Sun, 08 Oct 2006 00:01:00 -0700

I get a 405 error while working with ASP.Net based web service. The request synopsis is:

POST / HTTP/1.0
Host: my.machine.host.name
Content-Type: text/xml
Content-Length: NNNN
...

The problem is not anywhere else but with the request itself. To be able to appreciate the solution, one must understand the HTTP specifications.

1.0 version of HTTP does not specify any 'Host' header. It was introducted in 1.1. One needs to change the request to look something like:

POST http://my.machine.host.name/ HTTP/1.0
Content-Type: text/xml
Content-Length: NNNN
...

Or one may simply update the request to reflect "HTTP/1.1" instead of "HTTP/1.0".

Web Services in ASP.Net: HTTP-POST vs. HTTP-SOAP

eduzine@edujinionline.com (Eduzine) — Sat, 07 Oct 2006 00:01:00 -0700

What is HTTP SOAP and how does it differ from HTTP POST as far as Web Services in ASP.Net are concerned?

To get an answer to the question, one must first have an understanding of the HTTP Protocol - how does it work.

HTTP Protocol allows, among other methods, two most widely methods - GET and POST. You may consider them as the commands given to the server to perform specific tasks.

Associated with every command given by the client is a set of headers that follows the command and optionally some data that is sent for further parsing. This data can be username and password using which you logon to your favourite webmail or it can be the contents of the file that you upload.

When you go to a website by typing a URL in the browser, the browser sends a GET command to the server. A sample data sent by the browser to the server may be:


GET / HTTP/1.1
Host: http://www.edujinionline.com
Connection: close

GET command consists of just two parts -- a line containing the command and optionally a set of headers following thereafter.

Similar to GET is the command POST. POST command has three parts -- a line containing the command, a set of headers and data to be sent to the server. A sample POST command may look like:


POST /SomePage HTTP/1.1
Host: http://www.edujinionline.com
Content-Type: application/x-www-url-encoded
Content-Length: 33
Connection: close

username=edujini&password=online


POST /SomePage HTTP/1.1
Host: http://www.edujinionline.com
Content-Type: multipart/form-data;
      boundary=--EduJiniOnlineBndry
Content-Length: Some-Length

Connection: close

--EduJiniOnlineBndry
Some Data
--EduJiniOnlineBndry--

For the server to be able to parse the contents after the headers correctly, one must send at least two headers Content-Length indicating the number of bytes of the content (after headers) and Content-Type providing the type of the content.

When you submit a form, the content-type would generally by application/x-www-url-encoded and when you upload a file it must be multipart/form-data

When one works with SOAP-based Web Services on HTTP Protocol, the Content-Type must be text/xml and nothing else.

Enabling HTTP-POST for the Web Services means that one can connect to a URL like http://www.edujinionline.com/WebService.asmx?op=Op1, submit the form (automatically generated by the engine) and get the results back (in XML format).

Enabling HTTP-SOAP for the Web Services means that one can connect to the URL (http://www.edujinionline.com/WebService.asmx) using the POST method and using the content type as 'text/xml' and providing the content (after headers) as the SOAP-Message and expect a SOAP-Message in response.

Still unable to figure the what's the difference between HTTP-POST and HTTP-SOAP... drop in a comment and we shall get back to you.

Java, PHP and .Net: Web Services, SOA and InterOP

eduzine@edujinionline.com (Eduzine) — Fri, 06 Oct 2006 00:21:00 -0700

How does the interoperability of Web Services between Java, PHP and .Net fare?

In this entry and may be a couple more to follow, I plan to bring out how the three leading web-platforms fare when it comes to Web Services. Few questions, not exhaustive by any means, that would be of interest may be:

What level of support is available in individual platform?
How good is individual platform when it comes to all standards and specifications around WebServices?
How good is individual platform when it comes to inter-operability with others?
What resources are available in terms of bundled libraries, additional libraries, 3rd party tools and libraries and documentation / tutorials thereof?

Ok.. as I continue writing further, I have changed my mind. No further discussion in this entry. I will create new entries to address individual topic.

HOWTO: Using Arrays in WebServices

eduzine@edujinionline.com (Eduzine) — Thu, 05 Oct 2006 17:40:35 -0700

How do I use arrays in a Web Service?

Probably one of the more frequently asked questions regarding web services. I thought I will answer this prior to starting my discussion on comparing platforms.

Attempting to answer this question from the perspective of all three major enterprise platforms...

ASP.Net:
Using from ASP.Net based Web Services, or for that matter, even using SOAPFormatter in .Net Remoting is simple. There are two ways to achieve it.

1. If you need an array of data as one of the parameters to the method, you can apply the attributes XmlArrayAttribute and XmlArrayItemAttribute to the parameter configuring the name of the element.

2. If you need to pass a parameter whose type is not primitive, you should again look at the attributes in System.Xml.Serialization namespace on how you can serialize the class in the way that you want it to...
PHP:
Probably the simplest and the toughest of all three. Toughest because in PHP one has to first generate the WSDL by hand.

On the server side one doesn't need to do anything... can treat any parameter as an array. For the client to be able to work perflectly fine, one needs to generate appropriate WSDL. That's it. An example of the generated WSDL may be (data-type):
```
  <element name='userNames'>
    <complexType>
      <sequence>
        <element name='name' type='xsd:string'
           minOccurs='1' maxOccurs='unbounded' />
      </sequence>
    </complexType>
  </element>
```
One good example of how dynamic-structure can be useful in PHP is using PHP to access MapPoint Services.
Java using Axis:
Again, a very simple implementation though one would need to have a look into the WSDD file.

Looking into the User Guide of Axis, the arrayMapping element can be used to maximize returns.

On the page search for the topic of 'Deploying array mappings - the <arrayMapping> tag'... or just find for the word 'arrayMapping'. I am quoting the example here for completeness:
```
  <arrayMapping qname='ns:ArrayOfMyDataType' xmlns:ns='uri'
    languageSpecificType='java:f.q.t.MyDataType[]'
    innerType='ns2:MyDataType' xmlns:ns2='uri2'
    encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
```
f.q.n: stands for fully qualified name.

The reference for the element can be found here.

HOWTO: Transfer Files using Web Services

eduzine@edujinionline.com (Eduzine) — Wed, 04 Oct 2006 17:38:00 -0700

How to transfer files using Web Services?

There are actually multiple ways of doing so.

The first, simplest approach, is to send the contents of the file as a raw-string parameter. In case, the file content is binary, do not forget to base64 encode it.

The advantage of this approach is that you don't need to download any extra features / extensions / add-ons for any Web Service engine that you are using, be it on .Net, Java, PHP or whatever.

The disadvantage is that all manipulation needs to be done manually. What more, metadata like filename etc needs to be passed as a few more parameters... all manipulation to be done manually.

The other option is to use MIME or DIME (now, superseded by MTOM) attachments. For .Net based webservices, one would need to download "Web Service Enhancements (WSE)". WSE 2.0 is for .Net 1.1 and WSE 3.0 is for .Net 2.0. Take you pick. Java guys can continue to use Axis (Axis2 is what I have been waiting for). PHP -- I sill don't know about the libraries that would support these.

The advantage of MTOM attachments is that the APIs are fairly abstracted and one doesn't need to perform any manual compuations or calculations.

ASP.Net: Disable non-SOAP Requests

eduzine@edujinionline.com (Eduzine) — Tue, 03 Oct 2006 17:34:00 -0700

How to disable non-SOAP and non-Documentation Requests to ASP.Net based Web Services?

ASP.Net WebServices (ASMX handlers) are highly configurable in terms of the protocols that they can handle. By protocol, I mean the WebServices protocols like Get, Post, Document, SOAP-1.1, SOAP-1.2 etc.

The configuration section /configuration/system.web/webServices is handled by System.Web.Services.Configuration.WebServicesSection. Now, this section has a sub-section of procotols that is mapped to the Protocols property of the class mentioned.

By default, the following protocols are enabled:

HttpGet
HttpPostLocalhost
HttpSoap
HttpSoap12
Documentation

These elements, technically, are members of the enumeration System.Web.Services.Configuration.WebServiceProtocols.

To disable non-SOAP and non-Documentation requests, all that needs to be done is remove the other protocols. To do so, add the following code in your application web.config under the /configuration/system.web/webServices section:

<protocols>
   <remove name='HttpGet' />
   <remove name='HttpPostLocalhost' />
</protocols>

You are done. As always, if in trouble, either post a comment or contact EduJini!

HOWTO: How to Use WSDL in .Net Applications

eduzine@edujinionline.com (Eduzine) — Mon, 02 Oct 2006 17:05:00 -0700

How to use this WSDL file in my own .NET application?

The action requires a maximum of 4 steps.

Step 1: Right click on the 'project' in 'Solution Explorer' and select 'Add Web Reference...'
Step 2 (optional): Browse to the service location. If you know the location of the WSDL file, skip this step.
Step 3: Browse to the WSDL file.
Step 4: Give the name of the proxy class to be generated for the service.

See the screenshots below.

Step 1:

Step 2:

Step 3:

Step 4:

ASP.Net: Using Asynchronous Calls in Web Service

eduzine@edujinionline.com (Eduzine) — Sun, 01 Oct 2006 23:28:00 -0700

What is the best approach to perform asynchronous call in Web Services?

There are three approaches. Depending upon the requirement, one or more may be chosen.

Asynchronous Delegate-Call
Threads
Message Queues (MSMQ)

Let us explore these options in depth...

Asynchronous Delegate-Call
Simplest way to call a method asynchronously.

Create a delegate with the same signature as the method that you wish to invoke. Then, create a new instance of the delegate using the method-instance as the parameter (similar to what you write while adding an event handler to an event). Then use the methods BeginInvoke and EndInvoke to call it.

Use this mechanism if you want to call the method asynchronously but the result to the client is synchronous. The method WebMethod in the above example will not return unless iar.IsComplete is true.


     public static object MethodToCall(params) { ... }
     public delegate object MethodDelegate(params);

     public WebService
     {
       public string WebMethod(params)
       {
         MethodDelegate md = new MethodDelegate(MethodToCall);
         IAsyncResult iar = md.BeginInvoke(...);

         //Do other work of yours
         //And then check for the other method
         while(!iar.IsComplete)
         {
           Thread.Sleep(20);
         }
         object returnValue = md.EndInvoke(...);
       }
     }

Threads
This approach may be used in scenario where a task needs to be started by a web service while another web-service may be used to monitor the progress of the service.

Example is long. Will post the URL from where the code may be downloaded.
Message Queues (MSMQ)
The scenario would be same as for Threads. However, here there is a flexibility. The MS-MQ server can be anywhere in the world and the monitoring web service can, as such, be anywhere - need not be on the same server as the invoking service.

Example is long. Will post the URL from where the code may be downloaded.

Eduzine© - Web Services

Web Service Specifications

Introduction

1st Generation Specifications

2nd Generation Specifications

Exploring Windows Communication Foundation - Part 2

Downloads

Hosting WCF Service in IIS/ASP.Net

Updating the client

Service Customization

Service Contract Name

Operation Names

Action URIs for input and output messages

Parameter Names

Summary

Exploring Windows Communication Foundation - Part 1

Introduction

Downloads

Case Study

Service Definition

Service Contract Definition

Contract Implementation

Service Configuration

Contract Configuration

Service Configuration

Service Hosting

Client Application

Notes

Summary

HOWTO: Web Service Transactions

"405 - Method Not Allowed" error with ASP.Net based Web Service

Web Services in ASP.Net: HTTP-POST vs. HTTP-SOAP

Java, PHP and .Net: Web Services, SOA and InterOP

HOWTO: Using Arrays in WebServices

HOWTO: Transfer Files using Web Services

ASP.Net: Disable non-SOAP Requests

HOWTO: How to Use WSDL in .Net Applications

ASP.Net: Using Asynchronous Calls in Web Service

1^st Generation Specifications

2^nd Generation Specifications