(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.

(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.

Andy Morrison wrote
about a technique for identifying the correct host instance to attach to when
debugging components associated with orchestrations.

A potentially easier solution is to keep perfmon running with the counter shown below
(BizTalk:Messaging/ID Process – all instances.)  The counter values will update
every time a host instance recycles.  The Debug-Processes dialog in Visual Studio
will show you (and allow you to sort by) process IDs to make this easy. 

Then put PerfMon in “report view” to easily see process IDs by host instance:

Andy Morrison wrote
about a technique for identifying the correct host instance to attach to when
debugging components associated with orchestrations.

A potentially easier solution is to keep perfmon running with the counter shown below
(BizTalk:Messaging/ID Process – all instances.)  The counter values will update
every time a host instance recycles.  The Debug-Processes dialog in Visual Studio
will show you (and allow you to sort by) process IDs to make this easy. 

Then put PerfMon in “report view” to easily see process IDs by host instance:

There have been several folks who have discussed how to create messages “from scratch”
within an Orchestration context – you can read Matt’s
thoughts and check out a BizTalk documentation
excerpt. This is a common question, and I had an additional technique I thought
I would share… 

Background: When you have a schema that has many promoted properties (or distinguished
fields), or many elements that can be set via xpath expressions easily, it can be
useful to simply start with a “template” document instance and populate the element
content that you are interested in. 

In this situation, you will often have a “Message Assignment” shape that looks something
like this:

xmlDoc.LoadXml("<ns0:BizTalkSampleS3 
      xmlns:ns0="http://BizTalkSample.Schemas.BizTalkSampleS3">
      <SomeElement></SomeElement></ns0:BizTalkSampleS3>");
someMsg = xmlDoc;
someMsg.SomeElement = "some content";
// (or xpath(someMsg,someElementXPath) = "some content" if we don't have a 
// distinguished field.)
   

One disadvantage of loading up “template” xml documents from either expression shapes
or code (via XmlDocument.LoadXml) is that those xml fragments can get easily “lost”,
and are hard to update early in the development cycle when schemas may still be in
flux.  Loading the template files from the file system is problematic because
the question arises “where should I store these files, so that I can find them in
any environment I deploy to?” (Solvable, but a hassle.)

Instead, why not embed the template xml documents as assembly resources?  For
those unfamiliar with that process, I have a short tutorial here (& a helper class.) 

1. You will need a C# project as part of your overall BizTalk solution.  Place your
   template xml file(s) in the directory corresponding to this project, and add them
   as an “existing item” to the project. 
2. Select this file within the Solution Explorer, and within the Properties window, select
   “Embedded Resource” as the “Build Action” as shown here:

    

3. Place this
   class (text here)
   within the same C# project that houses the resources you have added.
4. To construct a message, drag out a “Message Assignment” shape, and within the associated
   expression write some code like the following.  Simply pass the file name of
   the template document as an argument to GetXmlDocResource (or GetStringResource.)

   sampleUsingTemplate = 
      BizTalkSample.Components.EmbeddedResourceCache.
         GetXmlDocResource("BizTalkSampleS3_output.xml");
      // Populate the "rest" of the message with distinguished fields, promoted 
      // properties, xpath expressions, etc.
      sampleUsingTemplate.SomeElement = "foo";
               

The class I have supplied will cache the loaded resources in a hashtable for performance
sake, and allow you to load resources as both strings and XmlDocuments.

A last thought: Many people ask, “Why can’t I just create a message using a new operator
or a default constructor of some sort?” Well, because few XSD schemas sufficiently
constrain the set of valid instance documents enough for that to be useful – what
form would a “default message” take? (Would it have the optional elements you need?
Some elements that you don’t want?)

Enjoy – feedback appreciated!