BizTalk server relies on a config file to store certain application information. This config file is located in \Program Files\Microsoft BizTalk Server 2004 and is named BTSNTSvc.Exe.Config. View your file here (DO NOT CHANGE THIS FILE WITHOUT BACKING UP!!!).
Let’s say that you have some .NET components that you want to consume from your BizTalk solution. Let’s also assume that these components are possibly shared with another solution, and make use of a config file for things such as connection strings, directory locations, etc., a fairly common situation. Now, keep in mind when you call a component, and that component makes use of a config file, it uses the config file of the calling application (at least for EXE’s). So, we have a couple of options. We can take what’s in the shared components config file and paste it into the BTSNTSvc.Exe.Config file. But, this means we now have 2 places to maintain the information. What if we then have a multi server configuration, we now have 2 config files to maintain in more than one location. Not good. Wouldn’t it be nice if we could somehow have the BizTalk config file “point” to the components config file? Then, we could maintain the other applications config file as we normally would. Well, the good news is you can.!!!
Take a look at my sample config file to follow along. I’ll explain a couple of the sections. It is important to remember to always take a copy of you current BTSNTSvc.Exe.Config file before making any changes as changing it incorrectly will prevent BizTalk from running.
The key to making this work is the section. To make this section “available”, you will have to add the following under the section of your config file –
Now that we have this in the config file, we can add the section . I won’t copy it here to save space, so look at the example. This section is where all the magic happens. Some of the attributes like AssembliesPerDomain, etc you can find information about in the help documentation. The key sections to be aware of are the section, section, and the section.
This section defines a new domain for your particular situation to run in. *** define this a little better. You will give your domain a name, and then you will use this name later to correlate the calling piece of your BizTalk solution with the called components config file.
This section defines where the called components config file resides. You can use absolute paths, or I believe you can use relative paths also.
In this section you are going to link your AppDomain (which contains the ConfigurationFile section) to the part of you BizTalk solution that calls the shared component. Let me clarify “part of your BizTalk solution”. When you create your orchestrations, you give them a namespace. They probably run under the same namespace, or at least the same root namespace. So, in the example you see “Source.Test.Orchestrations.*” as the pattern assignment rule. What this is saying is that any orchestration that is under this namespace would be associated with that particular app domain, and would then be able to make use of the configuration file listed under that app domain.
Hopefully with the example and the explanation, this will make some sense. There is some information in the help file about adding the new sections, but they don’t go into much detail of how all the pieces fit together, and what the pattern assigment rule is really supposed to point to, etc.
DON’T FORGET…BACK UP YOUR CURRENT CONFIG FILE BEFORE MAKING CHANGES. This will save a lot of headaches.
One last point to remember…and I won’t go into a lot of detail, but remember that if you are calling components from BizTalk, they must be GAC’d. It is possible that the shared components you are calling didn’t require to be GAC’d prior to calling them from BizTalk. Now that they are in the GAC however, you will need to change your shared components config file slightly. When you are defining your section for that component, you will have to change the attributes a bit so that you are including the following –
<SECTION type=", Version=, Culture=, PublicKeyToken=” name=”” />
The values for component name, version, culture and token you can get out of .NET Framework Configuration admin tool. Just look for you component, and make note of the values listed. The only one that should change would be the version.
Have you seen an error that looks like the one below on your Send Pipelines?
There was a failure executing the send pipeline: “Microsoft.BizTalk.DefaultPipelines.XMLTransmit” Source: “XML assembler” Send Port: “some location” Reason: This Assembler cannot retrieve document specification by using this type: “namespace#rootnode”.
This is caused by not having a unique combination of namespace and root node (MessageType). BizTalk by default does not like unrecognized messages. The XML Disassembler has a setting to allow unrecognized messages. But what about sending unrecognized messages?
To allow unrecognized messages inside the Send Pipeline, just set the XMLNORM.AllowUnrecognizedMessage message property to True inside a Message Construct shape. This, of course, assumes you have to construct your output message inside the Orchestration.
The statement inside your Construct shape should look like this:
OutMessage(XMLNORM.AllowUnrecognizedMessage) = true;
I found out tonight that Delivery Notification set to Transmitted works differently for Send Groups. In the case of Send Groups, no NACK is returned if any of the Send Ports in the group fails.
I think most BizTalk users have some idea about what Property Promotion is. I would say Property Promotion is the process of taking message or system data and putting it into the message context. The tricky part is when and how properties get promoted.
The items that are promoted using a property schema attached to your schema are promoted in the pipelines. When and how the system properties are promoted is somewhat of a mystery. I think some items are promoted in the adapters (like the specific file, HTTP, and FTP properties) while others seem to be promoted as the messages enters or leaves the Orchestration (like Sending Orchestration Type).
Some properties are only available inside the Receive Pipeline and Orchestration (like Received Port Name and Received File Name). In the sample below I manually copy them into the message inside the Orchestration.
It is possible to overwrite read only properties inside the pipeline (like MessageType). This is dangerous but I am sure could have some benefits. The MessageType property is read only inside the Orchestration but if it is promoted inside the Receive Pipeline the promoted value is used rather then the true message type.
It appears that system properties that are manually promoted in the Receive Pipeline are carried throughout the whole message flow and the system does not change them. I can set Message ID to 12345 on the Receive Port and that value comes back out on the Send Port. But, this message ID does not seems to actually be used internally.
MessageType on the other hand is used by the system if promoted in the Receive Pipeline. If I change this property, it shows up in HAT with the value I set for it. I have found one exception to this. It is the MessageType property when working with untyped messages. That property is cleared when the message is sent out of the Orchestration.
Property Demotion. This is something a little less known to BizTalk users. This is the process of taking message context data and putting it into the message. This is done in the Send Pipeline. It is sometimes hard to determine what values are actually in the context and only values in the message context can be demoted.
CRITICAL: If you use a pass through pipeline your properties are not demoted. They are only demoted using the XML Assembler component.
Ok, so how do you go about Demoting values into your message? First, you have to add the Property Schema to your schema that contains the values you want to demote. If you want BTS System properties follow the steps below.
How to add the BizTalk System Properties Schema to your Schema:
1. Go to the Promote Properties Dialog Box
2. Go to Property Fields Tab
3. Go to the BizTalk Type Picker by clicking on the folder icon
4. Expand Microsoft.BizTalk.GlobalPropertySchema
5. Select BTS.bts_system_properties
Then, follow the same steps just like you are promoting the properties by selecting the elements you want to promote and select the corresponding element in the Property Schema. It is that simple.
CRITICAL: If you have the same schema on the inbound and outbound you may inadvertently promote or demote values.
I have put together a sample working with both Typed messages and Untyped messages. I have included several start messages that set various values. You can check out the schema to see how I accessed the propertied for Promotion and Demotion.
DOWNLOAD: Promotion and Demotion Sample
Take Away: Property Promotion and Demotion is an important part of BizTalk allowing for message context data to be demoted into a message that is sent out of the system.
Make sure you check out Todd Uhl’s Blog. He has a sample working with Role Links in BizTalk 2004. This is something I had not looked into yet but his sample makes it look easy and useful.
Todd is working on the Tech Arch team on my current project. Watch for more great deployment and architecture posts from him in the near future.
Here is another sample of a Sequential Convoy in BizTalk 2004. This is a little different then most, it contains a Parallel Action shape that allows for concurrent parallel processing of inbound messages.
What does this accomplish? It is all about control. This process allows for processing a pre-defined number of messages at the same time in a controlled manner.
Performance? Ok, it is not the fasting running Orchestration I have ever seen. Actually, in some of my tests this parallel action processed 1/2 to 1/3 less messages per minutes then a single process convoy. In case you are wondering, running 100 messages has 203 persistence points.
What’s the point then? Well, I could see a need for something like this in a de-batching scenario when the parallel actions will take an unknown account of time to complete and the overall status of all the messages is important.
Download the sample below. I have 4 parallel actions processing messages. I added a random delay to simulate message submission to an outside system or web service. I have a Win Form test harness for easy running. If you want to test the performance, download my single convoy example and remove the delay shapes inside this sample.
The key to this solution is the Synchronized Scope shapes that maintain the overall message count inside the Orchestration.
DOWNLOAD: Parallel Sequential Convoy Sample
See the read me file for set up instructions. Make sure you run “Clean Up” before you rerun and samples.
A better approach? I think it would be better to remove the processing logic inside the Parallel Actions and call an additional Orchestration to do any work. This would increase the overall flexibility and maintenance of the solution.
Take Away: Parallel Convoys allow for better control of your de-batching process but the overall throughput of your messages is decreased.
This is another Sequential Convoy Message processing sample using an Orchestration. This sample uses the Parallel Action Shape to process multiple records at the same time. This could be used to slow down message processing inside Biztalk and process messages in a controlled manner.
This sample should work for BizTalk 2004 and BizTalk 2006.
Get more information from the original blog post on this topic: http://www.biztalkgurus.com/biztalk_server/biztalk_blogs/b/biztalk/archive/2004/10/05/parallel-sequential-convoy-in-biztalk-server-2004.aspx
This simulates an orchestration callrules action from code:
MyArrayList = new System.Collections.ArrayList();
MyPolicy = new Microsoft.RuleEngine.Policy(YourPolicyName);
MyTracer = new Microsoft.RuleEngine.DebugTrackingInterceptor();
You will have to create your facts in here. Use TypedXmlDocuments or custom objects (see the BizTalk help for samples)
The aboveline will redirect the traces to the windows event trace.
Use the excellent debugview
utility from sysinternals to view the traces.
I applogize for being anything but prompt on this.
The zip file can be found here.
Steps for setting up Role Link Sample –
1. Create a receive port in BTS Explorer
2. Create 2 send ports – RoleLinkTest_Approver1 and RoleLinkTest_Approver2
3. Set your transports, send or receive locations, etc for your ports
4. Create a party called Approver1. Choose RoleLinkTest_Approver1 as their send port.
5. Create a party called Approver2. Choose RoleLinkTest_Approver2 as their send port.
At this point you should be able to deploy the project. Once the project has been successfully
deployed, you should now have a new Role listed in BTS Explorer called
RoleLinkSample.RoleLinkTestOrchestration.Purchasing.Approver. This is from the role link type we
6. Right click on the new Role and select “Enlist Party”. Choose are 2 parties. From this point
forward, if you wanted to add new parties (for new trading partners perhaps), you would just repeat
steps 4,5 and 6…it’s that easy!!!
Now you can run the test files through. Read back through the previous post on role links, and
follow along this example (pay attention to the expression shape that initializes the ports).
Hopefully it will make a little more sense.
Please let me know if you have any questions, or if the setup instructions are lacking.
ooops, almost forgot..take a look at the 2 files you’ll be submitting, and don’t forget to point the project to a keyfile.