Enumerated types in Web service interfaces and BizTalk

On my last Biztalk project, I had to call a Web service interface containing an operation with an enumerated data type. As it turned out, that’s a non-trivial task. You would think that importing the WSDL would create a .NET enumerated type which you can use in a Message Assignment shape.

Instead BizTalk creates an XML Schema for the enumerated type. You can get see the schema file if you expand the Reference.map node under your Web Reference

In the schema you’ll find a simpleType definition and a corresponding element definition. What’s odd is that the parameter in for the enumerated type expects you to assign the full element, not just a valid value of the enumeration.

This may seem odd to you if you are used to consuming Web services in .NET applications, where you simply assign the parameter value. Let’s take a look at the enumeration definition in the following schema and I’ll show you what I am talking about:

<xs:schema xmlns:tns=" urn:my-log-service" elementFormDefault="qualified" targetNamespace=" urn:my-log-service" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Severity" type="tns:SeverityType" />
  <xs:simpleType name="SeverityType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Debug" />
      <xs:enumeration value="Information" />
      <xs:enumeration value="Warning" />
      <xs:enumeration value="FatalError" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

If you were to consume a Web service that has a parameter of the SeverityType in a regular C# application then wsdl.exe would generate an enum for the SeverityType and a methods that takes a parameter of that type like this:

    [System.Xml.Serialization.XmlTypeAttribute(Namespace=" urn:my-log-service")]
    public enum SeverityType {
        Debug,
        Information,
        Warning,
        FatalError,
    }

    public void Log(SeverityType sev, string text)

When I need to send a Log message to the Web service, the imported enumeration allows me to write simple C# code like this:

LogService svc = new LogService();
svc.Log( SeverityType.FatalError, logText );

and the Xml serialization plumbing in the Web service proxy will produce the a SOAP message with an XML representation like this:

  <soap:Body>
    <Log xmlns="urn:my-log-service"/>
      <sev>FatalError</sev>
      <text>Things are really messed up right now</text>
    </Log>
  </soap:Body>
Both parameters are embedded in the body.

In BizTalk, the programming model is different. It's not as simple as just assiging the literal value to the sev parameter. If  Message_1 is the message you are sending to the Web service, you cannot just say:

Message_1.sev = “FatalError“;

because the sev parameter is of type SeverityType. If you're familiar with XML Schemas then you might argue that SeverityType is really just a string that can only take certain values -- and you're fully correct. However, BizTalk think about it slightly different. It expects that you assign a SeverityType to sev. How would you do that?

You actually have to assign the complete <Severity> element from the schema, which is of type SeverityType, to the <sev> parameter, even though only the element value needs to go into the message sent to the service.

One way to set up the message in BizTalk is to load the XML element into a variable of the .NET XmlDocument type. If Message_1 is the message to send to the service and doc is an XmlDocument variable then you would populate the message in a MessageAssignment shape with the following code:

doc.LoadXml("<Severity xmlns='urn:my-log-service'>FatalError</Severity>");
Message_1.sev = doc;
Message_1.text = "Things are really messed up right now";

This looks like the SOAP message would contain an extra Severity element:

      <sev><Severity>FatalError</Severity></sev>

but that is not the case. The message going to the service is the same as in the C# example above.

If your orchestration deals with many messages that contain enumerated types then writing all the message generation code in a separate .NET assembly is a good idea. It would keep the code in the message assignment shapes much cleaner and the orchestration developers don’t need to think about extraneous XML elements.