BizTalk 2006 Documenter

Documentation is always an important part of any project. Automating the documentation hasn’t been achieved its excellence. But various documentation tools are available for public use which will help us to create a decent base. One of them is Darren Jefford’s BizTalk documenter.

Download BizTalk 2006 Documenter:

http://www.codeplex.com/BizTalkDocumenter/

I have always found this tool handy whenever I have been asked to work on an existing BizTalk solution. For instance lets say you have been asked to work on an existing BizTalk Solution which comprises of 40 projects!!! Navigating through its reference projects, to understand the flow is always a painful process. I always use this tool to generate a help-file out of these BizTalk projects.

In another project, since my client was very much satisfied with the document generated by this tool, I have configured to run this tool as part of automated build (used MS-Build). so whenever our project changes, the project document will also be updated accordingly.

This tool is simple self-describing tool. But I have faced some problems initially and the solution is as follows.

• Make sure that you have the HTML-Help compiler when you have opt to generate HTML-Help version (MS-Word version is also available) of document. Download the HTML-compiler from here:

http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

• “Unable to locate the help compiler executable”

Ensure the “HelpComplieLocation” variable is assigned to the exact path of the Help compiler “*.exe” file in the BizTalkDocumenter.exe.config file

• “There was an error generating the XML document.”

This error is due to tracking enabled in any of your send port. Just for documentation sake disables the tracking in your send port and rerun the tool again.

• “Item has been already added. Key in dictionary: 'xxx.xxx.xxx.Orchestration' Key being added:'xxx.xxx.xxx.Orchestration'”

In rare case this error might occur. Ensure you have selected only the required BizTalk Applications in “Select Documentation Type”.

Host, Host Instance, Host Group

Recently I have met some developers who were new to BizTalk. They were having very vague idea about BizTalk host, host group and host instance. We all learnt this by experience but for a beginner, understanding the host model in BizTalk might take some time. So let me post an article which explains these for beginners.

Host:

The BizTalk host is a logical, process boundary for BizTalk artifacts like Adapters, Orchestrations, Send Ports, Receive Locations and Pipelines.

• BizTalk Host is not a physical entity; it’s a logical boundary
• We assign the host to Adapters and Orchestrations, Transport Types and its corresponding handlers to Send Ports and Receive Locations.

Ok, so what is the actual use of the BizTalk Host? These separate process boundaries (Host) enable us to create security boundaries and facilitate management.

Let's say that your company where the BizTalk application is going to be deployed is

·         Having different set of security policies for sending and receiving message from their stakeholders – by using different security certificates for receiving and sending any messages or by using different policies in their firewall.

·         Having different security access rights to receive/process/send – this can be achieved by providing different windows group to a host, which controls the access to the host and its associated host instance(s) to database and other resources

·         Having different set of throttling configurations for send and receive messages

·         More receive intensive where your messaging system receives more messages, then you can isolate the receive locations in a separate host.

Microsoft’s recommendation for the HOST model is to have separate Receiving, Sending and orchestration hosts both logically and physically. This model has been proved to be the most optimal configuration for achieving the highest throughput.

Based on the physical configuration and type of adapter hosted within, there are two types of hosts:

1.    In-process hosts.

2.    Isolated hosts.

In-Process host:

The logical process boundary which gets executed and managed within the runtime process of BizTalk Server engine.  

Isolated host:

The logical process boundary which gets executed and managed from outside the runtime process of BizTalk Server engine. In most of the cases, they run under IIS process boundary. Hence the adapters such as HTTP and SOAP (The adapters that runs outside of the normal BizTalk Server runtime process) are managed under isolated host.

Since the Isolated host exist outside the BizTalk environment, the BizTalk Administrator tool is not designed to show the status of the host (like Started/Stopped)  

Host Group:

Host group is nothing but a Windows-group which will be assigned to the host to control its associated host instance(s) access to the database and other resources.

When you initially configure the host, you will provide a Windows group which will be used to control access of the host and its associated host instance(s) to database and other resources

Make sure that the Windows-group which will be assigned to the host has got the “Login access” to the BizTalk-SQL databases like:

• BizTalkMgmtDb
• BizTalkMsgBoxDb
• BAMPrimaryImport
• BizTalkDTADb
• BizTalkRulesEngineDb

A host group requires the following privileges:

• It must be a member of the BTS_HOST_USERS SQL Server role in the following databases:

  • Configuration
  • MessageBox
  • Rule Engine
  • Tracking
  • BAM Primary Import

• It must be a member of the BTS_<<in-process host name>>_USERS SQL Server role for the MessageBox database

• It must be a member of the BAM_EVENT_WRITER SQL Server role in the BAM Primary Import database.

If you use the Configuration Wizard to create hosts, and if you specify a local Windows group for the hosts, the Configuration Wizard automatically creates two Windows groups. The default names of these groups are the BizTalk Application Users group and the BizTalk Isolated Host Users group.

Host Instance:

A host instance is a run-time instance of host in a server. Host instance runs within the security boundaries of the host and executes message processing on each machine belonging to the host.

The host instance executes in the associated server inheriting the logical boundary defined in the host.

When you create a host instance of a host associated with the host group, the host instance inherits the database privileges of the host group.

BAM in Depth for Developers

I have been reading an excellent white paper on BAM, I thought I should share this info. This white paper provides a deep, low-level review of how BAM works and how BAM can be extended. This white paper can be found at:

http://msdn.microsoft.com/en-us/library/dd320628.aspx

Cheers
M.R.ASHWINPRABHU

LoadGen-Testharness for SOAP transport

I have been using the LoadGen in the recent weeks. I have been using it as part of creating test harness for performance and stress testing in the BizTalk applications. I thought I’ll write a post about configuring LoadGen for SOAP transport. 

A sample scenario: I have a WebService (which I have been using it with my SOAP adapter), which will initiate the message flow in BizTalk. I would like to create a harness which will simulate the source application to post the request message and to receive the response message back from the WebService. 

Steps involved:

1. Create the WebService.
2. Configure the LoadGen.
3. Create the source file which LoadGen use to post).
4. Execute the LoadGen.

1. Create WebService

Following is the sample webservice to be used for the testing: 

Build and complie the webservice project. Access the webservice from the browser. Browse to the page where you can see the SOAP message formats. Following is the SOAP Request message for the above webmethod.  

2.Configure the LoadGen.

 Download and install the latest version of LoadGen (2007) from the below Microsoft link (http://www.microsoft.com/downloads/details.aspx?familyid=C8AF583F-7044-48DB-B7B9-969072DF1689&displaylang=en)

 Open the sample configuration file from <<installation drive>>\ LoadGen\ConfigFiles\ConsoleConfigFiles  

In this case since we are going to test the webservice which inturn return the response, we will select the “SoapToSoapTwoWayLG.xml” – it’s for SOAP two-way transport. In the config file, the root element <LoadGenFramework> contains two key elements  

1. <CommonSection>
2. <Section>

<CommonSection> element configures the default settings common to all LoadGen tasks in a LoadGen scenario. Some of the key settings are  

<NumThreadsPerSection>: Number of concurrent threads that LoadGen will use to send messages.

<SleepInterval>:Interval between the subsequent threads.

<LotSizePerInterval>: Number of messages that will be sent as a lot in each thread.

<RetryInterval>: Interval time to reattempt in case of failure.

<OptimizeLimitFileSize>: If file size becomes greater than the specified limit (in bytes), LoadGen will perform streaming for optimization.  

<Transport>: Transport protocol to be used for the LoadGen tasks. In this case SOAP.  

<Section> element configures the setting specific to a LoadGen task.

          <SrcFilePath>: Path of the source file for a LoadGen task

<DstLocation> Element contains the configuration settings for the LoadGen transport component.

<URL>: Specifies the URL of the WebService.

<SOAPHeader>: Specifies the SOAP action header for the request message to deliver.

<SOAPPrefixEnv>: Specifies the start tags of the SOAP envelope and the SOAP body.

<SOAPPostfixEnv>: Specifies the end tags of the SOAP envelope and the SOAP body.

<ResponseMsgPath>: Specifies the directory location for the response message.  

Coming back to configuring our sample webservice in LoadGen configuration file, perform the following steps (We are going to refer the SOAP Request message):  

• Specify the input file path for the LoadGen in <SrcFilePath>

• Specify the WebService URL in <Section>\<DstLocation>\<Parameters>\<URL> element as

• Specify the SOAPHeader in the format of "SOAPAction:[value]".

• To specify the SOAPPrefixEnv, copy the start tags of SOAP envelope and the SOAP body in a text-editor from our example:

Replace the “<” with “&lt;” and “>” with “&gt;”, now we should have

Copy the above content and paste it in <SOAPPrefixEnv></SOAPPrefixEnv> element, like

 

To specify the <SOAPPostfixEnv>, perform the similar replacements with the end tags of the SOAP envelope and SOAP body. Then we should have

 

• Specify the directory location for the response message in <ResponseMsgPath>

Following figure could help in easily identifying the LoadGen sections from the SOAP message

<Click on the image to see the clearer view>

Create the Source file:

 While configuring the <SOAPPrefixEnv> and <SOAPPostfixEnv> elements in the LoadGen configuration, we have specified the start and end tags of the SOAP envelope and SOAP body. We have not used the actual body of the message. Now we will use this to create the source file for the LoadGen. Copy the SOAP body content and paste it in a text-editor with sample value in it. (I have saved the file as InputSrcFile.txt as specified in the <SrcFilePath>)

As per your test criteria, configure the <CommonSection> element.

I have configured it to 1 file in 1  thread per section to execute the try run

For the complete LoadGen Configuration file for this sample webservice (my skydrive folder location):

http://p9grea.bay.livefilestore.com/y1pVA4-qMhhNrBuLy7yUCv2AyVKjBHI8htB-3b-fwMopx11lrCuSDv9g91MP-3c9RiPJv5YIJmH1KodvcTNlSDwkQ/LGSOAPTwoway.xml

Execute the LoadGen:  

From the command prompt, navigate to the installation directory of the LoadGen and type “LoadGenConsole” with its only parameter, the name of the LoadGenConfiguration file  

[installation directory]\LoadGen\Bins>LoadGenConsole TryLGSOAPToSOAPTwoway.xml 

 If you want to enable tracing for your LoadGen (its very essential in my experience), Uncomment the follwing lines from your LoadGenConsole.exe.config file from “[Installation directory]\LoadGen\Bins\”  

After executing the LoadGen, check for the response in the directory specified in <ResponseMsgPath>

BizTalk Server 2009 beta documentation

BizTalk Server 2009 - beta documentation is now available for download at: http://www.microsoft.com/downloads/details.aspx?familyid=38923F29-167F-497D-80A5-899602FEF8D7&displaylang=en

Cheers
M.R.ASHWINPRABHU

Technorathi Tags: BizTalk Server, BizTalk Server 2009