Browse DevX
Sign up for e-mail newsletters from DevX


Introducing Contract First : Page 2

Many publications and blogs consider Web services to be the silver bullet because they are so easy to implement in .NET and interoperate with disconnected systems. But are people really using Web services the way they should be used?




Building the Right Environment to Support AI, Machine Learning and Deep Learning

Web Services
Contrary to all known acronyms, Web services are not just suited to realize XML-based remote method calls. Yes, many developers use them like this but it trims their potential considerably. As I discussed in the preceding paragraphs there was no notion of a special pattern of communication when it comes to services. I did not mention synchronous communication and I did not mention RPC (Remote Procedure Call) and the like. An RPC is always an abstraction of something more difficult—but surely it is not always a good and wise abstraction.
A Web service is therefore a message-oriented communication means, period. You can implement service-oriented thinking, mindset, and methodologies through Web services—in a near-perfect manner.
A Web service is therefore a message-oriented communication means, period. You can implement service-oriented thinking, mindset, and methodologies through Web services-in a near to perfect manner. Web services are, harshly spoken, nothing more than an entry point into an application or program. Above all, Web services and SOAP are no substitution for existing component models and they are not the right place to put your business logic. They are really just competent data and message transformers. With such a view, Web services lose a lot of their aloofness and the confusion being caused by the word "Web."

You might have just read those lines with an uneasy feeling. Are Web services really seen this way on the .NET platform today? Are Web services used like this? Are our tools actually "selling" us Web services like this? .NET Web Services Today
Web services are abundant in the .NET development environment. The primary technology stack for developing and consuming Web services is ASP.NET. Insiders call ASP.NET's Web services runtime the ASMX engine. In the last few years, many developers got used to viewing ASMX through their Visual Studio .NET glasses. They just need to open a wizard and then use the Web service implementation—just add some methods and attributes and they were all set. On the other side, you just need to select Add Web Reference... from the menu and you are automagically provided with a reference to a remote functionality. That's easy. But is it correct?

Maybe the outlined approach is enough for simple point-to-point integration based on the object-oriented and interface-based body of thoughts. But if you try to relate those ideas of service orientation with today's ASMX reality you'll soon hit the wall. But why? First, consider the project wizard and dialogs. It suggests that ASMX Web services are just another XML-based object communication means. If you Google appropriately you'll find tons of articles revolving the magic of [WebMethod]. Just mark your business logic with this attribute and you are done forever. Paired with ASMX's limitation to HTTP as the transport protocol number one you have the perfect picture of an RPC-ish XML-based remote method call. I think this is just the wrong level of abstractions that developers need in order to take the next steps heading to service-orientation. ASMX is not bad, not at all. It is just used in the wrong way in most cases.

Maybe one of the biggest misconceptions is to allow the ASMX runtime to automatically create the WSDL (Web services Description Language) for a given Web service implementation. By simply pointing to the ?wsdl parameter in a Web service's endpoint address you can retrieve the Web service's metadata. You don't need to know XML, SOAP, or WSDL-you don't need to use angle brackets. That's true love. But the hassle comes later. This nice feature leads to a wrong approach to Web services. A lot of developers tend to just take their business logic classes and place a WebMethod attribute in front of those methods that should be accessible via SOAP. They neglect the fact that on the wire there are messages and that they must not think in .NET and its common type system for achieving interoperability and integration. Instead, they must rely on the common denominator of types, the XML Schema type system. In most cases they cannot just abstract away any of the XML and Web services-specific details. So how can they do better?

Believe it or not, the answer to the above question is simple: turn the tables. Focus on the data and the messages first, and then let tools generate the skeleton code for your primary Web services engine. Practical experiences from projects have shown that thinking and acting in different notations and dialects is good when it comes to modeling the service interfaces. Being explicit is good, especially for service interface contracts. And it is even better to step back from using either C# or VB. NET for this important step and take a completely different means to describe your service's interface. Because the success of your Web service stands and falls with the service's interface. This idea is also called the contract-first approach to Web services design and implementation. Schema or Code?
There are basically two philosophies for contract-first design: code-based and schema-based. Code-based means that a developer uses a CLS-compliant programming language to write down the interface of their Web service. In addition they use a number of XML- and SOAP-specific .NET attributes in order to achieve their goals. I consider this a bit dangerous because it still centers on objects and the .NET BCL. Additionally, it does not hinder a developer to expose .NET idiosyncrasies like a DataSet.

The schema-based alternative uses XML Schema and WSDL directly in order to explicitly distance itself from concrete programming platforms and languages like Java and C#. Starting from those XML-related representations, you can easily create platform-specific code. But the major problem of schema-based contract-first is that it is quite complex to learn (who wants to know all the XML Schema and WSDL details in syntax?) and very error-prone to use (there simply are no good tools or editors to leverage). For the remainder of this article I want to focus on the schema-based way to contract-first design your Web services and I'll show you a small and free tool later on that can lower the barrier considerably for interoperable Web service architectures. But first I need you to take a closer look at how the schema-based approach actually works in detail.

The Phases
A picture tells a thousand words, so look at Figure 2, which shows the sequence of steps or phases involved in the contract-first design approach. (From now on when I mention contract-first I actually mean schema-based contract-first).

Figure 2: Phases of schema-based contract-first design and implementation.
There are basically five steps to watch out for:

  1. Model your data. This step involves thinking about which data you need to exchange through your Web service interface. This is an explicit view on explicit data. One can think of it as the XML-ized way of defining data transfer objects. You'll use XML Schema (XSD) to model the data.
  2. Model your messages. Write down which messages you will need to exchange the data you have modeled in the previous steps. You'll use these messages later in your Web service interface. You'll use XML Schema (XSD) to model the messages. (Step 1 and 2 might be collapsed into one step).
  3. Model your operations. Define which operations you want to offer to the Web service consumer. Operations are made up of message exchange patterns (for example, one-way or request/response) and their associated messages—those messages you have designed before, which use the data you have defined in first place. You'll use WSDL (XSD) to model the operations and interface.
  4. Generate code. Generate your platform and programming language code as appropriate—based on the message and interface contract defined in the previous steps.
  5. Iterate. There is never a first match for your interface contract. You need to be able to refine existing service descriptions and thus also update existing code from it. This is not an explicit step but more an orthogonal action throughout the whole design and implementation process.
Although tools already exist in the .NET Framework SDK that help you generate ASMX Web service code from XSD and WSDL, they are not sufficient for effective contract-first work.
OK, this all sounds nice. You might now just start to hammer down your XML Schema for the data and the messages before you go into Notepad and write your WSDL manually. Ouch. There must be tools for it. And it turns out there are. Tool Approach to Contract-First
Although tools already exist in the .NET Framework SDK that help you generate ASMX Web service code from XSD and WSDL, they are not sufficient for effective contract-first work. Developers really need a good WSDL editor or even designer. For the XSD-related part of modeling data and messages you might want to rely on Visual Studio .NET's intrinsic XSD editor.

Let me tell you about a small tool called WSCF (Web services Contract-First) which solves a lot of the problems related to Web services, and it makes the contract-first approach to Web services easier. WSCF is primarily an add-in for Visual Studio .NET, but it also includes a command-line tool. It was designed to make implementing the above-outlined five steps of contract-first Web services as easy and smooth as possible. Therefore, WSCF has two main responsibilities: aid in the design of the data, message and service interface contract description in an interoperable fashion; and generate code from a given service interface description. You'll see how to accomplish this. In order to get a better impression of what things actually look like and see how they work, I'll walk you through a simple example. Suppose that you're a member of a .NET user group, and you want to make some of the group's member data available to the outside world. You've decided to create a Web service that delivers and accepts data packed in SOAP messages and a client application that talks to this Web service.

Comment and Contribute






(Maximum characters: 1200). You have 1200 characters left.



Thanks for your registration, follow us on our social networks to keep up-to-date