How to configure a local IBM MQ development environment

IBM Websphere MQ can be an overwhelming product to use as a message broker if you have worked in the past with Microsoft’s MSMQ or the Azure Service Bus. The best way to learn and understand a product is to have your local lab environment, that you can recreate when needed.

With this post I share with you some links how you can setup your own local IBM MQ 9 installation for development purposes.

Step 1: Download IBM MQ Advanced for Developers

Direct link: IBM MQ 9.0.3 for Windows

Step 2: Setting up a development WebSphere MQ server

This very well written blog posts explain how you can setup a queue manager, configure a channel and create a queue.

(Skip step 10 as it isn’t the best way to disable security)

Step 3: Disable MQ Security

The default installation of IBM MQ has security turned on. Without disabling this you won’t be able to use your .NET client application or the BizTalk Adapter to send/receive messages. Be aware that you should only do this on your development environment!

Step 4: Add a firewall exclusion rule

If you are planning to host your local IBM MQ setup in a seperate VM, you will most likely need to setup a firewall exlusion rule so you can access the queue manager from another machine. (If you install IBM MQ as a service it will listen by default on all IP addresses)

Simply add an exclusion rule to allow inbound TCP traffic for the port your queue manager is running on (default is 1414).


Optional: .NET Sample Applications

Setting the MQSeries CCSID by using an Environment Variable

During a smoke test of a new BizTalk Server 2016 (with HIS 2016 and the IBM MQ client) we stubled upon the following exception:

“The program ended because, either the source CCSID ‘1208’ or the target CCSID ‘437’ is not valid, or is not currently supported.”

In this simple test we were sending and receiving messages to/from a queue with a couple of ports, and dit not yet use a pipeline component to set IBM MQ Series Context Properties.

But wait, we needed a way to set the CCSID to 1208!

Luckily, you can set an Environmet Variable to specify the desired CCSID globally:

PowerShell (Run as Administrator):

[Environment]::SetEnvironmentVariable("MQCCSID", "1208", [EnvironmentVariableTarget]::Machine)

MQCCSID: Specifies the coded character set number to be used and overrides the native CCSID of the application. (IBM Knowledge Center)

After applying this, the messages were sent using the correct CCSID:


Upgrade from HIS2013 to HIS2016 on BizTalk2013R2

In a previous blogpost I wrote about how you could use HIS2016 together with BizTalk 2013R2 (on Windows Server 2012R2) in order to use the MQSC adapter with IBM WebSphere MQ9.

This post is about upgrading an existing configured BizTalk 2013R2 environment without removing your current (port) configuration. By reading this description you should already know that this involves some “manual” actions…

These are the steps I followed to upgrade an already configured BizTalk 2013R2 with lots of MQSC SendPorts/ReceiveLocations where I didn’t want to remove all the current binding configuration (wich is what you need to do if you want to remove an adapter and follow the normal installation path…).

Before you start

  • Make sure everything is backed-up correctly
  • Stop everything: host-instances, SQL jobs, SSO,..

Uninstall the old

  • Uninstall the currently installed IBM MQ Client
  • Remove the MQSC COM+ Application
  • Uninstall HIS2013 (but don’t unconfigure anything, just leave the MQSC adapter untouched)
Uninstall MQSC COM+ Application: 
%windir%\Microsoft.NET\Framework64\v4.0.30319\RegSvcs.exe /u "%snaroot%\Microsoft.BizTalk.Adapter.MQSC.dll"

Install the new

  • Install .NET 4.6.2 (.NET 4.6 is a minimal requirement for HIS 2016)
  • Install HIS 2016 (no configuration, more details here)
  • Install IBM MQ Client (64 Bit)
  • Install HIS 2016 CU2

The “manual” part

  • Update the MQSC Adapter info in the BizTalkMgmtDb “Adapter” table
    • Update the AssemblyVersion in InboundTypeName/OutboundTypeName columns to the newer version.
SELECT * FROM [BizTalkMgmtDb].[dbo].[adm_Adapter] where name like 'MQSC' 
New InboundTypeName: 
Microsoft.BizTalk.Adapter.Mqsc.MqscReceiver, Microsoft.BizTalk.Adapter.MQSC, Version=10.0.1000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null
New OutboundTypeName: 
Microsoft.BizTalk.Adapter.Mqsc.MqscTransmitter, Microsoft.BizTalk.Adapter.MQSC, Version=10.0.1000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null
  • Register the MQSC COM+ Application
Install MQSC COM+ Application: 
%windir%\Microsoft.NET\Framework64\v4.0.30319\RegSvcs.exe "%snaroot%\Microsoft.BizTalk.Adapter.MQSC.dll"


  • Reboot your server(s)


This worked for a running setup at my current customer. I cannot give you any garantees this will work on your envirenment! Always test this kinds of upgrades before applying this in your production environment!