Don Smith : XML

Handcrafting WCF-friendly WSDLs

donsmith — Fri, 06 Oct 2006 10:30:00 GMT

It's 10:15 pm and I'm still in the office, but I really think I should get this entry posted before I head home - or it won't ever get posted. I was supposed to be working on my demo for my Service Factory session at the SOA Conference tomorrow, but I got side-tracked early in the day when I started playing with a new feature of Service Factory (that I'm going to demo). This new recipe (hereforth referred to as "the new recipe") allows you to create the service interface, data contracts, and a stub of the service implementation from an existing WSDL document. Yeah, pretty cool, huh? Of course you can do the same thing in svcutil if you have the .NET 3.0 SDK installed, but you have to leave Visual Studio and head off to the command prompt - and it won't separate the parts into multiple files and place them in the appropriate projects.

As I'm sure you've already realized, we've added this feature for the masses who have adopted a contract-first approach to building services. Unfortunately for these masses, the object model you have to code against after you've generated code from your existing WSDLs (using either svcutil or the new recipe) is not as enjoyable as what you get with the code-first approach WCF and its DataContract offer. I'm hoping this entry will add some clarity for those of you who wish to have the best of both worlds: Contract-First and DataContracts. First, let's talk about the DataContract.

The DataContract

Rather than start from ground zero with DataContract basics and the DataContractSerializer, I'm going to recommend you go read Aaron Skonnard's excellent Service Station article on Serialization in WCF before continuing. Okay, now that you know DataContract only supports a subset of XML Schema, let's get more specific about this "subset". I am in no way stating that this is a complete list, but these are the things I've personally been able to verify. If you use any of the following constructs, svcutil and the new recipe will fall back to creating XML serializable types (like the ones in ASMX) instead of DataContracts.

<xs:element ref= ...
<xs:anyAttribute ...
<xs:group ref= ...
<xs:attribute ...
<xs:choice ...
<xs:any ...
<xs:all ...

Of course this pretty much means to be safe, you need to stick with a <xs:sequence> of <xs:elements>. However, I was a little surprised to see that a <xs:simpleType> <xs:restriction> on a xs:string generated a very nice enum. Oh, News Flash! Kirill just responded to my email (hey, what's he doing on email this late?) and pointed me to some [internal] beta documentation that very clearly defines how all XSD constructs map to DataContracts. The doc looks awesome - I'll be sure to update this entry once it is live on the Web (if I don't, remind me). Okay, but you're not in the clear yet. You see, now we have to navigate the message wrapping issue.

The MessageContract

Because the DataContract is all about simplifying interop and the object model (OM), it hides wrapping element from the code, but (obviously) not from the WSDL. So, if you're going to import your handcrafted WSDLs, you need to know how to represent the wrapper "message" in WSDL in such a way that you don't have to deal with them in your OM. I think the easiest way to explain this part would be to start with a fragment of a WSDL and show what must change to get the right stuff in code. Consider this:

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  xmlns:srvc="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
                  xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
                  targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<wsdl:types>
    <xs:schema elementFormDefault="qualified"
                   targetNamespace="http://MyOrg.HrSrvc.DataContracts/2006/10"
                   xmlns:tns="http://MyOrg.HrSrvc.DataContracts/2006/10">
      <xs:element name="Employee" type="tns:Employee"/>
      <xs:complexType name="Employee">
        <xs:sequence>
          <xs:element name="ID" type="xs:int"/>
          <xs:element name="Name" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>
</wsdl:types>

<wsdl:message name="AddEmployeeSoapIn">
    <wsdl:part name="request" element="data:Employee" />
</wsdl:message>
<wsdl:message name="AddEmployeeSoapOut">
    <wsdl:part name="response" element="data:Employee" />
</wsdl:message>

<wsdl:portType name="IEmployeeManager">
    <wsdl:operation name="AddEmployee">
      <wsdl:input message="srvc:AddEmployeeSoapIn" />
      <wsdl:output message="srvc:AddEmployeeSoapOut" />
    </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="YouGetTheIdea"/>
</wsdl:definitions>

Yes, I know I'm sending and receiving the same type. I'm trying to balance between brevity and reality (cut me some slack). Hopefully at this point I have some contract-first readers nodding their head thinking, "Ok, I'll buy that - seems reasonable enough." Now let's look at how we would have to write this to get the nice dev experience with WCF ('cause this won't create it).

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:srvc="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<wsdl:types>
<xs:schema elementFormDefault="qualified"
   targetNamespace="http://MyOrg.HrSrvc.DataContracts/2006/10"
   xmlns:tns="http://MyOrg.HrSrvc.DataContracts/2006/10">
<xs:element name="Employee" type="tns:Employee"/>
<xs:complexType name="Employee">
<xs:sequence>
<xs:element name="ID" type="xs:int" nillable="true"/>
<xs:element name="Name" type="xs:string" nillable="true"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
<xs:schema elementFormDefault="qualified"
   targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
   xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
   xmlns:tns="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<xs:import namespace="http://MyOrg.HrSrvc.DataContracts/2006/10"/>
<xs:element name="AddEmployee"/>
<xs:complexType>
<xs:sequence>
<xs:element name="request" type="data:Employee"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="AddEmployeeResponse"/>
<xs:complexType>
<xs:sequence>
<xs:element name="AddEmployeeResult" type="data:Employee"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>

<wsdl:message name="AddEmployeeSoapIn">
<wsdl:part name="parameters" element="srvc:AddEmployee" />
</wsdl:message>
<wsdl:message name="AddEmployeeSoapOut">
<wsdl:part name="parameters" element="srvc:AddEmployeeResponse" />
</wsdl:message>

<wsdl:portType name="IEmployeeManager">
<wsdl:operation name="AddEmployee">
<wsdl:input message="srvc:AddEmployeeSoapIn" />
<wsdl:output message="srvc:AddEmployeeSoapOut" />
</wsdl:operation>
</wsdl:portType>

<wsdl:binding name="YouGetTheIdea"/>
</wsdl:definitions>

The highlighted areas are the parts I added/changed from the first snippet. It’s after midnight now. I’ve learned the beta of Windows Live Writer I was using has a length limitation and doesn’t color XML snippets (yes, I did this manually for your reading pleasure). So rather than continue to wow you with my use of compelling prose, I’ll just bulletize (see?) the significant parts:

· What’s up with the nillable=”true” on the data types? That actually turns out to be pretty critical. I haven’t really thought to much about why yet, but without this construct, it complicates the OM bigtime.

· What about that new schema … doesn’t that complicate the OM? Surprisingly not! It won’t even show up in the generated code. Notice how it imports the existing schema to reference the existing types, which do show up in the code. If you don’t explicitly create this wrapper, it will think the first element it finds (Employee otherwise) is the wrapper … yuck.

· Can the wrapper elements (AddEmployee & AddEmployeeResponse) be in the same namespace as the data type (Employee)? Well, that depends. They can if that namespace just happens to be the same as the service. In other words, the wrapper schema has to share the same namespace as the service. It doesn’t matter if the data types are in the same namespace or not.

· Don, is the fact you named the wrapper elements “AddEmployee” and “AddEmployeeResponse” important? Yes. If you don’t follow this convention, you’ll see these as types in the code … yuck!

· Let me guess, it’s also important that I name the data:Employee elements “request” and “AddEmployeeResult” respectively? Well, not really so much. If you name them something else, like “RequestMessage” and “ResponseMessage,” the System.ServiceModel.MessageParameterAttribute will step in to make sure the response message is correct on the wire, but it won’t affect the OM so much. It will look like this:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]

[ServiceContract(Namespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10"]

public interface IEmployeeManager

{

[OperationContract(Action="...", ReplyAction="*")]

[return: MessageParameter(Name="ResponseMessage")]

Employee AddEmployee(Employee RequestMessage);

}

· Alright, what’s up with the “parameter” message part names? Yeah, that’s important too. That basically says this contract is wrapped and not bare.

I think that’s about it. I’ll update this entry if I think (or learn) of anything else, but I’m going home now. Hope you find this helpful. BTW, I was listening to the Lemonheads the entire time I was putting this together … pretty cool.

WSDL.EXE problem with BEA WSDL

donsmith — Thu, 06 Jan 2005 10:47:00 GMT

As it turns out, using the 1.x builds of the .NET Framework, wsdl.exe (and VS.NET) are sometimes unable to process perfectly good WSDL documents generated from the latest versions of BEA WebLogic Workshop. If the WSDL contains multiple schemas, and any have the same targetNamespace as another, you'll get something like, "a schema with the namespace 'urn:foo-bar" has already been added."

There are not currently plans to fix this behavior in the 1.x versions of the framework. The product group is, however, planning to fix it in 2.0 (although it's not yet in beta 1 yet). Since I know at least 2 large Microsoft customers have hit this problem, I thought someone else might find this XSLT transform beneficial.

<xsl:stylesheet version="1.0" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:output method="xml" />
  <xsl:key name="matching-schemas" 
    match="xs:schema" use="@targetNamespace" />

  <xsl:template match="/|@*|node()">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="xs:schema">
    <xsl:variable name="matches" 
      select="key('matching-schemas', @targetNamespace)" />
    <xsl:if test="count( . | $matches[1]) = 1">
      <xsl:apply-templates select="$matches[1]" mode="consolidate">
        <xsl:with-param name="matches" select="$matches" />
      </xsl:apply-templates>
    </xsl:if>
  </xsl:template>

  <xsl:template match="xs:schema" mode="consolidate">
    <xsl:param name="matches" />
    <xs:schema>
      <xsl:apply-templates select="@*|node()" />
      <xsl:for-each select="$matches[position() != 1]">
        <xsl:apply-templates select="@*|node()" />
      </xsl:for-each>
    </xs:schema>
  </xsl:template>

</xsl:stylesheet>

I just threw it together and I've only tested it on a couple of WSDLs ... so you might want to verify the results with yours, but I think it's pretty solid.

At a higher level, this issue is usually a result of developing the Web service using a code-first approach in BEA WebLogic Workshop. As you will see is a common theme on this blog, I recommend developing Web services using a contract-first approach whenever possible, no matter what your platform.

I hope someone finds the transform useful. If you have any improvements or comments about it, let's hear 'em.

Refactoring XSLT

donsmith — Sat, 27 Nov 2004 02:06:00 GMT

I guess a quick introduction wouldn't be completely out of order for a first post. My name is Don Smith and I've been a Dev Consultant at Microsoft in Charlotte, NC for just over 5 years now. I spend most of my time helping our customers to be successful with Microsoft's XML technologies (XSLT, XSD, etc.), Web Services, and distributed architectures. I've been blogging for several years, but I'm just now deciding to join the MSDN blog party. Would love to hear from you if you feel so moved. :-)

Refactoring XSLT is a concept that originally dawned on me while delivering an XML development workshop earlier this year. Here's a touch of background. According to Martin Fowler, Refactoring is improving the design of existing code. With that in mind, one of the most common uses of XSLT is to transform XML data into HTML. Many enterprise web sites are divided [roughly] into 3 sections: the header, the main content, and the footer. If you've even seen or developed an XSLT stylesheet that results in HTML and has a considerable amount of code in the header and footer sections (or perhaps a non-trivial navigation system) you know the spaggetti code (mixture of code and HTML) required to get there is remnicient of Classic ASP. I'm not proposing there is a way to completely avoid the XSLT/HTML coupling, but this method can trim up your XSLT code and apply some structure to your solution.

The principles behind this approach are based on stylesheet extensibility (<xsl:include />) and factoring out large parts of the HTML into their own files. To illustrate this concept I'll use the following files:

Data.xml - A list of our fund raising volunteers and the amount of money they raised.
Content.xslt - The main stylesheet. It includes Common.xslt, Header.xslt, and Footer.xslt.
Common.xslt - A stylesheet that contains a script and template callable from other stylesheets.
Header.xslt - The stylesheet responsible for outputting the header HTML.
Footer.xslt - The stylesheet responsible for outputting the footer HTML.
Header.txt - A text file containing the HTML for the header section.
Footer.txt - A text file containing the HTML for the footer section.
Config.xml - A file that contains the locations of the header and footer files.

Below are enough files to get the idea of how this approach works ...

Data.xml - nothing special here; just a simple XML document

<?xml version="1.0" encoding="utf-8" ?> 
<contributors xmlns="urn:fund-raiser">
  <volunteer>
    <name>Joe Blow</name>
    <amount>58.25</amount>
  </volunteer>
  <volunteer>
    <name>John Doe</name>
    <amount>81.50</amount>
  </volunteer>
  <volunteer>
    <name>Jane Blow</name>
    <amount>89.75</amount>
  </volunteer>
  <volunteer>
    <name>Julie Doe</name>
    <amount>96.00</amount>
  </volunteer>
</contributors>

Content.xslt - as you can see, this file's sole function is to produce the main conent for the page (the table). Its call to the Header template will resolve to the Header.xslt include and likewise for the footer. The Common.xslt isn't used by anything in this file. Rather, it will be used by the header and footer (or any other child) stylesheets.

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:v="urn:fund-raiser"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:include href="Common.xslt" />
  <xsl:include href="Header.xslt" />
  <xsl:include href="Footer.xslt" />

  <xsl:template match="/">
    <xsl:call-template name="Header" />
    <table width="250">
      <xsl:apply-templates select="v:contributors/v:volunteer"/>
    </table>
    <xsl:call-template name="Footer" />
  </xsl:template>

  <xsl:template match="v:volunteer">
    <tr>
      <td width="50%"><xsl:value-of select="v:name" /></td>
      <td width="50%"><xsl:value-of select="v:amount" /></td>
    </tr>
  </xsl:template>
  
</xsl:stylesheet>

Header.xslt - all of the header HTML data is in an external file defined in Config.xml. The path is retrieved and passed into the FileContents template as a parameter. The FileContents template will resolve to Common.xslt.

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template name="Header">

  <xsl:variable name="headerfile" 
    select="document('Config.xml')/configuration/header" />

  <xsl:call-template name="FileContents">
    <xsl:with-param name="filepath" select="$headerfile" />
  </xsl:call-template>

</xsl:template>

</xsl:stylesheet>

Common.xslt - this is the only part of the solution I'm not crazy about: the script. Granted, even if you're not using .NET, most popular XSLT implementations have similar extension facilities. As you can see below, the FileContents template calls the GetContents function to retrieve the contents of the header. The XPath document() function can't be used here because the header and footer files don't contain well-formed markup.

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0"

  xmlns:fac="urn:factoring-xslt"
  xmlns:msx="urn:schemas-microsoft-com:xslt"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <msx:script language="c#" implements-prefix="fac">

    public string GetContents( string filepath )
    {
      try
      {
        using( System.IO.TextReader reader = 
        System.IO.File.OpenText( filepath ) )
        {
          return reader.ReadToEnd();
        }
      }
      catch( System.Exception ex )
      {
        return ex.Message;
      }
    }

  </msx:script>

  <xsl:template name="FileContents">

    <xsl:param name="filepath" />
    <xsl:value-of select="fac:GetContents( $filepath )" 
      disable-output-escaping="yes" />

  </xsl:template>

</xsl:stylesheet>

If you want to play around with these files, feel free to download my sample solution here. I've never seen this approach used anywhere and I've never seen anyone else mention it. I thought a purely original post would be a good start on MSDN. So, if you decide to implement any of these ideas, please test thoroughly. I can't stress that enough. Here are some other resources you might find useful:

If you have any thoughts about this stuff, I'd love to hear 'em. Happy coding!