Embed Size (px)
Citation preview
Page 1
Issue 9 Q1 2010
Table of Contents BizTalk Alerts in SCOM are flooding my e-mail Inbox, Help! ........................................................................ 2
Connecting BizTalk Server to Websphere MQ ........................................................................................... 18
Using a WCF Runtime Proxy to consume Services ...................................................................................... 47
BizTalk Dashboard ....................................................................................................................................... 60
Dynamic Send Ports .................................................................................................................................... 67
BizTalk 2009 Oracle Integration using the BizTalk Adapter Pack 2.0 .......................................................... 77
Querying a SQL Server Table using Business Rules…………………………………………………………………………………90
Page 2
BizTalk Alerts in SCOM are flooding my e-mail Inbox, Help! Written by Andrés Naranjo, Microsoft Premier Field Engineer.
So you’ve spent long hours configuring your BizTalk environment to integrate your business
applications, and perhaps even longer hours developing orchestrations and business rules to automate
your business processes. You’ve deployed your BizTalk artifacts onto a server group, and even took the
bold step of implementing a BizTalk monitoring solution using Microsoft’s System Center Operations
Manager (SCOM1), with the BizTalk Management Pack. Now all should be right in the world and you can
sleep at night, correct?
Well, that’s the theory. The reality, however, may be a bit more problematic. Suppose for example
that one of the downstream systems you integrate with becomes unavailable, say a WCF service a
partner exposes, goes down for maintenance and they didn’t warn you. While that’s happening, you’re
sending hundreds, or thousands of messages to that WCF service, and expecting a response so you can
continue your business processes. From the BizTalk perspective, this is not a problem, merely an
annoyance. The outgoing messages will be suspended on the outbound leg of their journey, and once
the target WCF service comes back up, you can resume the messages and go on with your business.
That is provided, of course, that SCOM alerts haven’t filled up your e-mail Inbox with alert e-mails
indicating this message or that message has been suspended. You see, by default, the BizTalk
Management Pack is configured to detect message transmission failures and raise an alert for each
message that is suspended. Each message, being a unique instance of data, causes its own alert and is
treated as a single entity from the Systems Center Operations Manager perspective. So if you have
configured e-mail or SMS alerts for BizTalk failures, each message suspension and their equivalent SCOM
alert, will generate a corresponding e-mail or SMS. By the time the downstream WCF service becomes
available, your e-mail Inbox could be essentially full of e-mails all indicating essentially the same
problem, albeit with different message instance IDs.
Figure 1 demonstrates this effect from the perspective of the SCOM admin console. Notice the first
portion I highlighted, showing a message count of 196 alerts, and compare that with Figure 2 which
displays the BizTalk admin console’s Group Hub view, showing the equivalent 196 suspended messages.
Under normal circumstances, this would result in 196 e-mails or pages or SMS messages if SCOM
notifications have been configured.
1 System Center Operations Manager (formerly MOM) is Microsoft’s solution for enterprise monitoring and
management. It provides a flexible and customizable framework for the monitoring of every Microsoft Enterprise product, through the use of Management Packs, released by both Microsoft, and Microsoft Partners, which supply the heuristics and logic necessary to dynamically discover and monitor artifacts, and generate alerts and notifications when undesirable events or conditions occur. With SCOM and the appropriate management packs, you can monitor events, performance, log files, web URLs, application configuration settings, service and process availability, and much more.
Page 3
Figure 1: SCOM Admin console - Alerts View
Figure 2: BizTalk Admin console - Group Hub
The initial response from SCOM administrators might be “we must override the BizTalk Management
Pack, to somehow disable the alerts.” However, disabling alerts just because there are too many
instances of the alerts is contrary to the objective of implementing SCOM and the BizTalk Management
Pack, namely to make BizTalk administration easier. So the objective is to override the BizTalk
Page 4
Management Pack, but to do so in such a way that we do still get alerted when messaging operations
fail, just not thousands of times.
How, then, do we prevent SCOM from generating these thousands of alerts? There is a little known
piece of functionality for SCOM monitors and rules whereby alerts can be configured to be grouped
according to one or more properties of the alert. As a result, multiple alerts with the same values for
these properties are grouped together, and instead of generating new alert instances, SCOM simply
increments the alert count.
The first hurdle we must clear is the fact that the BizTalk Management Pack for SCOM is sealed.
Essentially, a certificate has been applied to the management pack so as to prevent it from being
changed in any way. This does not mean that the settings of the BizTalk Management Pack are final,
because what we can do is to create a custom management pack, and to override certain settings of the
BizTalk Management Pack so as to achieve an end-sum where SCOM behaves more to our liking.
The basic plan is as follows:
1. Create our custom management pack.
2. Find the BizTalk SCOM alert we want to change.
3. Document the settings of the BizTalk Management Pack alert we want to change.
4. Override the BizTalk Management Pack alert, so as to disable it.
5. Create a brand new alert, with the settings we documented earlier.
6. Change the grouping properties so alerts are grouped as per our criteria.
Creating a new custom management pack is fairly straight forward, and as a general recommended best-
practice, you should have a custom management pack for every sealed management pack. After
opening the SCOM Administration Console, open the Administration section, right-click on Management
Packs and select Create Management Pack. In the dialog box which opens up, give the Management
Pack a descriptive name, such as: “Contoso BizTalk Management Pack”, which is the name we will use
for this example. The Management Pack creation wizard is fairly straight forward, and should only
require a name and version information.
The next item in our master plan is to figure out what exactly it is that we want to change. Any time we
make changes to existing management packs in SCOM we call those changes overrides. So, what is it
that SCOM uses to monitor what BizTalk is doing? How does SCOM figure out when BizTalk messages
are not flowing in or out of BizTalk? Fortunately for us, and our purposes, the artifact SCOM uses is
actually very simple. SCOM simply monitors the Windows Application event log on the BizTalk machines
looking for specific Event ID’s with specific sources, using SCOM event log rules, and fires up alerts when
the specified events occur. Figure 3 shows the Application event log entry for the messages suspended
earlier.
Page 5
Figure 3: Event Log for a particular suspended message
Of course, there are many different events BizTalk can issue, according to the nature of the problem in
question. The events generated for a transmission failure by an FTP adapter may be different than the
events generated in sending a SOAP message. Accordingly, SCOM has different rules for all the possible
occurrences of events. So where do we start looking? Well, as it turns out the SCOM alert actually tells
us all we need to know about the rule which is firing the alert, as shown by the second highlighted item
in Figure 1 above with the label of Alert Rule. The Alert Rule tells us exactly which SCOM rule has
triggered the alert, in this case it is an Alert Rule called “Core Alert: ERROR – An outbound message is
being suspended by the Adapter.”
Messaging alerts, as designed by the developers of the BizTalk Management Pack, all start with the
words “Core Alert,” and we can find them all in the SCOM admin console, by going to the Authoring
section (highlighted on the left pane in Figure 4 below,) expanding the Management Pack Objects node,
and clicking on Rules. Then on the right hand pane at the top, use the “Look for:” search box to filter all
the rules installed on the SCOM server with the key words “Core Alert”, as seen in Figure 4. You could
proactively override these alerts in order to prevent alert flooding, but since there are over fifty of
these, I would recommend only “tuning” the alerts you are experiencing.
Page 6
Figure 4: List of the 57 messaging related alert rules in the BizTalk Management Pack
Referring back to our master plan above, in step 2 we have to find the alert rule we are interested in
modifying. In this case, I highlighted our particular rule in Figure 4. Now we can right-click on the rule
and select properties, so that we can document (step 3 of the plan) the settings and behavior of the rule
in order to create a new rule with similar configuration. Note that we can also get to the rule’s
properties by clicking on the alert rule’s name I highlighted in Figure 1, and see the exact same
properties box.
Figure 5 shows the Configuration tab of the properties dialog box for the Core Alert rule we are
interested in. The Configuration tab is the only one we really care about since this is where all the
settings we’re looking to document are located. The Product Knowledge tab has a description of what
the alert does, but this knowledge is not that relevant.
First we’ll document the Data Sources properties, which we can do by clicking on the top-most “View…”
button, to see where our alert data comes from, as shown in Figure 6. The Log Name tab shows us that
the data comes from the Application event log, and the Expression tab shows us that the alert uses a
logical expression equivalent to (Event Level = Error) AND (Event ID =5754) AND (Event Source = BizTalk
Server 2006 OR Event Source = BizTalk Server 2009). Remember, these are the configuration settings of
the rule that is part of the BizTalk Management Pack. We are documenting them, so we can create a
custom rule of our own in our unsealed management pack. To document these settings, write them
down, or take screenshots of the properties box.
Next we need to document the properties for the SCOM alert that will be generated. We cancel out of
the Data Sources dialog box, and under the Responses sections, click on “GenerateAlert”, and then click
Page 7
the “View…” button to the right of this control. Document the configuration settings here, as shown in
Figure 7, including the Alert Name, Alert Priority, Alert Severity, and the Alert Description, in this case
$Data/EventDescription$.
Figure 5: Alert rule configuration properties
Page 8
Figure 6: Alert Rule Event log filter expression
Page 9
Figure 7: GenerateAlert configuration properties
Having documented these properties, we then need to check out the Alert Suppression settings. Alert
suppression is the mechanism we are looking to leverage so that instead of generating multiple alerts
(and thereby multiple e-mails or SMS messages), we generate just one when the alert is raised, and
increase the Repeat Count of the alert by one every time the event occurs. Figure 8 shows the Alert
Suppression Settings for the alert we are exploring here. As you can see, by default, the events are
configured to be grouped by Event ID, Event Source, and something called Parameter 1. There is also an
advanced suppression parameter, which you can review but which we won’t need.
Page 10
Figure 8: Alert Suppression configuration properties
After having documented the configuration settings for the alert rule, it is time to do away with the
rule. Again, since the rule is defined in a sealed management pack, we cannot remove it, but we can
override it. To override the alert, from the Authoring console view of Core Alerts, right click on the
“Core Alert: ERROR – An outbound message is being suspended by the Adapter” rule, select “Overrides“
and select Disable the Rule -> For all objects of type BizTalk Server. This will override the rule for all
BizTalk servers monitored by SCOM. If you only wish to override the rule for some servers, you can
target the override accordingly by placing different servers into SCOM groups and targeting the override
to just the groups you want.
Configure the Override properties as shown in Figure 9, making sure to select your custom management
pack (in our case the Contoso BizTalk Management Pack), checking the checkbox for “Enabled” and
selecting an “Override Value” of False, then click the Apply button. The override effectively disables this
rule on all BizTalk Servers, which is not a problem since we are going to create one from scratch. We will
have full control over the new rule.
Page 11
I should add a quick note on overrides. Overrides allow us to change some, but unfortunately not all, of
the configuration settings for a rule, monitor, task, or discovery in SCOM. They allow us to enable, or
disable rules and monitors, change the severity or priority of the alerts they generate, and in some cases
configure whether or not the alert can be automatically resolved once the issue is cleared up. The
properties we can override are limited, however, which is another reason we have to create our own
alert in this scenario.
Figure 9: Override Properties
With the standard rule alert out of the way, we have to create a rule we can configure, which is a simple
task. Under the Authoring section of the SCOM management console (highlighted in the left pane of
Page 12
Figure 4 above), right-click on “Rules” and select “Create a new rule…” to open the Create Rule Wizard.
Make sure to first and foremost select your custom management pack from the drop-down control at
the bottom, and then in the rule types tree expand Alert Generating Rules ->Event Based and select NT
Event Log (Alert). This will create an alert rule which monitors the Windows Event log, and triggers
alerts as necessary.
After clicking the “Next” button, the General tab of the Create Rule Wizard allows you to give your rule a
name and a description. I like to append the name of my company, or my own name, in front of the rule
name, so I can easily filter rules later in the SCOM console. Leave the Rule Category set to Custom, and
click the “Browse” button to target your rule. When you click the “Select” button you will see a listing of
all the object classes and groups in the SCOM health model as installed on the server. If you type
“BizTalk Server” in the “Look for:” text box, the dialog box will filter the targets and just show you the
relevant BizTalk target objects. Make sure you select the BizTalk Server object with a description of:
“This is the Server Role that indicates BizTalk Server is installed on a machine,” and click OK. Your Create
Rule Wizard General tab should look like the one in Figure 10, after which you can click the “Next”
button.
Page 13
Figure 10: Create Rule Wizard - General Tab
In the Event Log Type step of the wizard, make sure Application is selected, since we’re going to be
looking for events in the Windows Application event log and click “Next.” Here is where the fun begins.
In the Build Event Expression step of the wizard we’ll have to recreate the logical filter expression we
documented earlier (see Figure 6 above). Building the logical expression is pretty straight forward, using
a combination of AND’s, OR’s and Expressions. This process is very similar to the configuration of filter
expressions for BizTalk send ports, or the activation receive shapes of BizTalk orchestrations. When
selecting the Expression Event Properties, make sure to use the option for “Select from a list of common
event properties,” as this will allow you to filter by common Event log categories such as Event ID, Event
Source, Event Level, and Event Category (Figure 11).
Page 14
Figure 11: Event Properties selections to be used to build logical filter expressions
The final step in the wizard, Configure Alerts, allows us to customize the nature of the SCOM alert
triggered by the occurrence of the relevant events we just configured. Give the alert a name, or you can
leave the name it defaults to from the rule name. Configure the Alert Description, Priority and Severity
fields as you documented from the alert we disabled (see Figure 7). Once these parameters are set
correctly, click on the “Alert Suppression” button, so that we can configure the alert suppression
settings, and check the boxes for Event ID and Event Source (refer to the settings we documented
earlier, as shown in Figure 8).
By now you may be asking yourself what these fields listed in the Alert Suppression dialog box are, with
such descriptive names such as Parameter 1, Parameter 2, …, Parameter 25. These values allow you to
group events according to parameters in the Description field of the event log entry. Suppose that we
have multiple send ports, pointing to different URI’s and perhaps using different transports. Should a
messaging failure occur, and we only group alerts by Event ID and Event Source, then we’ll only receive
one alert for the messaging failures, when perhaps we want to keep track of the failures for each URI
separately. For example, if messaging to our internal web services fails, we do not want the alert for
that failure to be grouped together with an alert for a failure in communicating with an external
supplier.
How do we find out what is the corresponding value of Parameter 1, and Parameter 2 and so on? Why,
with a bit of trickery, of course!2 The first thing we need to do is install Log Parser 2.2 (available here:
http://www.microsoft.com/downloads/details.aspx?FamilyID=890cd06b-abf8-4c25-91b2-
2 Here I must give credit to one of my peers, Kevin Holman from the SCOM PFE team who has a great blog on
SCOM available here: http://blogs.technet.com/kevinholman/default.aspx
Page 15
f8d975cf8c07&displaylang=en) . We can then use LogParser, to parse one of the events we’re
interested in triggering an alert on (like the one shown in Figure 3), with a command such as:
Logparser.exe "SELECT top1 Strings AS Parameters FROM Application WHERE EventID=5754"
The output is shown in Figure 12 and since it is a bit messy-looking it requires some review. First of all,
Parameters are delimited by the pipe “|” symbol. So the first parameter in Figure 12 is the GUID
{B903D770-0F3C-4FF7-98D5-0B76BBF88C19} which is useless to us, the second Parameter is also a GUID
and is equally useless. The third Parameter is the transport, in this case WCF-BasicHTTP. The fourth
Parameter is the URI (http://www.contoso.com/TemperatureWebService/Convert.asmx), and the fifth
parameter is the port name (MySendPort1). So if we specify Parameter 4 as one of our Alert
Suppression fields, we’ll make sure to keep separate the alerts for each and every URI we communicate
with.
Figure 12: LogParser 2.2 output
I should note here, that every event is different, so you cannot assume that the URI field will be in the
same place for an Event ID 5753, just because of where it was located in Event ID 5754. They may be in
the same place, but that’s not guaranteed, so always run your event through LogParser to make sure.
As a result, the alert suppression settings for our example should look like the ones in Figure 13.
Page 16
Figure 13: Customized Alert Suppression settings
The final task in our action plan is to change the grouping settings in the alerts view of the SCOM
administration console. Depending on how you view your BizTalk alerts under the Monitoring section of
the SCOM administration console, you will want to add the Repeat Count column so that you see an
incremental count of alerts as they occur. The following steps apply to the Messaging Alerts View under
the BizTalk Server management pack folder, as well as for any custom views you create, but I will use the
default Active Alerts view.
To add the Repeat Count column, right-click on the Active Alerts view in the Monitoring section of the
SCOM administration console, and select “Personalize View.” Scroll all the way to the bottom of the list
of columns, and check the check-box for Repeat Count (second from the bottom in the control.) The
result is illustrated in Figure 14. Notice the highlighted Repeat Count column, and how after the original
alert occurred the next 127 messages which were suspended, bound for the same URI, all generated an
increase in the repeat count, instead of new alerts.
Page 17
From this point forward, any occurrences of the specific event alert we overrode will result in a new
alert for a first occurrence of the problem, followed by increments to the Repeat Count property for
subsequent occurrences. Therefore, it becomes paramount that when messaging resumes successfully,
the alerts in SCOM are closed out3; otherwise new occurrences of the same messaging problem will not
result in a new alert, or new e-mail or SMS messages.
Figure 14: Repeat Count column and final display output showing suppressed alerts
The BizTalk Management Pack for SCOM is a powerful partner for BizTalk administrators, to monitor
BizTalk Servers and applications. The rules and monitors in the management pack, out of the box,
represent a comprehensive strategy for managing a BizTalk environment, but sometimes they need to
be adjusted in order to better fit the needs, resources, and practical limitations of organizations and
administrators. Implementing the solution described here, should go a long way toward ensuring you
are properly alerted about BizTalk messaging problems, while still maintaining your sanity, not to
mention a healthy e-mail inbox.
3 The specific steps in the closing of SCOM alerts are outside the scope of this article.
Page 18
Connecting BizTalk Server to Websphere MQ (WMQ): Part 1 a look at IBM’s WCF transport channel for Websphere MQ Summary: This article presents the different options available to connect BizTalk Server to Websphere
MQ and explores in more detail the use of the new WCF transport channel for Websphere MQ that
ships with IBM Websphere MQ V7.0.1.
Author: Armando Fagundes, Senior Consultant at Avanade Inc., a business technology services company
that connects insight, innovation and expertise in Microsoft technologies to help customers realize
results. Responsibility for the contents and opinions expressed in this paper rests solely with the author.
Introduction
Websphere MQ (formerly known as MQSeries) is a very popular product and it is largely used in the
Enterprise as a message oriented middleware (MOM). As a result, it is a fairly common scenario in
BizTalk projects to have to integrate with Websphere MQ. BizTalk Server currently provides two
adapters to connect to Websphere MQ, the MQSeries server adapter (MQS) and the MQSeries client
adapter (MQSC). In addition, BizTalk 2006 R2 and BizTalk Server 2009 support other connectivity
options through the use of WCF custom bindings and WCF custom transport channels. Microsoft
provides a WCF Channel for Websphere MQ as part of BizTalk Adapters for Host Systems (BAHS) 2.0 and
IBM provides a Websphere MQ custom WCF channel with the new release of Websphere, version
V7.0.1.
In the next sections I will cover very briefly each one of the options and explore in more detail the use of
the new WCF transport channel for Websphere MQ that ships with IBM Websphere MQ V7.0.1.
BizTalk Server to Websphere Connectivity Options
BizTalk Server Based adapter for Websphere MQ (MQS)
The first version of the server based adapter was introduced right after the release of BizTalk server
2000. This adapter requires an instance of Websphere MQ to be deployed on a windows server to act as
an intermediary/bridge between the BizTalk servers in the group and any non-windows Websphere MQ
servers. The adapter has two main components: the BizTalk component that is installed in the BizTalk
Servers and manages all the BizTalk side communication; and the Websphere MQ component (aka
MQSAgent2) that communicates with Websphere MQ. The Websphere MQ component (MQSAgent2) is
a COM+ Application installed in the Windows Websphere MQ Server and communicates with
Websphere MQ locally through the Websphere MQ API.
Page 19
BizTalk Group
BizTalk Server #1
BizTalk Server #2
Windows Websphere
MQ Server
Non Windows Websphere
MQ Server
BizTalk WMQ
Server Adapter
(MQS)
BizTalk WMQ
Server Adapter
(MQS)M
QS
Ag
en
t2
(CO
M+
Ap
plic
atio
n) Websphere MQ
Queue Manager
Q1 Q2 Q3
Websphere MQ
Queue Manager
Q1 Q2 Q3
WM
Q
Ch
an
ne
l
BizTalk Client Based adapter for Websphere MQ (MQSC)
The client based adapter was introduced with the release of the BizTalk Adapters for Host Systems
(BAHS) 1.0 for BizTalk 2006 late 2006. The main difference between the client based adapter (MQSC)
and the server based adapter (MQS) is that the client based adapter uses IBM’s Websphere MQ client to
directly connect to any Websphere MQ Server, eliminating the need of the intermediary/bridge server
required in the server based adapter configuration. On the other hand, the client based adapter requires
IBM’s Websphere MQ Client to be installed on each BizTalk server in the group that needs to
communicate with the Websphere MQ servers.
BizTalk Group Websphere MQ
Server
Websphere MQ
Queue Manager
Q1 Q2 Q3WM
Q C
lien
t
Co
nn
ectio
n
BizTalk Server #1
BizTalk WMQ
Server Adapter
(MQS) WM
Q
Clie
nt
BizTalk Server #2
BizTalk WMQ
Server Adapter
(MQS) WM
Q
Clie
nt
The client based adapter offers two possible configurations depending on the type of IBM Websphere
MQ Client used, Base Client or the Extended Client. Both configurations provide guaranteed delivery but
only the configuration using the extended client supports once-and-only-once delivery of messages as
well as support for transactional scenarios.
The client based adapter (MQSC) does not replace the server adapter (MQS), it offers additional
connectivity options. Choosing between the different configurations will ultimately depend on the
specific requirements. Microsoft provides a good comparison of the server and the client based adapter
Page 20
as well as the two configuration options for the client adapter at http://msdn.microsoft.com/en-
us/library/aa772116(BTS.10).aspx.
WCF Transport Channels for Websphere MQ
In addition to the server based adapter (MQS) and the client based adapter (MQSC), it is also possible to
connect to Websphere MQ using WCF custom bindings with WCF custom transport channels for
Websphere MQ. Microsoft introduced a WCF Transport channel for Websphere MQ with the release of
version 2.0 of the BizTalk Adapters for Host Systems (BAHS 2.0). IBM has also included a WCF Transport
Channel for Websphere MQ with the release of version 7.0.1 of Websphere MQ at the end of last year.
The WCF Transport Channels can be used with BizTalk using the WCF-Custom Adapter and configuring a
custom binding. The WCF Transport Channel will rely on IBM’s Websphere MQ API, therefore requiring
the Websphere MQ client or the Websphere MQ server to be installed with WCF Transport.
BizTalk Group
Websphere MQ
Server
Websphere MQ
Queue Manager
Q1 Q2 Q3
WM
Q C
lien
t
Co
nn
ectio
n
BizTalk Server #1
BizTalk WCF
Adapter
WM
Q
Clie
nt
WCF Channel
Stack
Application
Protocol
Encoder
Transport
Protocol
...
BizTalk Server #2
BizTalk WCF
Adapter
WM
Q
Clie
nt
WCF Channel
Stack
Application
Protocol
Encoder
Transport
Protocol
...
.
Page 21
IBM Websphere MQ WCF transport channel
Components of the IBM Websphere MQ WCF custom channel
All the classes required to use the Websphere MQ WCF custom channel are included in the
IBM.XMS.WCF.dll assembly. This assembly is installed by default with Websphere MQ V7.0.1. After the
Websphere MQ V7.0.1installation is complete, the assembly will be available in the GAC (Global
Assembly Cache)
If you take a look into the assembly, for instance using ildasm or your favorite reflection tool, you will
find the following:
Page 22
As you can see, the custom channel implementation supports a request-reply pattern
(XmsRequestChannel and XmsReplyChannel) as well as a one-way pattern (XmsInputChannel and
XmsOutputChannel). If you are not familiar with the WCF Channel model, and you are interested, you
can catch up here http://msdn.microsoft.com/en-us/library/ms729840.aspx.
The main focus will be on the transport binding classes SoapJmsIbmTransportBindingElement,
SoapJmsIbmTransportBindingElementImporter and SoapJmsIbmTransportBindingElementConfig.
Address Format
Page 23
As with any WCF service you will need to define an endpoint/address to consume the service, the
Websphere MQ transport channel uses the following address format:
jms:/queue?name=value&name=value&name=value...
You can find a detailed explanation of each parameter in the Websphere MQ Help at:
http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzav.doc/un12
040_.htm
The most common parameters used are:
Name Required Description
Destination Yes destination = <queue name> OR <queue name>@<queue manager> This parameter identifies the destination queue. You can specify just the queue name or the queue name followed by the @ symbol and the queue manager name (ex: myQ@MyQMgr). This should be the first parameters following the jms:/queue.
connectionFactory Yes connectionFactory = <name>(value)<name>(value)… A connection factory for a WebSphere MQ provider includes the queue manager name and the information required to connect to that queue manager. To connect to a specific queue manager you can use the connectQueueManager parameter of the connectionFactory and specify the queue manager name as the value (ex: connectionFactory = connectQueueManager(MyQMgr)). Other parameters such as clientConnection or binding can be used to define the type of connection.
initialContextFactory Yes initialContext = com.ibm.mq.jms.Nojndi According the Websphere MQ Help, this parameter exists for compatibitity with Websphere Application Server and should always have the value com.ibm.mq.jms.Nojndi.
replyDestination No replyDestination = <queue name> This parameter identifies the reply queue in a request-reply interaction pattern. By default SYSTEM.SOAP.RESPONSE is used.
Below is an example for an address definition used in a request-reply interaction.
jms:/queue?destination=Delivery.Pickup.Request@DeliveryRUs&connectionFactor
y=connectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Noj
ndi&replyDestination=Delivery.Pickup.Reply
The address defines that messages are expected in the Delivery.Pickup.Request queue within the
DeliveryRUs queue manager and that the reply to the request is expected in the Delivery.Pickup.Reply
queue.
Using the IBM Websphere MQ Transport Channel with BizTalk Server
Page 24
In this section we will look at how to configure the Websphere MQ WCF Transport Channel to be used
with BizTalk server (2006 R2 or 2009). We will use a sample scenario and demonstrate how to send and
receive messages through Websphere MQ using the WCF Transport Channel with BizTalk Server.
Since BizTalk 2006 R2, BizTalk supports WCF through the WCF Adapters. To make the custom channel
available to BizTalk the binding element extension needs to be added to the machine.config. For more
details on how to enable WCF extensibility points with the WCF Adapters take a look at How to enable
WCF extensibility points with the WCF Adapters (http://msdn.microsoft.com/en-
us/library/bb743310(BTS.20).aspx).
Enable Websphere MQ WCF Transport Channel with the WCF Adapters
1. The first step is to make sure all assemblies implementing the extension are registered in the GAC. In this case, all assemblies that are part of the Websphere MQ WCF Transport Channel are registered in the GAC as part of the installation of Websphere MQ. At least the assemblies below should be registered in the GAC:
IBM.XMS
IBM.XMS.Util
IBM.XMS.Client.Impl
IBM.XMS.WCF
IBM.XMS.WCF.NLS
amqmdnet 2. The second step is to configure the extension in the machine.config file so that the extension is
available when configuring the ports. Open the machine.config (C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG), locate the system.serviceModel node within the machine.config and under the extensions\bindingElementExtensions node you need to add the line below :
<add name="IbmWmqTransportChannel"
type="IBM.XMS.WCF.SoapJmsIbmTransportBindingElementConfig, IBM.XMS.WCF,
Version=7.0.1.0, Culture=neutral, PublicKeyToken=8c7c0be90afcd8ba"/>
For the changes to take effect in BizTalk you will need to restart the host instances running the WCF
Adapter. Now that the extension has been configured the next step is to configure a receive location or
send port using the WCF-Custom adapter.
Configure a Receiveport to receive messages using the MQ WCF Transport Channel with the
WCF Adapters
Request-Response Receive Port/Receive Location
1. Create a request-response receiveport. Create a new receive location for the port, and choose the WCF-Custom adapter.
Page 25
2. Click Configure. From the General Tab write the address below:
jms:/queue?destination=Delivery.Pickup.Request@DeliveryRUs&connectionFactor
y=connectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Noj
ndi&replyDestination=Delivery.Pickup.Reply
This address defines that messages are expected in the Delivery.Pickup.Request queue within the
DeliveryRUs queue manager and that the reply to the request is expected in the Delivery.Pickup.Reply
queue.
Page 26
3. Click the Binding tab. From the Binding tab, select customBinding for the Binding Type.
Page 27
4. Remove the httpTransport. Right click the CustomBindingElement and select Add Extension. From the Add Extension window select the IbmWmqTransportChannel from the list of available extensions (this is the same name used when configuring the extension in machine.config).
Page 28
One-way Receive Port/Receive Location
1. Create a one-way receive port. Create a new receive location for the one-way port, and choose the WCF-Custom adapter.
2. Follow all the same steps as for the Request-Response receive location with one exception, when defining the endpoint address do not specify the replyDestination parameter. For example:
jms:/queue?destination=Tracking.Track.In@DeliveryRUs&connectionFactory=conn
ectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Nojndi
This address defines that messages are expected in the Tracking.Track.In queue within the
DeliveryRUs queue manager and that there is no response expected as a result (no replyDestination
parameter).
Configure a Send port to send messages using the MQ WCF Transport Channel with the WCF
Adapters
Page 29
The configuration of send ports using the WCF-Custom adapter is very similar to configuring receive
locations.
Solicit-Response Send port
1. Create a solicit-response send port; choose the WCF-Custom adapter.
2. Click Configure. From the General Tab write the address below(same address used when configuring the request-response receive location):
jms:/queue?destination=Delivery.Pickup.Request@DeliveryRUs&connectionFactor
y=connectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Noj
ndi&replyDestination=Delivery.Pickup.Reply
Fill in the SOAP Action header, in this case:
http://armandofagundes.com/deliveryrus/2009/11/DeliveryService/RequestPicku
p
Page 30
3. Click the Binding tab. From the Binding tab, select customBinding for the Binding Type.
Page 31
4. Remove the httpTransport. Right click the CustomBindingElement and select Add Extension. From the Add Extension window select the IbmWmqTransportChannel from the list of available extensions (this is the same name used when configuring the extension in machine.config).
Page 32
One-way Send Port
1. Create a one-way send port and choose the WCF-Custom adapter. 2. Follow all the same steps as for the Solicit-Response send port. When defining the endpoint address
do not specify the replyDestination parameter. For example:
jms:/queue?destination=Tracking.Track.In@DeliveryRUs&connectionFactory=conn
ectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Nojndi
Fill in the SOAP Action header, in this case:
http://armandofagundes.com/deliveryrus/2009/11/DeliveryTrackingService/Trac
kDelivery
Page 33
3. For the remaining steps, follow all the same steps as for the Solicit-Response send port.
When trying to test the one-way send port as configured, surprisingly, it will cause a transmission failure
with an error similar to the one below:
Page 34
Event Type: Error
Event Source: BizTalk Server 2009
Event Category: (1)
Event ID: 5754
Date: 3/8/2010
Time: 9:35:05 AM
User: N/A
Computer: WIN-O49J8EQLJRK
Description:
A message sent to adapter "WCF-Custom" on send port
"DeliveryRUs.spDeliveryTrackingWmq" with URI
"jms:/queue?destination=Tracking.Track.In@DeliveryRUs&connectionFactory=con
nectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Nojndi"
is suspended.
Error details: System.ServiceModel.EndpointNotFoundException: WCFCH0309E:
An error occurred while attempting to open the channel for endpoint
'jms:/queue?destination=Tracking.Track.In@DeliveryRUs&connectionFactory=con
nectQueueManager(DeliveryRUs)&initialContextFactory=com.ibm.mq.jms.Nojndi'
The operation could not be completed. The endpoint may be down,
unavailable, or unreachable, review the linked exception for further
details. ---> IBM.XMS.IllegalStateException: Failed to open MQ queue
SYSTEM.SOAP.RESPONSE.QUEUE. XMS attempted to perform an MQOPEN, but
WebSphere MQ reported an error. Use the linked exception to determine the
cause of this error. Check that the specified queue and queue manager are
defined correctly.
at IBM.XMS.Client.WMQ.WmqMessageConsumer.CheckNmqiCallSuccess(String
messageid, String insert, String insertKey, Int32 completionCode, Int32
reason, NmqiEnvironment environment, String probeid, WmqCommonConnection
commonConnection, Hconn hconn)
at IBM.XMS.Client.WMQ.WmqConsumerShadow.Initialize()
at IBM.XMS.Client.WMQ.WmqSyncConsumerShadow.Initialize()
at IBM.XMS.Client.WMQ.WmqMessageConsumer..ctor(WmqDestination
destination, WmqSession session, String selector, Boolean nolocal,
XmsPropertyContext xmsProps)
at IBM.XMS.Client.WMQ.WmqSession.CreateConsumer(ProviderDestination
destination, String selector, Boolean nolocal, XmsPropertyContext
propertyContext)
at IBM.XMS.Client.Impl.XmsSessionImpl.CreateConsumer(IDestination dest,
String selector, Boolean noLocal)
at IBM.XMS.Client.Impl.XmsSessionImpl.CreateConsumer(IDestination dest,
String selector)
at IBM.XMS.WCF.XmsRequestChannel.<OnBeginOpen>b__0(AsyncTimedResult ar,
Object param)
Linked Exception : CompCode: 2, Reason: 2085
--- End of inner exception stack trace ---
Server stack trace:
at IBM.XMS.WCF.XmsChannelHelper.ThrowCommsException(OperationType op,
Exception innerException, String endpointURI)
at IBM.XMS.WCF.XmsChannelHelper.CheckExceptionAndTimeout(OperationType
op, Exception e, String timeout, String endpointURI)
at IBM.XMS.WCF.XmsRequestChannel.OnEndOpen(IAsyncResult result)
at IBM.XMS.WCF.XmsRequestChannel.OnOpen(TimeSpan timeout)
at System.ServiceModel.Channels.CommunicationObject.Open(TimeSpan
timeout)
at System.ServiceModel.Channels.ServiceChannel.OnOpen(TimeSpan timeout)
Page 35
at System.ServiceModel.Channels.CommunicationObject.Open(TimeSpan
timeout)
at System.ServiceModel.Channels.CommunicationObject.Open()
Exception rethrown at [0]:
at
System.Runtime.Remoting.Proxies.RealProxy.HandleReturnMessage(IMessage
reqMsg, IMessage retMsg)
at System.Runtime.Remoting.Proxies.RealProxy.PrivateInvoke(MessageData&
msgData, Int32 type)
at System.ServiceModel.ICommunicationObject.Open()
at
Microsoft.BizTalk.Adapter.Wcf.Runtime.WcfClient`2.GetChannel[TChannel](IBas
eMessage bizTalkMessage, ChannelFactory`1& cachedFactory)
at
Microsoft.BizTalk.Adapter.Wcf.Runtime.WcfClient`2.SendMessage(IBaseMessage
bizTalkMessage)
MessageId: {A76B8891-A1CF-43DD-9E2D-D6F8D485070C}
InstanceID: {46DBF173-8393-4920-B31E-A3E3EAB3223C}
For more information, see Help and Support Center at
http://go.microsoft.com/fwlink/events.asp.
Looking at the error details, with especial attention to the highlighted sections, the adapter is trying to
access the SYSTEM.SOAP.RESPONSE.QUEUE that does not exist within the Queue Manager (result
code 2085 – MQRC_UNKNOWN_OBJECT_NAME). The SYSTEM.SOAP.RESPONSE.QUEUE queue is the
system queue used by default in the absence of a queue name defined in the endpoint address using the
replyDestination parameter. For the one-way operation to succeed, the
SYSTEM.SOAP.RESPONSE.QUEUE system queue needs to be created for the specific queue manager.
This can be accomplished by running the following commands for the queue manager:
define qlocal(SYSTEM.SOAP.RESPONSE.QUEUE) BOTHRESH(3)
define qmodel(SYSTEM.SOAP.MODEL.RESPONSE.QUEUE) BOTHRESH(3)
DEFTYPE(PERMDYN) DEFSOPT(SHARED) SHARE
define qlocal(SYSTEM.SOAP.SIDE.QUEUE)
You can find more information about the use of the default system queues at
http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzau.doc/csqz
au0034.htm.
Running a sample
Let’s consider a sample scenario for a fictitious shipping company, using the WCF contracts listed below.
Service Contracts
Page 36
Request-Reply
The Request-Reply Service Contract defines a single operation that allows the customer to request a
package pickup for delivery.
[ServiceContract(Namespace="http://armandofagundes.com/deliveryrus/2009/11"
, Name="DeliveryService")]
public interface IDeliveryService
{
[OperationContract()]
Delivery RequestPickup(Delivery delivery);
}
One-way
The One-way Service Contract defines a single operation that allows the delivery agents to update the
tracking information.
[ServiceContract(Namespace =
"http://armandofagundes.com/deliveryrus/2009/11",
Name = "DeliveryTrackingService")]
public interface IDeliveryTrackingService
{
[OperationContract()]
void TrackDelivery(string trackingID, TrackingPoint trackingPoint);
}
Note that the operation is not marked with IsOneWay=True, the reason for this is that the WCF send
adapter operates by design following a request-reply pattern even when configured as one-way in the
send port, more on this here http://msdn.microsoft.com/en-us/library/bb967002(BTS.10).aspx).
Data Contract
Page 37
public class Delivery
{
private string trackingID;
public string TrackingID
{
get { return trackingID; }
set { trackingID = value; }
}
private Package package;
public Package Package
{
get { return package; }
set { package = value; }
}
private DateTime pickupDate;
public DateTime PickupDate
{
get { return pickupDate; }
set { pickupDate = value; }
}
private Location pickupLocation;
public Location PickupLocation
{
get { return pickupLocation; }
set { pickupLocation = value; }
}
private Location dropoffLocation;
public Location DropoffLocation
{
get { return dropoffLocation; }
set { dropoffLocation = value; }
}
private DateTime dropoffDate;
public DateTime DropoffDate
{
get { return dropoffDate; }
set { dropoffDate = value; }
}
public class Package
{
private string description;
public string Description
{
get { return description; }
set { description = value; }
}
private decimal weight;
Page 38
public decimal Weight
{
get { return weight; }
set { weight = value; }
}
private decimal width;
public decimal Width
{
get { return width; }
set { width = value; }
}
private decimal height;
public decimal Height
{
get { return height; }
set { height = value; }
}
private decimal lenght;
public decimal Lenght
{
get { return lenght; }
set { lenght = value; }
}
}
public class Location
{
private string address;
public string Address
{
get { return address; }
set { address = value; }
}
private string city;
public string City
{
get { return city; }
set { city = value; }
}
private string state;
public string State
{
get { return state; }
set { state = value; }
}
private string zipcode;
public string Zipcode
{
get { return zipcode; }
Page 39
set { zipcode = value; }
}
private string country;
public string Country
{
get { return country; }
set { country = value; }
}
private decimal xcoordinate;
public decimal XCoordinate
{
get { return xcoordinate; }
set { xcoordinate = value; }
}
private decimal ycoordinate;
public decimal YCoordinate
{
get { return ycoordinate; }
set { ycoordinate = value; }
}
}
Server
Request-reply service
The request-reply service is implemented as a BizTalk orchestration. The orchestration just receives the
request from a client executes a mapping that builds the response and sends the response back to the
client.
Page 40
The mapping assigns a drop-off date (two days from the request date) and a tracking ID.
One-way
The one-way service is implemented as a console application. It will simply write the contents
of each request to the console.
using System;
using System.ServiceModel;
namespace DeliveryRUsServiceHost
{
class Program
{
static void Main(string[] args)
{
System.ServiceModel.ServiceHost trackingHost = new
ServiceHost(typeof(DeliveryRUsService.DeliveryTrackingService));
try
{
trackingHost.Open();
Console.WriteLine("Host running...");
Console.WriteLine("Press [Enter] to stop the host");
Console.ReadLine();
}
finally
{
if (trackingHost.State != CommunicationState.Closed)
{
trackingHost.Close();
}
}
}
}
}
Page 41
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace DeliveryRUsService
{
public class DeliveryTrackingService: IDeliveryTrackingService
{
public void TrackDelivery(string trackingID, TrackingPoint
trackingPoint)
{
Console.WriteLine("[{0}] Updated tracking information
received", DateTime.Now);
Console.WriteLine("Tracking ID:{0}", trackingID);
Console.WriteLine("New Location: {0}, {1}, {2} {3}",
trackingPoint.Location.Address,
trackingPoint.Location.City,
trackingPoint.Location.State,
trackingPoint.Location.Zipcode);
}
}
}
Client
Request-reply client
A simple console application is used to send request-reply messages to the service hosted in BizTalk
Server.
Page 42
using System;
using System.ServiceModel;
using DeliveryRUsClient.DeliveryService;
namespace DeliveryRUsClient
{
class Program
{
static void Main(string[] args)
{
Console.WriteLine("DELIVERY CLIENT - Press [ENTER] when the
service is started...");
Console.ReadLine();
try
{
DeliveryServiceClient service = new
DeliveryServiceClient("DeliveryRUs_WmqEndpoint");
// Create a delivery request
Delivery delivery = new Delivery();
delivery.PickupDate = DateTime.Now;
delivery.Package = new Package();
delivery.Package.Description = "HDMI 5 way switch";
delivery.Package.Height = 2;
delivery.Package.Width = 5;
delivery.Package.Lenght = 8;
delivery.PickupLocation = new Location();
delivery.PickupLocation.Address = "West 13th St.";
delivery.PickupLocation.City = "New York";
delivery.PickupLocation.State = "NY";
delivery.PickupLocation.Zipcode = "10014";
delivery.DropoffLocation = new Location();
delivery.DropoffLocation.Address = "Adams St.";
delivery.DropoffLocation.City = "Brooklyn";
delivery.DropoffLocation.State = "NY";
delivery.DropoffLocation.Zipcode = "11201";
delivery = service.RequestPickup(delivery);
Console.WriteLine("Delivery expected date:{0}",
delivery.DropoffDate);
Console.WriteLine("Your tracking ID is:{0}",
delivery.TrackingID);
service.Close();
}catch(Exception ex)
{
Console.WriteLine(ex.ToString());
}
Console.WriteLine("Press [ENTER] to exit...");
Console.ReadLine();
}
}
}
Page 43
One-way client
A BizTalk Server send port is used to send one-way messages to the one-way service hosted in the
console application.
Output
Request-reply
One-way
Page 44
What’s next?
On the next issue I plan to explore in more detail the use of the WCF Custom Transport Channel for
Websphere included in the BizTalk Adapters for Host Systems 2.0 (BAHS2.0). For now just a few pointers
to get you started.
Binding Extensions
The first step is to configure the extensions. To configure the binding element extension for the
transport you can add the following line to the machine.config
(C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG) under
system.serviceModel\extensions\bindingElementExtensions:
<add name="MSWmqTransportChannel"
type="System.ServiceModel.Channels.WebSphereMQ.WebSphereMQTransportElement,
System.ServiceModel.Channels.WebSphereMQ.Channel, Version=7.0.2300.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
The WCF Custom Transport Channel for Websphere included in BAHS2.0 also includes preset bindings
you can use by configuring the binding extensions. For these you can add the following lines to the
machine.config under system.serviceModel\extensions\bindingExtensions:
Page 45
<add name="msWmqBinding"
type="System.ServiceModel.Channels.WebSphereMQ.WebSphereMQBindingCollection
Element, System.ServiceModel.Channels.WebSphereMQ.Channel,
Version=7.0.2300.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
<add name="msWmqBinaryBinding"
type="System.ServiceModel.Channels.WebSphereMQ.WebSphereMQBinaryBindingColl
ectionElement, System.ServiceModel.Channels.WebSphereMQ.Channel,
Version=7.0.2300.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
<add name="msWmqRequestBinaryBinding"
type="System.ServiceModel.Channels.WebSphereMQ.WebSphereMQRequestBinaryBind
ingCollectionElement, System.ServiceModel.Channels.WebSphereMQ.Channel,
Version=7.0.2300.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
Address Format
net.mqs://<queue manager>/<queue>
Binding Configuration
The WCF Custom Transport Channel for Websphere included in BAHS2.0 exposes many properties in the
binding configuration. At a minimum the following should be configured:
Name Description
connectionType Type of connection. Possible values BaseClient, ExtendedClient or Server.
mqcdChannelName The name for the WMQ server channel (SYSTEM.DEF.SVRCONN or other).
mqcdConnectionName <server>(<listener port>), ex: localhost(1414).
mqcdTransportType Type of transport. Possible values TCP, LU62
Summary
From its earliest releases, BizTalk server has always supported connectivity to Websphere MQ. This
support was increased with the release of the BizTalk Adapters for Host Systems (BAHS) that introduced
a client based adapter for Websphere MQ with version 1.0. The WCF adapters in BizTalk Server 2006 R2
and BizTalk Server 2009 open the doors to the use of custom WCF transports that can be developed and
provided by the different vendors as part of their product releases and can easily be integrated with
BizTalk Server through the use of the WCF-Custom adapter and custom binding configurations.
Microsoft provides a WCF Channel for Websphere MQ as part of BizTalk Adapters for Host Systems
(BAHS) 2.0 and IBM provides a Websphere MQ custom WCF channel with the new release of
Websphere, version V7.0.1. Throughout this article we explored in more detail the use of the IBM
Websphere MQ custom WCF channel included with the new release of Websphere, version V7.0.1. We
looked at how to configure the custom transport channel and use it in BizTalk server to receive and send
messages through Websphere MQ.
Page 46
So now in addition to the BizTalk Websphere MQ server based adapter (MQS) and the BizTalk
Websphere MQ client based adapter (MQSC) there are other connectivity options with WCF custom
transport channels and WCF-Custom adapter.
Additional Resources/References
How to enable WCF extensibility points with the WCF Adapters http://msdn.microsoft.com/en-us/library/bb743310(BTS.20).aspx
Using the Windows Communication Foundation (WCF) Adapters in BizTalk Server
http://msdn.microsoft.com/en-us/library/bb967002(BTS.10).aspx
Introduction to BizTalk Adapters for Host Systems
http://technet.microsoft.com/en-us/library/bb726925(BTS.10).aspx
WCF Channel Model Overview
http://msdn.microsoft.com/en-us/library/ms729840.aspx
Websphere MQ V7.0.1 Trial download
http://wsww14.software.ibm.com/webapp/download/preconfig.jsp?id=2009-08-
28+03%3A34%3A46.648052R&S_TACT=104CBW71&S_CMP=
Websphere MQ custom WCF channel - Help
http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzav.d
oc/un12040_.htm
WebSphere MQ custom channel for WCF endpoint URI address format http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzav.doc/un120
40_.htm
Websphere MQ Handling messages greater than 4 MB long
http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzal.doc/fg1267
0_.htm
Availability of HIS 2009 and BAHS 2.0
http://connectbeta.microsoft.com/site66/content/content.aspx?ContentID=12212
Microsoft BizTalk Adapters for Host System 2.0 Evaluation (BAHS2.0)
http://www.microsoft.com/downloads/details.aspx?FamilyID=1e545278-0d5b-4bbd-b073-
18111ce86995&displaylang=en
Acknowledgements
Many thanks to Bryan Corazza for his support and valuable feedback.
Page 47
Using a WCF Runtime Proxy to consume Services Terry J. Thompson, Systems Architect/Senior Software Engineer,TeleVox Softwarewww.televox.com [email protected]
Problem
If you have worked with Web Services or WCF Services for any amount of time you know that it can be
difficult to keep WCF/ASMX client proxies up to date and if you have a large number of services the
sheer number of proxy classes becomes hard to manage.
The following is an attempt to ease the deployment and maintenance of our Services Farm and to
enable endpoint discovery using Microsoft UDDI 3.0 Services so that we aren’t bound to static hard
coded web.config and/or app.config files for service binding information.
There is nothing more painful than having to update multiple client proxies if a service’s interface
changes or to have to modify each process’s configuration files if you need to change the Uri for a
service.
Overview
The following diagram depicts the process sequence for utilizing the Microsoft.UDDI.dll to retrieve the
URI from Microsoft’s UDDI 3.0 Services repository for a simple WCF Service. The returned Uri and other
configuration data is then passed to the GenericServiceGateWay class which builds a runtime proxy that
allows the methods on the WCF to be utilized by the client application.
Page 48
Solution
This is a simple solution that addresses our current needs. I can definitely see this expanding over time
and becoming a richer solution that can handle more intricate configuration and security needs. I hope
that this first step can provide value to you and I would be happy to hear suggestions on improving what
we currently have.
Visual Studio 2008 Solution Setup
The following is a screenshot of the Solution setup. Notice that references are highlighted in red.
Page 49
Page 50
Prerequisite Setup
UDDI Setup
Microsoft UDDI Services 3.0 will need to be installed on a server in your environment to run the
application documented in this article.
Here is a summary of Microsoft UDDI Services 3.0 features copied from MSDN’s description.
http://msdn.microsoft.com/en-us/biztalk/dd789428.aspx
Microsoft UDDI Services 3.0 (Universal Description, Discovery, and Integration Services) ships
with Microsoft BizTalk Server 2009, and conforms to the UDDI version 3.0 specification. UDDI
Services 3.0 provides the following key capabilities:
A Web service that supports UDDI version 3.0 standards-compliant interfaces for service
discovery.
Rich role-based Web UI interfaces for service searching, publishing, subscribing, and site
coordination.
Notifications of service changes.
Custom categorization schemes for describing service providers and their Web services
in your organization.
SDK and developer tools to facilitate the development of UDDI-integrated applications.
A rich set of administration tools to ease the management of UDDI Services.
Some of the key benefits of UDDI Services are:
Page 51
It provides a scalable solution for organizing, discovering, reusing, and managing Web
services.
It promotes service reuse.
It facilitates loosely-coupled service hosting environments by enabling run-time
selection of, and binding to, a service endpoint.
It provides interoperability with other UDDI standards-compliant tools.
Microsoft UDDI Services 3.0 included with Microsoft® BizTalk® Server 2009. The installation instructions
and system requirements can be found at the following URL:
http://www.microsoft.com/downloads/details.aspx?displaylang=en&familyid=9d1831cc-8146-486b-
b489-a06a1aa2fb5b
For some great information on how to set up a WCF Service in Microsoft UDDI Services and a good UDDI
overview read Richard Seroter’s article at the following URL:
http://www.packtpub.com/article/soa-capabilities-in-biztalk-uddi
Here is a screenshot of the PrototypeService set up on a UDDI server. Note that the binding information
contains the Uri to connect to the WCF Service. Whatever you enter here is returned if you call the
GetServiceEndPointAddress method in the UDDIHelper class.
Client Application
I have created a simple Windows Forms client to utilize the GenericServiceGateWay class from the
TJT.Prototypes.ServiceGateWays project to retrieve a runtime proxy to a simple WCF Service.
Below is the client code to consume the GenericServiceGateWay:
Page 52
private void button1_Click(object sender, EventArgs e) { string service = string.Empty; string endPointUri = string.Empty; GenericServiceGateWay gateWay = null; IPrototypeService prototypeService = null; string retVal = string.Empty; try { //Service Name as it was entered in UDDI service = "PrototypeService"; //Custom UDDI Helper class wrapping functionality offered by the Microsoft.UDDI.dll UDDIHelper uddiHelper = new UDDIHelper(); //Call the UDDI Helper to get the endpoint uri for the specified service endPointUri = uddiHelper.GetServiceEndPointAddress(service); //Instantiate the runtime proxy gateWay = new GenericServiceGateWay(); //get the proxy instance. Note: IPrototypeService is the WCF Contract for the PrototypeService prototypeService = gateWay.GetGenericFactoryChannel<IPrototypeService>(endPointUri, WCFTransportTypeEnum.TransportType.BasicHttpBinding.ToString()); // call a method on the service retVal = prototypeService.GetData(10); MessageBox.Show(retVal); } catch (Exception ex) { MessageBox.Show (ex.Message ); } finally { // Be sure to clean up!! if (gateWay != null && prototypeService != null) { gateWay.Dispose((IClientChannel)prototypeService); gateWay = null; prototypeService = null; } }
.Net Components
The following section describes the components included in each project in the solution and includes
the code.
TJT.Prototypes.Enums Project
WCFTransportTypeEnum.cs
This is just a simple enum class to help with setting the right string for the case statement in
GenericServiceGateWay.cs.
Page 53
namespace TJT.Prototypes.Enums { public class WCFTransportTypeEnum { public enum TransportType
{ BasicHttpBinding, WSHttpBinding, WSDualHttpBinding, WSFederationBinding, NetTCPBinding, NetNamedPipeBinding, NetMsmqBinding, MsmqIntegrationBinding, WebHttpBinding
}; } }
TJT.Prototypes.ServiceContracts Project
IPrototypeService.cs
This is the service contract interface for the ProtoTypeService WCF Service.
using System.ServiceModel; namespace TJT.Prototypes.ServiceContracts { [System.ServiceModel.ServiceContractAttribute(Namespace = "http://www.tjt.com/ProtoTypes/ServiceContracts/2010/01/")] public interface IPrototypeService { [OperationContract()] string GetData(int value); } }
TJT.Prototypes.ServiceGateWays Project
GenericServiceGateWay.cs
This class is one of the primary focuses of this article. The GetGenericFactoryChannel method returns a
runtime proxy that can be used to bind to and execute methods on a WCF Service. The Dispose method
is used for cleanup and should be called any time you are finished working with a service.
using System.ServiceModel; using System; using System.ServiceModel.Channels; using System.Xml; namespace TJT.Prototypes.ServiceGateWays { /// <summary> /// A Generic Gateway library used to bypass the need for local app.config files to configure WCF Services. /// </summary> public class GenericServiceGateWay { public GenericServiceGateWay() { }
Page 54
/// <summary> /// Generic WCF Service Gateway using the WCF Channel Factory. NOTE: You have to dispose of instances returned by calling the Dispose() method in your client code!!. /// </summary> /// <typeparam name="T">Pass the Interface (Service Contract) for the Service. Example: ILoggingService</typeparam> /// <param name="EndPointUri">Endpoint URI to the WCF Service that you want to use</param> /// <param name="WCFTransportType">See TJT.Core.Enums -- its the WCF Transport type</param> /// <returns></returns> public T GetGenericFactoryChannel<T>(string EndPointUri, string WCFTransportType) { EndpointAddress address = new EndpointAddress(EndPointUri); //generic type T proxy = default(T); object binding = null; switch (WCFTransportType) { case "BasicHttpBinding": // Create a basic http binding binding = new BasicHttpBinding() { // NOTE: need to do a better job of handling binding configuration. Hard Coded is not the way to go ReaderQuotas = { MaxArrayLength = 400 * 8192, MaxStringContentLength = 400 * 8192 }, MaxReceivedMessageSize = 400 * 8192, MaxBufferSize = 400 * 8192 }; break; case "WSHttpBinding": binding = new WSHttpBinding(); break; case "NetTCPBinding": binding = new NetTcpBinding(); break; default: binding = new BasicHttpBinding(); break; } // Hook into the WCF ChannelFactory object ChannelFactory<T> channelFactory = new ChannelFactory<T>((Binding)binding, address); channelFactory.Endpoint.Address = address; //Create the channel proxy = channelFactory.CreateChannel(); return proxy; } /// <summary> /// Don’t forget to call this guy and cleanup!!
Page 55
/// </summary> /// <param name="service"></param> public void Dispose(IClientChannel service) { try { if (service != null) { if (service.State != CommunicationState.Faulted) { service.Close(); } else { service.Abort(); } } } catch (CommunicationException) { service.Abort(); } catch (TimeoutException) { service.Abort(); } catch (Exception) { service.Abort(); throw; } finally { service = null; } } } }
TJT.Prototypes.UDDI Project
UDDIHelper.cs
This class encapsulates communications with Microsoft UDDI 3.0 Services. See the section about UDDI configuration on how to set up the PrototypeService WCF Service so that you can retrieve its Uri. This class depends on a reference to the Microsoft.UDDI.dll that installs with Microsoft UDDI Services 3.0. This file can be located at %PROGRAMFILES%\Microsoft UDDI Services\SDK. using System; using System.Collections.Generic; using Microsoft.Uddi3; using Microsoft.Uddi3.Services; namespace TJT.Prototypes.UDDI { /// <summary>
Page 56
/// A Wrapper for the Microsoft.UDDI3 class library to allow interaction with the UDDI Servers /// </summary> /// <Author>Terry J. Thompson</Author> public class UDDIHelper { #region Properties string _UDDIServiceURL = string.Empty; /// <summary> /// URL for the Inquiry.asmx - used to return the path for a WCF or Web Service /// </summary> /// public string UddiURL { get { return _UDDIServiceURL; } } #endregion #region Constructors /// <summary> /// Default Constructor - Reads the config file to populate the path for the Inquiry.asxm file in UDDI 3.0 /// </summary> public UDDIHelper() { // NOTE: In our production code this information is pulled from a configuration file, not hard coded ":) _UDDIServiceURL = "http://YourServer/uddi/inquire.asmx"; } #endregion #region Public Methods /// <summary> /// Returns a Dictionary object with the configuration settings for the specified service registered in UDDI /// </summary> /// <param name="ServiceName"></param> /// <returns>Dictionary Object</returns> public Dictionary<string, string> GetServiceConfigurationDictionary(string ServiceName) { //Create a dictionary object to hold the config key, value pairs Dictionary<string, string> UDDIConfig = new Dictionary<string, string>(); try { if (_UDDIServiceURL == "") { throw new ApplicationException("The URL For the UDDI Server was not supplied."); } if (ServiceName == "") { throw new ApplicationException("The Service to retreive configuration for was not supplied."); } //Connect to UDDI Server UddiConnection conn = new UddiConnection(_UDDIServiceURL); //Query for Service Information FindService serviceQuery = new FindService(ServiceName); ServiceList queryResult = serviceQuery.Send(conn);
Page 57
//Get the Unique key assigned in UDDI for this service string key = queryResult.ServiceInfos[0].ServiceKey; //Since the returned key is the lookup for everything else, throw an exception if not found if (key == "") { throw new ApplicationException("Configuration Information could not be found for the service " + ServiceName + "
in the UDDI Repository."); } //Add the unique id for the service UDDIConfig.Add("ServiceKey", key); //Get the Service Details GetServiceDetail getDetails = new GetServiceDetail(key); ServiceDetail details = getDetails.Send(conn); //Get the Business Service Details, in particular the Endpoint Uri for the service BusinessService busservice = details.BusinessServices[0]; string endPoint = busservice.BindingTemplates[0].AccessPoint.Text; //If the Endpoint is not returned the service was not configured correctly in UDDI if (endPoint == "") { throw new ApplicationException("The EndPoint Uri be found for the service " + ServiceName + " in the UDDI Repository, please check the service configuration in UDDI."); } // Build the config dictionary //Add the address to the service (endpoint) UDDIConfig.Add("EndPointUri", endPoint); // Get Service Custom Categories (TModels) KeyedReferenceCollection categories = busservice.BindingTemplates[0].CategoryBag.KeyedReferences; foreach (KeyedReference catKey in categories) { UDDIConfig.Add(catKey.KeyName, catKey.KeyValue); } return UDDIConfig; } catch (Exception ex) { throw ex; } } /// <summary> /// Helper method to get right to the Uri without dealing with a dictionary /// </summary> /// <param name="ServiceName"></param> /// <returns></returns> public string GetServiceEndPointAddress(string ServiceName) { string endPointAddress = string.Empty; Dictionary<string, string> uddiConfig = null;
Page 58
try { //Get Service Configuration uddiConfig = this.GetServiceConfigurationDictionary(ServiceName); //Pull config values if (uddiConfig.ContainsKey("EndPointUri")) // True { endPointAddress = uddiConfig["EndPointUri"]; } } catch (Exception e) { throw e; } return endPointAddress; } #endregion } }
WCF Service
PrototypeService Project
This is a simple WCF service to test the functionality of the GenericServiceGateWay class. This service
returns a string with the value that you passed to it appended to the end.
using TJT.Prototypes.ServiceContracts; namespace TJT.Prototypes.Services { public class ProtoTypeService : IPrototypeService { public string GetData(int value) { return string.Format("You entered: {0}", value); } } }
Conclusion
Maintaining app.config files and the related WCF binding information for clients to connect to WCF
services in your enterprise can create a deployment and maintenance challenge for your organization.
As the number of Services grows in your Enterprise, dealing with reconfiguring client’s configuration files
as WCF binding properties change or as WCF Services are moved around Web Server Farms can quickly
become a significant task.
Also, leveraging Microsoft UDDI 3.0 Services is a great way to add a layer of Service Virtualization to
better manage changing Uri’s for services. It allows you to change the Uri and/or Service metadata in
Page 59
one place and clients that query UDDI Services will pick up the changes and keep working without a
configuration file change.
This solution was a quick way for us to overcome this challenge in the short term and may provide value
to you as you work to find solutions to similar problems.
Page 60
BizTalk Dashboard By Salam Y. ELIAS, passionate of BizTalk This article assumes you are familiar with BizTalk Server, WMI, Enterprise library and VB .Net. Audience: BizTalk Developers, IT administrators & DBAs: BizTalk Server 2006/2009,
VS.NET 2005, WMI Skill level: Intermediate to Expert
For a full demo, please visit my blog at http://salam.hd.free.fr/BlogEngine/ and look for
the entry "BizTalk Dashboard. Nice handy BizTalk admin tool"
Introduction
My story with BizTalk server started since the beta version 2000. I managed BizTalk
server platform for almost 8 years, did a lot of migration, day-to-day operations and
educated my team members on developing integration application and monitoring the.
Each version was shipped with some tools to allow monitoring BizTalk, for instance for
version 2000 and 2002, Microsoft provided some scripts to manage suspended
messages, databases, a web site to query history data which was then replaced by HAT
starting version 2004. In this version orchestrations were introduced along with many
other improvements. Tools have kept on improving in BizTalk 2006 R2 and 2009.
I should also mention that several very interesting tools made available on codeplex to
ease the life of developers and administrators.
One tool was missing is a real time monitor or dashboard to understand what is going
on in my platform. I decided to create a tool to enable me with an eye of bird at my
convenience watch what is going on from my desktop and not necessarily be in front of
the server.
At some point in time, I acted as a DBA; in fact I was impressed by Idera SQLcheck tool
which allows in one screen measure the health of SQL server. I started architecting the
solution by the end of 2008. After doing some research, I decided to use WMI as the
base for my tool, I called BizTalk dashboard, to retrieve BizTalk performance counters
and display them in a winform application. The tool monitors performance counters in all
categories that have their values expressed as “/sec”, i.e. message sent /sec,
orchestration created/sec…….
WMI issues I met in the beginning
First of all, I was thinking of using WMI events so that my interface does not need
polling. I wanted to subscribe to BT performance counter events. I discovered that with
BizTalk performance counters it was not possible, or at least I didn’t find how to do it so
my tool still uses polling. I also ran into the missing counters issue. Following MSDN
Page 61
documentation on performance counters, I understood that what I was looking for to use
was Win32_PerfFormattedData_BizTalk classes. When I tried to setup a logmon
session on BTS 2006 R2 box, with those counters I discovered that they were simply
not there. After searching and posting some messages to MSDN newsgroup, I
understood that some WMI classes are not registered properly or disappears because
of SPs updates or some other unknown reasons for me. This is the case until today, I
have setup 2 new brand BTS 2009 on 2 virtual machines, and perf counters were
missing. In case you are in this situation, please visit MSDN and search for WMIDiag or
the wonderful blog at http://blogs.msdn.com/wmi/archive/2006/05/12/596266.aspx
The third challenge was designing a dynamic configurable gauge. As I am not so good
in graphics developments, I came across a fantastic gauge at
http://www.codeproject.com/KB/vb/A_gauge_part_2.aspx
Requirements for the tool were
i. The tool should allow IT professionals and BizTalk developers to help them
acquire good knowledge of their platform
ii. The tool should be easy to configure through xml configuration files
iii. Display measures in gauges laid out on the interface according to a specific
category of BizTalk performance counter values.
iv. Logs necessary information (Start, error, successful retrieving of perf counters
remotely…)
v. In the config file, one should indicate the name of the server to monitor;
otherwise it will default to local machine along with a list of other BTS servers.
vi. In the config file, one should indicate the name of host instances names available
in the environment. The server to monitor, otherwise it will default to local
machine along with a list of other BTS servers.
vii. The tool should allow changing the server/host instance name in real time
without the need to reinitialize the applications.
viii. The tool must be able to run from client machines, so security should be taken
into consideration
ix. All gauges should be parameterized dynamically
Page 62
Figure 15
The configuration settings used by the tool are shown above. Here I would like to
highlight two parameters "IntervalUpdateCounters" and "BiztalkCounterscategories".
The first parameter is for polling the perf counters; here it is every 1000 millisecond. The
2nd should be always as indicated.
How BizTalk dashboard works
Software needed
A. .Net Framework 2.0
B. The Agauge dll
C. Enterprise Library 3.1 – May 2007
Run:
1- You will need to update the configuration file with the information for the
BizTalk Environment you are monitoring.
2- It writes to a log file to a directory declared in the environment variable
“temp”
3- It reads config file, display gauges for the server name displayed in the 1st
combobox and the host instance name displayed in 2nd combo box
according to the category in the 3rd combobox, in our case Messaging and
XLANGs which as you can see in Figure 2.
Page 63
Figure 16 - BizTalk Dashboard initialization
4- - As soon as your platform receives messages, gauges will start to shoot
up. Figure 3, 4 and 5 shows some gauges in action following some load
testing according to a scenario I have written using BizTalk Load Gen
2007
In this lab, I configured my gauges with 500 as maximum value, threshold at 350.Read
the blog post below to see how you can use Loadgen to stress test your BizTalk
environment.
http://salam.hd.free.fr/BlogEngine/post/Basic-scenario-to-stress-test-Biztalk-platform-
with-Microsoft-LoadGen-2007.aspx
Page 64
Figure 17 - Watch Messages received/sec and Lock failures/sec
Page 65
Figure 18 - Watch DB transactions/sec, Orch completed/sec, Orch created /sec & Persistence points/sec
Here is the output for Loadgen during the session
ShutdownDelay: 1000ms
.FilesSent: 1000
StartTime: 1/17/2010 3:05:29 PM
StopTime: 1/17/2010 3:05:41 PM
DeltaTime: 12.3277972Secs.
Rate: 81.1174927504486
BizTalk dashboard is suited for:
a. Developers should stress test their application before deploying it to production.
Before implementing their application in production, For example, they can see
Page 66
how many persistent points are created per second which might allow them to
revisit their orchestration architecture.
b. For IT administrators, it allows them to watch with an eye of bird from their
desktops what is happening in BTS platforms
Future enhancement
o Automatic discovery of host instances
o Log to CSV. This feature should allow IT department to have a baseline
with which they can run the tool on constant intervals to monitor platform
evolution.
o Use of WMI events if possible as it is according to me should be more
efficient.
o Sends alerts when threshold is crossed for a specific performance counter
in a specific category
o Log file should not be hard-coded
Points to be taken into consideration
You might encounter some access denied errors which can be caused mainly by either missing SQL, WMI, or REGISTRY access permissions for the user running the tool.
Indeed, one of the assumptions that I often make with BizTalk dashboard is that the user running the tool will have complete access rights to both BizTalk Server and SQL Server but it is not always the case.
Please check that counters WMI classes are registered properly on your box.
Sometimes it might be due to classes not registered correctly. Please use
WMIDIAD tool to check the health of your WMI repository. Check the following
URL if you have any issues with performance counters
http://blogs.msdn.com/wmi/archive/2006/05/12/596266.aspx#_Toc135182722
Casting String to Single issue. I forced my main application to use Cultureinfo
and set its Current thread’s Currentculture to run using en-US culture. This
because in casting from string to a single depend on decimal separator defined in
Regional settings. I discovered the issue as I was working in en-US format
machine, when I deployed to another machine where it had French environment,
it is “,” not “.”, so my cast was crashing.
BiztalkDashboard.log will be always written in temp directories. Log file name is
hard coded for the moment.
Salam Y. ELIAS
http://salam.hd.free.fr/
Page 67
Dynamic Send Ports Diego V. Martínez, MCTS: BizTalk Server 2006 R2, [email protected] / [email protected]
2010-Mar-03, Buenos Aires, Argentina
Introduction
Dynamic Ports is a feature in BizTalk that is not widely used. In my opinion there are certain situations
where Dynamic ports can greatly simply the solution. Perhaps most of the interfaces designed in BizTalk
will not need to use Dynamic Ports, but it’s still an important capability to understand.
If you find a business requirement that could be solved with Dynamic Ports, go ahead! Not using
Dynamic Ports in those cases will your BizTalk solution more complex and hard to maintain.
Static Ports are physical ports that are configured during deployment. Their configuration does not
change while the application is running. Dynamic Port allows you to change it configuration during
runtime.
It’s clear that we’re talking about Send Ports only, ok…? Dynamic Ports does not apply to Receive Ports.
You cannot change the configuration of a Receive Port (or a Receive Location) during runtime.
Page 68
Static Send Ports vs. Dynamic Send Ports
Beside the runtime configuration possibility that Dynamic Send Ports offer over Static Send Ports,
there’re other differences that can have an impact on the overall BizTalk solution. Here are a few
differences:
Subject Static Send
Ports
Dynamic Send
Ports
Observations
Complexity of solution Messaging and
Orchestrations
Orchestrations
Only
Dynamic ports require an Orchestration.
Ordered Delivery at
Send Port
Yes No Ordered Delivery feature is not available.
If Ordered Delivery matters, workarounds
should be applied at orchestration level,
e.g., using FIFO Singleton Pattern in
combination with Delivery Notification at
the Logical Send Port.
Mapping Configuration
in Send Port
Yes Yes
Configure Backup
Transport at Send Port
Yes No Backup Transport is not available when
using Dynamic Send Ports.
Configure Retry Options Yes Yes
Configure Pipeline at
Send Port
Yes Yes
Configure Send Handler Yes No Send Handler configuration is not
available when using Dynamic Send Ports.
Default Send Handlers are used
(BizTalkServerApplication or
BizTalkServerIsolatedHost depending
transport type used).
Configure Filters at Send
Port
Yes Yes
Configure Certificate at
Send Port
Yes Yes
Configure Tracking at Yes Yes
Page 69
Send Ports
Scenario Example
The following is a simple BizTalk example using a FILE Receive Port/Location and a FILE Send Port, both
bound to an Orchestration.
BizTalk Server
FILE Receive
Location
Orchestration FILE Send
Port
Inbound
Folder
Outbound
Folder
Let’s start with a FILE Static Send Port first.
Receive Location, Orchestration, and Send Port have the following configuration/design:
Receive Location Configuration:
Orchestration Design:
Page 70
Static Send Port Configuration:
This design causes every file that arrives to the URI set in the Receive Location, to be picked up, sent to
the orchestration, and then stored in the output URI configured of the Send Port.
All the files picked up are stored in the same folder, with the same send port properties like file name
pattern, copy mode…, etc. The Send Port configuration is static for every file processed; that’s way is
called “Static” Send Port.
What’s happen if we have the need to change same Send Port configuration according to message
content (i.e. same element of the message received)? For example, if the files we’re picking up have a
date time element, and the ones received with January on it we want to be stored in a January folder,
Page 71
(or with the word “January” as part of the output filename), the ones received with February on it, send
out with the word “February” as part of the filename, and so on.
How this could be accomplished? There’re some solutions. One could be making use of the “Decide
Shape” in the orchestration, so for every message you received into BizTalk, and evaluation need to be
made (ex. evaluating the date time element), so the file could be sent to a different Send Port according
to the value read. Each of the static Send Port has it URI set according to our needs.
This approach needs an orchestration design similar to this:
As you can see, for each situation we want to evaluate, the orchestration needs to have a rule for it. For
each rule, it’s needed to add a new Logical Port in the orchestration and also a new “Physical” Send
Ports configured in the BizTalk Administration Console. This could be very complex and hard to
maintain, especially when new evaluations are needed during the solution lifetime.
Page 72
A best approach should be design using a Dynamic Send Port! Let’s say that our solution is receiving XML
files like the one below:
<ArgentineSoccer xmlns="http://BTS_DynamicSendPorts.Xsd_Example">
<Team>Boca Juniors</Team>
<GroundCity>Buenos Aires</GroundCity>
<League>Primera División</League>
<Foundation>
<Year>1905</Year>
<Month>April</Month>
</Foundation>
</ArgentineSoccer>
Let’s say we need to use the /ArgentineSoccer/Foundation/Month XML element of the above example
to know where to route the files received.
I make Month element a distinguished field, so I can reference its content easily from inside the
orchestration.
Now, Receive Location, Orchestration, and Send Port have the following configuration/design:
Receive Location Configuration (same as Static Send Port example):
Page 73
Orchestration Design:
Dynamic Send Port Configuration:
As you can see, this orchestration has a new shape: “Set Send Port Configuration”. This Message
Assignment shape set all the variables necessary to automate the Dynamic Send Port. In our example,
those instructions are:
Page 74
Message context properties related to the file transport need to be set for Message_Out. We also need
to set the Microsoft.XLANGs.BaseTypes.Address context property for the dynamic send port.
So, the above message example, with “April” on its Month content, is sent to the “D:\temp\April”
output folder:
Page 75
This example uses FILE context properties because we want to use a Send Port of type FILE. If you want
to use another type of Send Port you need to set other context properties (i.e., WCF for WCF Send Ports,
FTP for FTP Send Port, SMTP for SMTP Send Port, etc…). With Intellisense (or browsing the MSDN Web
Site) you can find all the context properties available for each Send Port type.
So, that’s all! With a simple orchestration and dynamic ports can solve the problem that will be much
harder to solve with static ports.
One thing to note is that when the Orchestration’s Logical Send Port is created with “New Configured
Port Wizard”, the “Dynamic” Port Binding need to be selected. This will also create the corresponding
Dynamic Send Port on the BizTalk Administration Console when the solution is deployed. So, no new
Send Port needs to be created manually on BizTalk Administration Console.
Conclusion
Page 76
Dynamic Send Ports have certain limitations that I described earlier. However there are certain
situations where they can greatly simplify the solution and make it easier to maintain.
Page 77
BizTalk 2009 Oracle Integration using the BizTalk Adapter Pack 2.0 Praveen Mognti, Ceridian
This article will show you how to utilize the WCF-based Oracle adapters from the BizTalk Adapter Pack
2.0 to connect from BizTalk to Oracle R12. In this article we will walk through the difference between
the Oracle DB adapter and the Oracle EBusiness Suite (EBS) adapter.
The beauty of the Oracle DB bindings and Oracle EBS bindings is that from BizTalk we can call Oracle
Stored Procedures, Functions, and Views, as well as Concurrent programs. A concurrent program is an
instance of an execution file along with parameter definitions. Concurrent programs use concurrent
program executable to locate the correct execution file.
Different types of scripts/programs that can be attached to concurrent programs are:
A sql script
A Sql*Loader program
Java program
Oracle Report
Pl/SQL program (or call it a stored procedure/package procedure)
Host script, like a Unix shell script
Pro*C/Spawned
Perl
Software requirements to connect to Oracle from BizTalk Server
Installed:
SQL Server 2008
Visual Studio 2008
BizTalk Server 2009
Adapter Pack 2.0
Oracle Client 11g
The BizTalk Adapter Pack 2.0 consists of following adapters
1. Oracle Database (DB) 2. Oracle E-Business Suite (EBS)
Page 78
3. My SAP Business Suite 4. Siebel eBusiness Applications 5. SQL Server
As this article is about connecting to Oracle and in particular running concurrent programs, I will
illustrate the difference between Oracle DB adapter and Oracle EBS adapter.
Oracle DB Adapter: o Polling support for Stored procedures and Functions o PL/SQL tables
Oracle EBS Adapter o Browse and search metadata for each Oracle application o Support Interface tables, Interface views o Support for PL/SQL APIs o Concurrent Programs, Request Sets o Support for polling tables, Stored Procedures
When to use DB adapter and EBS adapter
As far as how to choose between the Oracle DB adapter and the Oracle EBS adapter, it depends on what
you need to do. If you are updating tables, inserting into tables, selecting data from table, calling a view
or stored procedure then we use DB adapter. If you are calling concurrent programs we use EBS
adapter.
Calling a Concurrent Program
Create a new BizTalk project, add a Schema by selecting Add Generated Items and select Consume
Adapter Service.
Page 79
Select the Oracle EBS Bindings and then enter a URI. The URI for the EBS Binding starts with
oracleebs: // and then enter the name of your Oracle instance. Once you have entered your URI
then click on the Configure button.
Once the Configure Adapter dialog appears we will start entering data in all of the tabs. Let’s start
with the Security tab. Select the client credentials type. On our example, we are going to select
Page 80
UserName from the drop down list box. We need to enter the User Name and Password. We are
now ready to move to the next tab.
Page 81
There are a number of properties that you can set on this URI Properties. We need to minimally
set the PortNumber and DataSourceName properties.
This is all of the information that we will need so hit the OK button and when we return to the Consume
Adapter Service dialog hit the Connect button.
After connecting to Oracle via Oracle EBS Adapter, we can select the Contract Type (Inbound,
Outbound). Then we can select Application-Based, Artifact-Based or Schema- Based, as the figure
below describes we select artifact-based view and select concurrent programs which displays all
the available concurrent programs.
Page 82
Page 83
After selecting the concurrent program, the Adapter Service generates a Schema with two nodes
(request and response) and a BizTalk binding file.
Page 84
The generated schema has the namespace:
http://schemas.microsoft.com/OracleEBS/2008/05/ConcurrentPrograms/
A binding file is also generated that include send port information, which is request response type.
After deploying the application into BizTalk Administration console, import the bindings file which
creates two-way send port (WCFSendport_OracleEBSBinding_Concurrent_Program_)
Need to create send pipeline (concurrent schema with request) with and receive pipeline
(concurrent schema with response).
Send port configuration:
Page 85
Port Type: WCF—Custom
SOAP Action Header: Operation Name -- “This is from the logical port operation from
orchestration”
Bindings: OracleEBSOraganizationID
OracleEBSResponsibilityKey
OracleEBSResponsibilityName
Password
User Name
Credentials: User Name, Password
Page 86
Page 87
Page 88
Sample XML file that is used to run the concurrent program in Oracle is shown below.
Sample XML response file from Oracle is shown below.
Page 89
Conclusion
BizTalk Server has provided connectivity to Oracle databases for a long time. With the release of BizTalk
Adapter Pack 2.0 they have added the ability to connect with OracleEBS and execute concurrent
programs.
Page 90
Querying a SQL Server Table using Business Rules Agustin Mantaras Rodriguez, Premier Field Engineer, Microsoft
Pre-Requisites:
You will need some experience using the Business Rules Composer (some basic
staff is taken for obvious)
Benefits:
There is no need to call a .NET component with SQL database helper functions or
whatever
Business rules engine will catch the results.
If the requirement changes, you can adapt the business rules on the fly with no
need to redeploy the orchestration.
Use Case
The application must retrieve the picture path of a given customer from table
tblCustomers on database Test and then perform several actions (no matter what)
Table looks like:
How to do it using Business Rules:
Steps
#1# You must create the XSD to call the Business rule engine in our case could be:
Page 91
Where CustomerID will be an input paramenter and Picture an output.
Now Open the Business Rules Composer
#1# Add a New Definition to the desired already created vocabulary
#2# The vocabulary Definition Wizard will appear. Select the option Database Table or Colum
and click next
Page 92
#3# Give a Definition Name a description
#4# Click on browse button to select the binding field in the database
Page 93
#5# Click OK and the definition wizard window will change to reflect:
Page 94
#6# Select Perform a Get Operation since we are just querying the database
#7# Click on Finish and do the same steps for the Picture field
#8# Save the vocabulary definition and publish it.
Let’s create the policy!
#1# Add a new Policy called BRCustomers
#2# Add a new Rule to the policy and call it BRCustomers
#3# Under the Facts Explorer got to XML Schemas tab and right click the Schemas node to
browse for the BR_Customers.XSD file
Page 95
This is the fact we are going to use with the policy.
#4# This is what we are going to:
What is this?
Textual this means:
If the CustomerId field of the incoming BizTalk Message is equal to CustomerID Field on the
table i will return the corresponding Picture field
Page 96
So... it is just a seek for the Customer ID Field.
The magic in here: the BusinessRules engine will perform internally the T-QUERY :
SELECT Picture FROM tblCustomers
WHERE CustomerID = @CustomerId
And you do not need to do nothing :-)
So…
#5# From the Facts Explorer Drag the CustomerID Field and drop in the first argument of the
is equal to predicate (already inserted)
#6# Now Click on vocabularies and Drag the CustomerID database field in the second argument
of the is equal to predicate.
#7# Now Go to XML Schemas again, drag the Picture field and drop it in the THEN Actions
Section
Page 97
#8# Go to Vocabularies TAB, drag the Picture database field to the assignment side of the
THEN expression.
#9# Save Everything, publish and deploy de Business Rule
Page 98
How to call this Business rule form BizTalk
Overall picture:
#1# add the Following references to the BizTalk project:
(Microsoft.RuleEngine) C:\Program Files (x86)\Common Files\Microsoft
BizTalk\Microsoft.RuleEngine.dll
(System.Data) C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Data.dll
#2# Create the BusinessRule Scope (transactiontype = Atomic)
#3# At BusinessRule scope level create the following variables:
RulesDataConn of type Microsoft.RuleEngine.DataConnection
SQLconn of type System.Data.SqlClient.SqlConnection
SQLTran of type System.Data.SqlClient.SqlTransaction
#4# IN the BusinessRulesConnect Expresion:
SQLconn = new System.Data.SqlClient.SqlConnection(Connection string value);
SQLconn.Open();
SqlTran = SQLconn.BeginTransaction();
RulesDataConn =new Microsoft.RuleEngine.DataConnection ("DataBaseName", "TableName",
SQLconn,SqlTran);
Page 99
#5# Insert a call BusinessRule Shape and configure it:
#6# Insert the UpdateComClose Expresion and type:
RulesDataConn.Update();
SqlTran.Commit();
SQLconn.Close();
