WSDAPI 101 Part 1: Web Services from 10,000 feet

  • [アーティクル]

Introduction to WSDAPI 101
The world of Web Services (WS) is often described in terms of contracts, messages, and generated code.  The picture that’s painted gives a high-level overview of the interactions between clients and services; but in describing the fundamentals, it’s sometimes difficult to immediately understand how these concepts relate to interfaces, methods, function calls, and actual code.

This is the first in a series of articles that will start with that 10,000’ view of WS, but will also provide a concrete example that illustrates the connection between concept and code.  These articles will be specifically geared toward explaining the concepts around my stack, the Web Services on Devices API (WSDAPI) available in Windows Vista and Windows Server 2008.

I originally called these articles Web Services from the programmer’s perspective, but the title was too long so it’s WSDAPI 101 instead.  Either way, these articles will focus on illustrating Web Services (and specifically WSDAPI) in a way that’s most useful to developers who actually use it.

So to start on our journey, I’ve provided a roadmap of the articles in the series:

  1. WSDAPI 101 Part 1: Web Services from 10,000 feet (this article)
  2. WSDAPI 101 Part 2: The stack, explained through a concrete example
  3. WSDAPI 101 Part 3: Generated code and what it does for you
  4. WSDAPI 101 Part 4: The interfaces under the generated code
  5. WSDAPI 101 Part 5: Putting it all together to generate WS traffic

My intent is to keep articles isolated enough that you don’t need to read the first four to grok the last, but there will be some small overlap in content and you’ll certainly have the best understanding if you read all of them in order.

Alright, let’s start with the content.

The 10,000’ view
Before I start with the programmer’s perspective, I’ll begin with that 10,000 foot view that I mentioned earlier.  It doesn’t tell you enough to get coding, but it’s necessary to understand the more concrete explanation.

Web Services are a pile of specifications that describe how to format and transfer messages.  There are four fundamental objects in the WS world:

  • A contract, which describes the data being sent in a message.  This contract is typically described in a file written in the WSDL format.
  • Messages, which are formatted according to the WS specifications and the contract.  These messages are XML in the SOAP format and may be sent over many transports (communication channels), including HTTP and raw UDP.
  • Clients, which send messages to a service and may receive responses, depending on the contract.
  • Services, which accept messages from many clients and sends responses, again depending on the contract.

The vast majority of Web Services conform to the descriptions above.  There are a handful of cases where the contract and messaging take place in different ways, but we’ll conveniently ignore those for now.  In any event, these four concepts are enough to understand the major actors in any WS communication.

Another vitally important part of the Web Services story is the programming model.  Web Services are so powerful because in addition to the openness afforded by the transparent relationship between contract and message, there is also rich tool support to allow developers to quickly develop applications that can use this rich messaging functionality without actually having to deal directly with parsing XML or generating HTTP headers.  This tooling makes developing clients and services very straightforward, and is easily one of the biggest reasons for the wide adoption of WS.

Now, this easy development process begins with the WSDL, which describes the programmatic data that will move between the client and the service.  The WSDL describes port types and operations that roughly correspond to interfaces and methods.  A developer takes this WSDL and feeds it through a service modeling tool, which generates code that exposes the functionality available at the service.  If you’ve ever seen sample code for a WSDAPI or WCF application, you know that it only takes a few lines to connect to a service and issue meaningful, strongly typed messages.

And with that, you’re using WS.

The programmer’s perspective
But if you’re anything like me, the description I’ve just given you stops right before the interesting parts.  WS gives you powerful messaging and an easy-to-use programming model, but how can I dig around in this to make things work the way I want?  What is this “generated code” layer, and how does it work?  What sort of things does the generated code depend on?  Is the WSDL used at runtime, or just at compile time?  How portable is this generated code, and can I use it with other WS stacks?  What if I’m writing a Web Service from scratch—do I need all of the pieces that are described here?  How do I debug failures in my WS client or service?

The list goes on and on, and this series is designed specifically to address these questions.  If you’ve read to this point, you’ve probably realized that the answers to these questions aren’t in this article—but I assure you that they will be addressed in the next four articles, when I dive into the technology in detail.  But now you understand the background and know what to expect, which is critical to a good and practical understanding of Web Services.

See you next time!

Comments

  • Anonymous
    November 11, 2007
    Hi Dan, Nice start. Waiting eagerly for the next part. Regards, -Manish

  • Anonymous
    November 15, 2007
    Manish- Thanks very much!  The next articles are already in the works--I expect the next entry will be online in the next week or two. --Dan

  • Anonymous
    September 17, 2008
    Hi Dan, We were facing one problem while doing cancel of scan job. Can you please share with us the sequence of operations to be followed for cancelling the scan job. We observed that in comparison to the Microsoft inbox driver,In our driver WSD service is not calling "CWSDDevice::EndRetrieveImage".As a result of this scan job is not getting cancelled. Request you to share with us approach for cancelling the scan job. Regards Shilpa and Rashmi

  • Anonymous
    September 19, 2008
    Hi Shilpa and Rashmi- Sorry, I can't help you with that one--questions about sequencing of operations are specific to a particular application, and I'm not an expert on the WSD Scan specification. You can consult the spec or contact Microsoft developer support. Thanks --Dan