Receiving RawStrings…

(See update below)

If you have attempted to send email from BizTalk, you’ve gotten pretty comfortable
with this documentation
topic.

It discusses how to use a sample class (Microsoft.XLANGs.CustomFormattersSDK.RawString)
and associated custom formatter to deal with messages that contain raw string content. 
As the docs say, “Sending a message of type System.String will not work, because
the string gets formatted as an XML document in the message, which is not your desired
solution.”  (In other words, whether you send or receive, using System.String
as a message type means you are dealing with a wrapping tag.)

However, though the docs cover sending RawStrings, it is less clear how you
can use the RawString class when you want to receive messages as such.  Just
typing the port operation as RawString will yield a UnexpectedMessageTypeException,
because none of the default receive pipelines will set the MessageType context property
on inbound messages to be RawString – and this type matching is what orchestrations
expect.

We need a custom receive pipeline that will set the MessageType context property equal
to the fully qualified type name for RawString.  Jon’s discussion of receiving
binary messages provides some background here, and Jon’s ContextAdder pipeline
component can make the MessageType context property assignment very easy.

Here are the steps required to receive RawStrings:

1. Download & build Jon Flanders’ ContextAdder pipeline
   component, and make sure the build outputs end up in your Microsoft BizTalk Server
   2004\Pipeline Components directory.
2. Build this
   code (the RawString class & custom formatter) into a separate C# library (with
   a strong name) and deploy it to the GAC (if you haven’t already when dealing
   with email.)
3. Use the RawString type on the orchestration port operation that you are trying to
   receive RawStrings on…

4. Create a receive pipeline (ReceiveRawString), and add the ContextAdder pipeline component
   in the Validate stage.  (You will only ever need one such pipeline around –
   put it in a common library.)  Configure the properties collection with the properties
   for RawString, as shown below (“Value” property will be the full five-part
   assembly-qualified type name):

5. Specify the ReceiveRawString pipeline for the associated physical port.

Now you will have full access to the raw string content, and can do whatever you need
to do…You might want to declare an orchestration variable of type RawString,
and assign it to the RawString message so you can access properties/methods like ToString(),
which returns the underlying string content.

>

Update:

Greg Van de Wiele has pointed
out the other way to go about this (and Jon has talked
about this approach in his recent posts as well.)  It can be less work
in that no custom pipeline is required (a one time task) – though perhaps a little
harder to explain to the “next guy“…you can decide!

It goes like this:

1. You will need to do step 2 from above.
2. Use the XmlDocument type on the orchestration port operation that you are trying to
   receive raw string content on, and use a PassThruReceive pipeline.
3. Create a multipart message type, with a single part that is of type RawString. 
   Also, declare an instance of this type, say, tempRawStringMsg.
4. Receive the message from the port in step 1 into an XmlDocument-typed message (say,
   xmlDocIn)
5. Drag out a message assignment shape.  In the expression, do: tempRawStringMsg.rawString
   = xmlDocIn;
6. As before, you might want to declare an orchestration variable (not a message) of
   type RawString, and assign it to tempRawStringMsg.rawString so you can access properties/methods
   like ToString(), which returns the underlying string content.

Note that not wrapping the RawString in a multipart message doesn’t work
– you will get a compiler error indicating that assignments can’t be made between
XmlDocument and RawString types.  Also note that introducing an intermediate
message has a performance cost.