Don Smith : Architecture

Using MessageContracts and DataContracts

donsmith — Tue, 11 Mar 2008 05:10:00 GMT

Users of the Service Factory often ask about the rationale behind the required use of MessageContracts even though the use of MessageContracts aren't mandated by WCF. I've answered this question in other venues, but it seemed like a good thing to put here in case I need to point others to it in the future.

If you ask the WCF product team when you should use a MessageContract versus a DataContract, their guidance usually revolves around the level of control you need over the message - like when you need to use custom SOAP headers*. You can find more detail in this topic of the WCF documentation. Their guidance makes complete sense if you think about the motivation they had when building WCF: to unify all of the Microsoft communication mechanisms into a single approach that is relevant to all scenarios. This is great for someone who has traditionally only done object-oriented or component-oriented development. They can be successful without understanding the nuances of building Web services.

In our experience one of the biggest hurdles for many developers who are new to Web services has been the concept of the message - rather than just passing around types like they've always done. You can characterize this distinction as implicit versus explicit message design. We have a topic in the Service Factory documentation that touches on this distinction. I think there is some room for improvement on this topic, but you can find it here nevertheless.

However, the confusion over a message isn't the only reason we elevate the importance of the message and recommend these usage patterns. We intentionally draw a clear distinction between types (both primitive types like string, and complex types like Customer) and messages (like ProcessExpenseReportRequest). From our perspective, DataContracts represent types and types are reusable. Messages are not used as types but rather the payload a method operates on - and it is not reusable since they are specific to the operation they are passed to and from. This level of distinction provides architects and lead developers a means of achieving better consistency throughout their organization by being more prescriptive about reusability.

I am aware that Juval's position is that MessageContracts are rarely needed. And, I hold Juval in the highest regard - I've not yet had an opportunity to learn what is motivating him to take this position. Some might argue that MessageContracts are just an additional (unnecessary) level of redirection. I can understand this point of view. We just feel the benefits greatly outweigh this nominal cost, and the feedback we've received from customers has been completely supportive of this approach.

* In my opinion, there is only one reason you would need to create a custom SOAP header that isn't already defined by a standards body like WS-*. (hint: if it's already defined elsewhere, you should use it to ensure interoperability, instead of "rolling your own") And, that reason is if you need to pass around localization information (like "en-us"). I don't think this is covered by any WS-* or other spec.

... come and get yer Service Factory!

donsmith — Wed, 10 Jan 2007 07:30:00 GMT

That's right ladies and gentlemen, the December release of the Web Service Software Factory and a VB.NET version is now available for your consumption, modification, and production pleasures :)

Okay, I'm just going to do 3 things in this post since I know there will be many more to follow:

Lay some links on ya. For downloading the Service Factory releases and more info.
Share my favorite new features of the Service Factory with you.
Give you a sense of what is to come in the near and not-so-near future.

Links

Service Factory December release helps you build both WCF and ASMX services in C#. The old July release is no longer available since everything it contained is included in this release. Web Service Software Factory–December 2006 (ASP.NET and WCF services in C#)
Service Factory July release that helps you build ASMX services in VB.NET. Yes, I know this is new and was actually published in December, but it is effectively the same exact version as the original July release - it's just been converted to VB.NET (that's why we're calling it the July release). If this is confusing, I apologize ... I'm to blame. Web Service Software Factory–July 2006 (ASP.NET services in VB.NET)
Service Factory information. If you're not sure what the Service Factory is and want to find out before downloading it, go to http://msdn.com/servicefactory to learn more about it.

Favs

WSDL-first support. This feature definitely wasn't the most challenging to include, but I still love it. I've spent a lot of time over the years monkeying around with WSDL files. The fact that Service Factory has a single recipe (wizard) that will take a single WSDL and generate the service interface, service implementation, binding configuration (config file), and all of the associated DataContracts/XmlSerializable types is just freakin' sweet. You have to see it even if you don't define all your contracts in WSDL first.

Versioning guidance. This is a favorite of mine because ... well, I wrote it haha. No, seriously ... it's no secret this is a topic that is near and dear to my heart. I have labeled the topic "emerging guidance" in the Service Factory documentation because I want to gather more evidence from customers that this approach is actually working for them before I propose we call it a "proven practice". I have spoken with a number of customers who have taken this approach and it is working well for them. I haven't spoken to anyone it didn't work for, but I'd love to hear from you. If you're interested in reading or sharing, I've also posted the topic on my blog here. Personally, I think the "strategy" section of the guidance is still weak on content, but more on that in the "futures" section of this post. I also plan to do a webcast on it.

WCF Code analysis. This one turned out to be the sleeper feature - we didn't expect this to turn out so sweet. As you may know, FxCop has been integrated into Visual Studio 2005 under the name Code Analysis. Well, we took all of the same rules that used to be the Security Analyzer back in the WSE days and converted them all to code analysis rules. They also work against the code AND the config files (something FxCop hasn't done historically). I know, pretty sweet, huh? Well, when we showed this to the WCF team, they asked if we could include some of the rules that they fire at run-time so they could be run at design-time (like the ones that make sure all the binding stuff is consistent). "Sure", we said. So there are about a dozen of them too ... and it's all integrated into Visual Studio ... even if you're not using Service Factory.

Recipe runner. Okay, now I'm cheating a little. This isn't actually a feature ... and it's not really included in Service Factory. One thing we learned while building the July release was that testing GAX recipes is feakin' hard. Well, harder than it should be. So the team took a couple of months at the beginning of this version to get it right. The result is something we call RecipeRunner. Those of you who are creating your own recipes or heavily modifying the ones we provide will really like this if you care about testing, which you should. We'll be making it available on the community site in the near future.

There are loads more things that are new and way cool in this release, but I want you to discover some of them for yourself too. Of course I'll be mentioning them as time goes on and in some mini videos. Oh, that brings me to the last item on my agenda.

Futures

Blogcasts. The very next things you're going to start seeing are more of the blogcasts I did some months back. Many of them are outdated now and I need to do more of them now that the WCF Service Factory has released. The feedback was very positive (thank you) and because I claim to listen to you, I promise to do more of them shortly.

HOL exercises. I've already began the process of converting the existing hands-on lab (HOL) to WCF. Additionally, we'll be adding a bunch of new exercises. What I need from you is some details so we're sure they are helpful. This is what we have in mind:

Modifying a guidance package - There is already a how-to in the Service Factory documentation, but customers are always telling me they need more help. If you tell me what kind of changes you're making to guidance packages I will try to create an exercise that illustrates how to make that change.
Building a service agent - A service agent is that layer of code on the consumer side that invokes the proxy (that's right, you're NOT suppose to do it in the button's click event handler :). It manages things like retries, response caching, offline support, asynchronicity, etc. I need you to tell me what kind of challenges YOU (not your neighbor) need. That will help me get this exercise right.
Versioning - this will build on the topic I mentioned earlier and will walk you through how to evolve a service in a number of ways.
Message validation - The reference implementation already illustrates this. But would you find a HOL exercise valuable? If not, cool, I'll spend that energy somewhere else. If so, also cool.
Exception shielding - The reference implementation also illustrates this. Same question ...
Create a code analysis rule - I think this is also covered in the VS documentation, but I've never looked for it. Are you going to be writing your own rules? If so, would you find a HOL exercise helpful?
Workflow Foundation - we actually did a lot of work with this, but had to pull it at the last minute (yeah, sometimes cutting scope at the last minute hurts). We might be in a position to create an exercise as a result of what we already have. We'll see.

v3 planning. We have already began the planning process for v3. But because we JUST started, we don't have a lot to share just yet. I can tell you (if you didn't already guess) that a service domain specific language (DSL) is the primary theme of the next version. I will be sharing everything with you around the features and their priorities as soon as we have something to share. As always, we'll be counting on you to steer us where you need us to go. All of this communication will naturally happen on the Service Factory community site, which will be moving to CodePlex in the very near future. More on that later too.

Okay, it's getting late and the weather is getting nasty so I'm heading home. Until next time, you have a lot to keep you busy :D Looking forward to your feedback. Thanks!

Service Architecture Concept Model

donsmith — Fri, 21 Jul 2006 07:56:00 GMT

I'm posting this because I'm interested in your thoughts about it.

IMPORTANT: This is just a concept illustration. I'm not encouraging anyone to accept and begin using the nomenclature used.

This is just the result of a conversation Tom and Ed and I had today about how this illustration might evolve. If something isn't clear, please leave a comment. If you've seen other illustrations or nomenclature about these things that better resonate with you, please leave a comment and tell me about them. If you have any other thoughts, ... I think you get the idea :)

Service Factory: Entity Translation

donsmith — Fri, 28 Apr 2006 23:41:00 GMT

For the third installment I've decided to talk about the entity translation (mapping) capability of the guidance package. Specifically, this is mapping between the entities that are [de]serialized to/from the wire representation and the entities that represent the business domain model. This time I used a high-quality mic (Shure) and better software (Camtasia Studio), but WMV is still the best output format for this delivery mechanism (MP4 isn't an option). I also tried 1024 x 768 instead of 800 x 600.

File: ServiceFactory-Mapping.wmv
Length: 15:15
Size: 5.93 MB

Service Factory: Contracts

donsmith — Thu, 20 Apr 2006 11:54:00 GMT

Here's the second installment of my blogcast series on Service Factory. In this one I show how to create WCF data contracts and service contracts. It's a little bigger and longer than I would have preferred, but since I was building the project (a wine rating app) from scratch, I guess that's what took longer.

File: ServiceFactory-Contracts.wmv
Length: 25:48
Size: 8:51 MB

Service Factory: A Brief Introduction

donsmith — Thu, 20 Apr 2006 10:53:00 GMT

Here is the first installment of a series of blogcasts I hope to continue that are focused on the project I'm working on. This is just a quick 11 slide PowerPoint presentation that gives you the rationale and scope of the project. It's really the best place to start and it's only 15 minutes. Just ignore the cursor I forgot to move out of the way :)

File: ServiceFactory-Intro.wmv
Length: 15:23
Size: 2.14 MB

Web Services Architecture Domain Model

donsmith — Sat, 03 Sep 2005 03:31:00 GMT

I'm not in a position to provide any details just yet, but a couple of us on the patterns & practices team have teamed up with heavy hitters like Jason Hogg, Beat Schwegler, Christian Weyer, Wojtek Kozaczynski, Maarten Mullender, Daniel Cazzulino, Victor Aprea, Hernan de Lahitte, and Pablo Galiano to provide some kick ass guidance around designing and developing Web services. During one of our meetings this week, we thought there might be some value in throwing together a domain model so we could make sure we were all singing from the same sheet of music when we used certain terms. This is a Visio version of what the whiteboard looked like after the meeting.

This is by no means complete, but it illustrates some interesting concepts and commonly used terms. The first thing it illustrates is the almost 1 to 1 mapping of angle-bracket thingies and .NET thingies.

Also, in the context of the common "Contract First" phrase, you can not only see what comprises the contract on each side of the model, but get a visual sense of what contract first might mean. Contract first doesn't necessarily mean "fire up your favorite text editor and start handcoding WSDL". Of course, if you like doing that, you certainly can. But you can also start with C# if that is your preference. You can get yourself in trouble with either approach, but each approach is viable also ... start with whatever you're comfortable with ... just make sure you're thinking about the messages and the contract as a whole.

The other interesting thing this illustrates is the clear separation of the service, the adapter, and the business logic. This separation of concerns is an important architectural detail. Beat and I will be speaking specifically about this during our PDC pre-con session.

Principles of Web Service Design

donsmith — Fri, 19 Aug 2005 20:46:02 GMT

John Evdemon just published 2 articles on the principles of web service design.

The first one is titled Principles of Service Design: Service Patterns and Anti-Patterns and in my opinion should be required reading for anyone who is new to web service development. Specifically, anyone new to building web services should focus on his explanation of the 4 tenets of service orientation, and the anti-patterns - this is good stuff - but if you've been staying up to date on web service architecture and development, you won't read much you haven't read/heard before. If you think you're pretty up-to-speed on web services, just breeze through those parts and check out the patterns - they tend to be more specialized.

The second article is titled Principles of Service Design: Service Versioning. This article was of particular intereste to me since I've done quite a lot of thinking about the right approach to versioning web services. If you haven't thought much about how you're going to version your services, definitely check out this article. John does a good job of getting you up to speed on the issues quickly - this is a difficult problem to solve in an elegant way.

This is something you might not pick up on while reading the article. Notice how John does not consider the use of strings or XML nodes an option for message versioning. He doesn't consider this because it's not recommended. Coupling is not loose or tight - there are varying degrees of it. Typing web service messages as strings is too loose, but not providing an extension mechanism or open content model is too tight. John is recommending a nice balance.

I didn't expect the article to effectively say, "here is how you should version your web services," which it doesn't, but, I like John's approach. He effectively says, "here are the issues and here are some principles that should guide your decision making." This is about the most you can ask for at this point. No one in the entire industry has come up with a definitive, elegant mechanism that addresses versioning for all types of services. I would like to see that happen someday. I'm currently working on some tooling that may result in great strides to this end. More later ;-)

What you can expect to find here

donsmith — Fri, 12 Aug 2005 12:50:00 GMT

You may not know this, but the patterns & practices team is pretty amped about making stuff that architects and Web service developers actually need (or at least make them happy). I know this because that's what they pay me for ;) If you're building Web services, are involved in an integration project, or are just interested in topics around enterprise architecture (like service orientation), you're going to want to monitor (or even subscribe to) this blog. And here's why ...

We have a bunch of stuff in the oven around Web service security, SAML, WS-I, WSE, integration patterns, and baseline architectures you're going to want to know about. No one wants their colleagues making fun of them for finding stuff out late ;) Not only am I going to let you know about things here long before you find out about it here, I'll give you the opportunity to influence its direction. So, if you see something you don't like, or have a suggestion to make it more like what you need, fire off an email to me. <MyBestRadioVoice>Why, you could even be the next champion.</MyBestRadioVoice> Okay, so here's what we have going on right now (I don't know if I'm going to keep this list updated as time goes on, but you should be able to figure out what we're up to by browsing the categories):

Web Service Security Patterns - This is huge! As you probably know, Web services are going up everywhere and a lot of them have security requirements. Transport level security (SSL) will be fine in some cases, but other services are going to need message level security (WS-Security). If you've looked into this, you know it's far from trivial. how are you supposed to know which token(s) to use ... X.509 ... Username ... Kerberos ... SecureContextToken for example? Well, these set of patterns cover the spectrum of architecture patterns, design patterns, and implementation patterns in WSE. In addition to the patterns, this asset has a navigation document to put you in the ballpark of the patterns you should be considering, and it has some primers to get you up to speed quickly on some of the concepts. Today, this stuff is in the CTP (Community Technical Preview) phase. All you have to do is join the community here (of course it's free), download the CHM file, and start reading. <RadioVoiceAgain>You'll be impressing your friends, family, and (more importantly) your manager in no time.</RadioVoiceAgain>

Applied Integration Baseline - This is also huge, but more in the literal sense. What I mean is this is the largest amount of code we've ever released at one time. Oh no, don't be scared ... because we even wrote a separate application, we call the Narrator, whose job is to help make sense of it all. So what is this thing? Well, we're all familiar with sample applications ... I like to call this a sample enterprise. One of the most difficult things to do in an enterprise is integrate all of the siloed applications so they consistintly share commonalities across the org. This asset shows how to compose patterns to address complex integration requirements using SQL, BizTalk Server, IIS, and .NET. The result is a baseline architecture to build on as you iterate over the implementation. The version for .NET 1.1 is here, the version for .NET 2.0 is here, and the community is here. You may also want to check out a flash version of the Narrator - very good stuff.

WS-I Basic Security Profile Reference Implementation - I'll spare you the description of who the WS-I is and if you've not heard of the BSP 1.0, you can read about it here. Well, this asset is basically the Microsoft version of the WS-I Sample Application. This is the app we'll use to consume the other vendor's sample apps and they will consume this one with their version ... all to test for the success of interoperability. This is one of the better sample applications I've seen. The security requirements are surprisingly complex. There's good stuff in here. I'll definately be blogging more about this one. Feel free to join the community and have a look at the code and supporting docs. Right now it is only targeting WSE 3.0, but we would consider building a WSE 2.0 version if the demand is high enough <PutsHandNextToEarListening />.

We have a couple of other things in the crock pot, but I don't have anything I can show you just yet. One is a SAML STS (security token service) Application Block. Well, we think we're going to release it as a block. What do you think?Right now the community is private. If you think (or know) you're going to implement SAML, are interested in this project, and are willing to provide us some feedback, fire me off an email mentioning this blog entry and tell us about your SAML plans. We'll invite you to the community so you can have a look at it now. The other project we have going is just in the very first stages and is easily my personal favorite. I can't wait to get this one in your hands. Unfortunately, I have to keep my fingers still for now. Much more later. Promise.

If you have any questions or comments, post to the forums and I'll see it in my inbox almost instantaneously.

Okay, I think I'm straight

donsmith — Fri, 12 Aug 2005 09:45:00 GMT

I was dorkin' around with my workblog the other day and it dawned on me that I never posted about how I recently switched jobs ... everyone blogs about this ... cool, so let me tell you what I'm up to these days ... and why you care.

I've been at Microsoft for about 5.5 years now and that whole time, I was a dev consultant helping customers with their enterprise applications focusing on Web services and XML technologies. On the 27th of June, I started a new position as the Product Manager for the Web Services & Integration program in the patterns & practices group and moved from Charlotte, NC to Redmond, WA. In my new role, I determine what assets we need to build based on customer and community feedback. Does that kick ass, or what? Everyday, I get to work with customers who are building Web services, the Web service community, and the WSE and Indigo product teams. I've only been doing it for 5 weeks, but so far ... it's awesome.

Alright, so why do you care? I've been asking myself a similar question ... what am I going to do with my workblog? Initially, I was thinking, I don't want to just talk about patterns & practices all the time. But the more I thought about it, I realized that's exactly what I should do - here's why. My program represents 1 of only 3 in the pattern & practices group. That should indicate we're pretty serious about it. And, we're 100% committed to letting the customer drive our actions (sometimes the product groups don't do this as well as they would like to). A lot of people think the Microsoft blogs have been successful because Microsoft as a company and our products are more transparent and it's easier for everyone outside of the company to communicate with us. We're really liking that too!

So yeah, I think I'm straight. I have a pretty good idea what I'm going to do here and why you should care. Unfortunately, you're going to have to go over here to find out ;)

Web Services Security Patterns ... finally

donsmith — Tue, 12 Jul 2005 11:28:00 GMT

The patterns & practices team has been working on a set of Web service security patterns for a few months now. Until today, the content was only available to those who were invited to join the community workspace. Now anyone can join the workspace and download the content. Better yet, a CHM version was just published so you get everything in a single file with search capabilities.

Don, what can I expect from this content? Well, when it comes to securing Web services, there are a number of things to consider (confidentiality, message integrity, authentication, authorization, etc) and you basically have 2 basic places to address these concerns: the transport and the message. IIS provides the facilities you need to accomplish transport-level security and if you're familiar with WSE, you know there are a number of tokens to help tackle the message security challenges (Kerberos, X.509, Username, SCT, etc). Okay, given all of this, how do you know which is the most appropriate given your solution's requirements and threat assessment? The Pattern Navigation section attempts to get you in the ballpark of the patterns you should be considering based on your security requirements and constraints. Also included are primers to help get you up to speed on certain topics if you need it. Check it out.

I'll blog about the stuff we have slated for the next release in a future post. See you on the workspace.

[Currently Playing :: Switchblade - Roger Clyne & the Peacemakers]

Versioning Web Service Parameters

donsmith — Fri, 03 Dec 2004 11:08:00 GMT

Dare makes a few comments about one of my previous posts so I thought - in true blogsphere fashion - I'd follow-up in a new post. First I'll mention a few more things about versioning web services, then I'll get to Dare's comments.

Versioning web services can be very challenging depending on the results you're trying to achieve. The primary decisions revolve around compatibility. First scenario, the easy way out: no compatibility. If you choose this route, it is highly recommended you implement a breaking change so your intentions are clear. So, for the next version of your service, you change the namespace, create a new endpoint address, and (re)deploy the clients for that service. When I said the easy way out, I was referring to versioning ... obviously not maintenance and deployments.

As you can imagine, there are a number of forces that can mandate a service implement a breaking change. The most common of these is driven directly from the business. The recommendation I make about using a single parameter for Web Service operations is strictly for the scenarios when we're applying a non-breaking change. We should always strive for compatible changes when we want to avoid the maintenance and deployment headaches evidenced above. I think most of this was understood in my previous posts, but I wanted to state it explicitly just to be clear.

I think it's also important to make a distinction between different kinds of Web Services, even if they're broad and sweeping. There is a considerable difference between a service-oriented Web Service and one that is not service-oriented. Perhaps my choice of GetTemp( TempRequest ) was a poor one. Service-oriented operations are very course-grained because they represent a business process. Because of this, the service interface is not likely to change (unless the organization is going to stop offering the service). However, the data pieces that service will require could very possibly evolve over time. Therefore, it's important to be able to version the service interface and the parameters of the operations independently. If you agree at this point, then we need a way to identify what version of the operation's inputs are being used. The only way to accomplish this with multiple parameters is for one of the parameters, which has nothing to do with the business logic of the operation, to contain version information. With a single parameter, we can maintain a straightforward experience for the client developer. Consider this message schema:

  <s:schema ... targetNamespace="urn:service">
    <s:element name="param" type="tns:UberParam" />
    <s:complexType name="UberParam">
      <s:sequence>
        <s:element name="param1" type="s:string" 
          minOccurs="0" />
        <s:element name="param2" type="s:string" 
          minOccurs="0" />
      </s:sequence>
      <s:attribute name="version" type="s:string" 
        use="required" fixed="1.1" />
    </s:complexType>
  </s:schema>

Just for completeness, the C# version of this parameter will look like this.

  using System.Xml.Serialization;

  [XmlType( Namespace="urn:service" )]
  public class UberParam
  {
      public string param1;
      public string param2;
    
      [XmlAttribute()]
      [System.ComponentModel.DefaultValue( "1.1" )]
      public string version = "1.1";
  }

By providing a fixed value for the version of the data type, the service developer has more metadata to work with and the client developer can focus on only the job at hand.

  UberParam uber = new UberParam();
  uber.param1 = "value";
  uber.param2 = "value";
  MyService.Operation( uber );

Depending on the requirements, a Web Service acting more in the role of a traditional API might not need this level flexibility. In these cases, I still recommend a single parameter, but without the need of additional metadata, the recommendation is less founded.

From Dare ...

Also the developer has to know how to manage interdependencies between properties of the TemperatureRequest that are set if there are any that are mutually exclusive, know which properties are required and whether to initialize primitive values in the object to defaults without any help from the API.

These issues are valid whether we have one parameter or multiple. The developer is still required to know something about the API and its requirements.

The other reason I like the former [multiple parameters] is that it carries the impression that the XML Web Service end point is unchanging while the latter [single parameter] does not.

As a client developer, I would find more comfort by feeling a single-parameter service is constructed in a flexible enough way to withstand the pressures of evolution.

One parameter to rule them all: Part 2

donsmith — Mon, 29 Nov 2004 09:51:00 GMT

In my post yesterday, I recommended that Web Service operations should only have a single input parameter rather than multiple for the sake of versioning. In the comments of that post, Todd makes some really good points why having multiple parameters isn't such a bad thing. Rather than responding in comment form, I thought [since I want to illustrate with code snippets] I'd just respond with a new entry. The fact that it also makes my new blog look more active isn't a bad thing either :-)

One of the most important considerations when designing Web Service endpoints is the message ... the XML on the wire. This is where the rubber meets the road. Decisions at this point will impact versioning, interoperability, and other factors in the future. This is why the WS-* specifications are primarily about what the message should look like rather than how the message should be processed. The importance on the message is also a primary motivation behind the contract first development approach Christian details here and Yasser writes about here. Let's have a look at a simple operation that uses multiple parameters: (yes, I'm eventually going to get around to my point ;)

[WebService( Namespace="urn:many-param-service" )]
[SoapDocumentService( SoapBindingUse.Literal, 
  SoapParameterStyle.Bare )]
public class Service : WebService
{
  [WebMethod]
  public ResponseType GetTemp( string city, string state )
  {
    return TemperatureLib.Calculate( city, state );
  }
}

The input type and input message are represented like this in the WSDL contract for the operation above:

<wsdl:definitions ...>
  <wsdl:types>
    <s:schema targetNamespace="urn:many-param-service">
      <s:element name="city" type="s:string" />
      <s:element name="state" type="s:string" />
      ...
    </s:schema>
  </wsdl:types>
  <wsdl:message name="GetTempSoapIn">
    <wsdl:part name="city" element="tns:city" />
    <wsdl:part name="state" element="tns:state" />
  </wsdl:message>
    ...
</wsdl:definitions>

Notice how the city and state parameters are not contained in another element, but are direct children of the s:schema element. I'll tell you why this is a problem in a minute, but the reason it's like that is because the wsdl:part names in the wsdl:message are not "parameter" and I specified SoapParameterStyle.Bare in code (they each impact the other depending on whether you're developing code-first or wsdl-first). "Okay Don, so why not just use SoapParameterStyle.Wrapped?" Because then every node of that wrapper element becomes a parameter - even if you don't want it to be. Meaning, there's no way to send extra non-parameter metadata to the operation. Okay, I know I'm getting too vauge here so I'll use an example. Suppose we want to send version information to the operation. In the example above, there's nowhere for it to go. "Why would we want to send version information to the operation?" Because as we version the operation, we should include version information so it's obvious what changed in each version. We can't get that information by simply adding new parameters to the method signature. I'm not going to go into it here (I will in my article) but there is a approach Doug talks about here about how to version datatypes that contain this version metadata. By using a single uber-parameter, we can include the traditional parameters as well as any metadata we need to send like version infomation. Then, instead of having to check for nulls, we can switch on the version metadata.

Just for completeness, this is what the code for a single parameter operation might look like:

[WebService( Namespace="urn:one-param-service" )]
[SoapDocumentService( SoapBindingUse.Literal, 
  SoapParameterStyle.Bare )]
public class Service : System.Web.Services.WebService
{
  [WebMethod]
  public ResponseType GetTemp( RequestType req )
  {
    ResponseType res = new ResponseType();
    res.City = req.City;
    res.State = req.State;
    return res;
  }
}

And the input type and input message in the WSDL contract for the operation will look like this:

<wsdl:definitions ...>
  <wsdl:types>
    <s:schema ...
      targetNamespace="urn:one-param-service">
      <s:element name="req" type="tns:RequestType" />
      <s:complexType name="RequestType">
        <s:sequence>
          <s:element ... name="City" type="s:string" />
          <s:element ... name="State" type="s:string" />
        </s:sequence>
      </s:complexType>
      ...
    </s:schema>
  </wsdl:types>
  <wsdl:message name="GetTempSoapIn">
    <wsdl:part name="req" element="tns:req" />
  </wsdl:message>
  ...
</wsdl:definitions>

A single parameter approach also has a bit to do with style. I don't feel the style aspect is as menial as how you use spaces in your method signatures because it adds a considerable level of consistency to them. And, as I mentioned above, it adds a level of elegancy to operations which consume metadata that doesn't work well as a traditional parameter.

Todd also states: "Sometimes it may make sense to put the new parameter on the TempRequest object, but not always. Following your example, if TempRequest really is Address, it makes sense to put a ZipCode field on the object rather than as another parameter to GetTemp. However, if ZipCode doesn't logically fit into TempRequest (ie, TempRequest is not an Address), then don't put it there."

That's the beauty of using a single parameter. It's not important whether TempRequest is an Address or not - or if it contains an Address or not. As far as the contract is concerned, we know it contains everything GetTemp needs to function. When we use a single parameter it will always make sense when something new is added. If you want to play with the differences between single and multiple parameters, I've posted some sample code here that might save you some time. Happy coding!

Two Web Service "Don'ts"

donsmith — Sun, 28 Nov 2004 02:40:00 GMT

There are at least 2 things I'm still seeing in some web service implementations we should not be seeing. In my first post, Refactoring XSLT, I was shooting for original ... interesting ... maybe even useful ... but not a best practice (at least not until more testing is done). In this post I'm writing about 2 best practices - independent of the platform (.NET, J2EE, etc) being used. One of them you've [hopefully] heard 1000 times and this will be your 1001st. You might not have heard the other one before ... or at least heard the rationale behind it.

Don't code on the edge

Web Services are essentially the buttons and textboxes other applications use to access some functionality. The endpoint (an ASMX file in the case of .NET) is just that ... an endpoint ... and that's all it should be. You have no business putting application logic in an ASMX page (or its codebehind) than you do in a windows form. I would even go as far as to say there should only be one line of code (2 at the max) in each of your exposed operations. How 'bout an example?

[System.Web.Services.WebMethod()]
public TempResponse GetTemp( TempRequest tempreq )
{
    return TempCalculator.GetTemp( tempreq );
}

As you can see, I'm calling a static GetTemp() method on a different class and returning its result. There might be another line if you have to call an instance method or maybe even another one if TempCalculator is on a different physical tier like Michele illustrates here, but the important thing to notice is the lack of any "temperature" code in the method's body. Let your business logic do that and put it in a different library assembly. "What's the big deal Don? Why not just put it in the codebehind?" If proper analysis and design have been accomplished on the business logic, it actually won't fit on the edge very easily. So, if you have business logic on the edge (in the endpoint operations or in the user interface) there's a very good chance the business logic has a poor design. Forcing the business logic in a separate library encourages solid software design.

One parameter and one return to rule them all

I'm actually illustrating this in my little WebMethod above. I'll admit my tent is pitched in the very middle of the messaging camp (opposed to the RPC camp), but that's not why I recommend only one input parameter and a single return type on all Web Service operations. The reasons really revolve around versioning and interoperability. I've been writing an article on versioning Web Service for months now to eventually be published on MSDN. I thought I lost it on a bad hard drive, but thanks to my close friend Yex, who still had a draft I sent him, I didn't have to start over from scratch. You'll have to take my word for it for now, but in the article I show how it is much easier to version datatypes (parameters and return types) than it is the interface of the operation. In other words, it's much easier to add a ZipCode member to our TempRequest type than it is to add a ZipCode parameter to our GetTemp() method while retaining compatibility with older and newer versions. We've also found the serialization behaviors between .NET and other platforms is very comparable with regard to custom types (opposed to primitive types). Lastly, it's a nice consistent pattern ... no surprises.

I think one of the reasons we're still seeing these bad practices is because developers aren't hearing and seeing them put in place often enough. DonXML talks about this problem in more detail here. I too have been guilty of using bad coding practices in demonstrations and sample code. Of course the main reason we do it is because we're trying to illustrate a certain concept and don't want to spend the time to work up a solid design. We also don't want to confuse the recipient with details outside of the thing we're trying to illustrate. So what's the answer? I think if we just point out the bad practices to the recipient - either using code comments or verbally - it would go a long way to curb this problem. You also know as well as I do that many real-world applications are just demos and sample code that has evolved. Let us all keep reminding everyone about the dangers of ignoring a solid design over productivity - becuase doing so will cause productivity to suffer eventually. Happy coding!