MQ .NET Sample application for Azure - ibm-messaging/mq-azure GitHub Wiki

Starting MQ v8.0.0.2, MQ .NET client assembly can be bundled and installed with your application on production machine. There is no requirement of installing full MQ client on production systems. In such environment MQ .NET client supports only the managed mode transport. The other two, ‘bindings’ and ‘unmanaged’ mode transports are not supported as these require native libraries which are available only in a full MQ client installation. While packaging an application, only amqmdnet.dll assembly will need to be included in the package. No other assemblies are required.

MQ .NET applications can be both desktop as well as web (ASP .NET) applications running on Azure PaaS environments.

This sample application demonstrate the usage of MQ .NET client in Azure environment. The sample is built with the following architecture.

The sample application displays a list of universities and their rating in a web page. As described in the above architecture the browser based application communicates with a worker role application via IBM MQ queues using simple request/reply messaging pattern.

The web role puts a request message to REQUESTQ queue and waits for a response on REPLYQ. The worker role application gets the messages from REQUESTQ, does a database query and puts a response message in REPLYQ. The web role then gets the response message and updates the web page with list of universities.

The sample consists of multiple applications and uses couple of products. Each of the products need to be configured to run the sample application.

Here is the list of applications and products used in the sample.

1. IBM MQ V8.0.0.2 queue manager running on an Azure virtual machine.
2. SQL Server database instance in Azure
3. ASP .NET based WebRole application deployed in an Azure Cloud Service.
4. WorkerRole application deployed in an Azure Cloud Service
5. Application to populate database with sample records

This sections describes the configuration required for products and application.

Important note: All the components (Virtual machines, Cloud Service, SQL Database, Virtual network) must be located in the same Azure geographic region, for example East Asia.

Use Azure Management Portal for performing all configuration.

Create a virtual network by providing a name. Later when creating virtual machine and web and worker applications, choose this virtual network. This ensures both web role and worker role applications can connect to queue manager running on another cloud service.

Add two subnets, one for web role and the other for worker role & virtual machine that hosts queue manager.

Follow these steps to create a SQL database:

1. In Azure console choose SQL DATABASE menu to display a list of database you already created. Choose “CREATE A SQL DATABASE” link.
2. In the “Specify database settings” panel, provide appropriate values. NAME: UniverDB SERVER: “New SQL database server” Leave others to default and press Next.
3. In SQL Server database settings panel specify following Login name: Unidbuser Password: Passw0rd Region: Chose the same region as you did while creating virtual network, for example East Asia. Leave others to default and press next to create SQL server database

After SQL database is successfully created, note down the server address which will be needed while configuring connection string in application.

Important: Later IP address of your WorkerRole virtual machine will need to be added to allowed IP address list otherwise application will not be able to connect to database

4. In Visual Studio 2012 – connect to the above SQL server using address and userid and password.
   1. You may have to user Azure console to alter firewall settings to include your current machines IP to be allowed to connect to SQL Server.
   2. Using VS2012 connect to the above database. Create table called University with the following i. universityId – Integer type. Primary key ii. universityName – nchar (50) Null not allowed iii. universityAddress – nchar(MAX) Null not allowed iv. universityRating – Integer type.

This section describes the steps for configuring an Azure virtual machine with IBM MQ.

The first step is to create a virtual machine using IBM MQ V8.0.0.1 image available in Azure Product gallery. Sample configuration is given below.

Once the virtual machine goes into running state, open a remote desktop session to the virtual machine and login using the userid/password provided.

Create two users, webrole for WebRole and workerrole for WorkerRole applications. Make sure to uncheck “User must change password at next logon” and check “Password never expires” option. Do not add these users to mqm group.

Create a queue manager called QM.UNIVERSITY and configure it as described below

crtmqm QM.UNIVERSITY
strmqm QM.UNIVERSITY

Create the following objects using MQSC. First start MQSC console by running

runmqsc QM.UNIVERSITY

Create a server connection channel.

def channel (UNIVERSITY.CHN) chltype(SVRCONN)

Create a listener and start

def listener(TCP.LISTENER) trptype(TCP) port(2424) control(QMGR)
start listener(TCP.LISTENER)

Define queues for request and reply messages.

def ql(REQUESTQ)
def ql(REPLYQ)

Create an object for user connection authentication.

def authinfo(UIDPW) authtype(IDPWOS) adoptctx(YES) chckclnt(REQDADM)

Update the queue manager to use the above authentication object.

alter qmgr connauth(UIDPW)

Refresh queue manager security.

refresh security type(CONNAUTH)

Quit MQSC

end

Run the following commands to setup user authority

setmqaut -m QM.UNIVERSITY -t qmgr -p "webuser" -all
setmqaut -m QM.UNIVERSITY -t qmgr -p "webuser" +altusr +connect +inq

setmqaut -m QM.UNIVERSITY -t qmgr -p "workeruser" -all
setmqaut -m QM.UNIVERSITY -t qmgr -p "workeruser" +altusr +connect +inq

setmqaut -m QM.UNIVERSITY -n "REQUESTQ" -t q -p "webuser" -remove
setmqaut -m QM.UNIVERSITY -n "REQUESTQ" -t q -p "webuser" +put

setmqaut -m QM.UNIVERSITY -n "REQUESTQ" -t q -p "workeruser" -remove
setmqaut -m QM.UNIVERSITY -n "REQUESTQ" -t q -p "workeruser" +browse +get

setmqaut -m QM.UNIVERSITY -n "REPLYQ" -t q -p "webuser" -remove
setmqaut -m QM.UNIVERSITY -n "REPLYQ" -t q -p "webuser" +get +inq

setmqaut -m QM.UNIVERSITY -n "REPLYQ" -t q -p "workeruser" -remove
setmqaut -m QM.UNIVERSITY -n "REPLYQ" -t q -p "workeruser" +put

The WorkerRole uses XA transactions. So provide authority for the user XA recovery queue.

setmqaut -m QM.UNIVERSITY -n "SYSTEM.DOTNET.XARECOVERY.QUEUE" -t q -p "workeruser" -remove
setmqaut -m QM.UNIVERSITY -n "SYSTEM.DOTNET.XARECOVERY.QUEUE" -t q -p "workeruser" +browse +get +inq +put

Using Windows Firewall utility, open port 2424 (as queue manager will be listening on this port) to allow inbound connections to queue manager.

Create a cloud service that will host both webrole and worker role applications. You will be using this cloud service when deploying application via Visual Studio.

A sample application, mqcloudservice, is available in ibm-messaging/mq-azure repository. Refer the sample code to build your own MQ .NET based WebRole/WorkRole applications.

Note: Building and deploying application to Azure cloud requires Azure subscription Id, cloud service deployment id, certificates and such sensitive information to be embedded into the Visual Studio project (ServiceDefinition.cloud.cscfg file). In this sample such sensitive information has been removed from the project file. Typically this information gets added when a new cloud service type of project is created in Visual Studio.

Prerequisites:

1. Visual Studio 2012 Update 4
2. Azure SDK

Open the attached solution in Visual Studio 2012. The solution has four projects:

1. mqWebSite – ASP .NET WebRole application
2. mqSqlWorker – back end application processing requests from front end
3. mqHelpers – Utility classes used by other projects in the solution
4. PopulateDB – Application to populate sample data in SQL database.

Populating SQL DB with sample data

Use the PopulateDB application to update the SQL server database with sample data. The PopulatedDB reads the sample data from Xml file and updates the SQL server database. The SQL server connection string and sample Xml filename needs to be specified in app.config file.

<add key="SQLDBConnection" value="Data Source=tcp:<sql server host>,1433;Initial Catalog=UniverDB;Integrated Security=False;User Id=studentuser@<host>;Password=Passw0rd;Encrypt=True;TrustServerCertificate=False;MultipleActiveResultSets=True"/>
<add key="RecordsFile" value="RecordsFile.xml"/>

The project already contains sample data in the Xml file. Running the application will first clear the database and then update it with data from Xml file.

Configuration changes

Configuration changes will need to be done in app.config/web.config files so that applications connect to correct queue manager, SQL Server etc. The IBMMQConnection and SQLDBConnection properties define the information required to connect to queue manager and SQL server. Update the values for these properties to point to correct queue manager and SQL server.

For example app.config of WorkerRole will need to be changed. The IP address in “Connname” requires change. So is the SQL Data Source.

<appSettings>
  <add key="IBMMQConnection" value="QMName=QM.UNIVERSITY;Conname=<QM IP>(2424);Channel=UNIVERSITY.CHN;UserId=workeruser;Password=Passw0rd;RequestQueue=REQUESTQ;ReplyQueue=REPLYQ"/>
  <add key="SQLDBConnection" value="Data Source=tcp:<sqlserver host>,1433;Initial Catalog=UniverDB;Integrated Security=False;User Id=studentuser@<host>;Password=Passw0rd;Encrypt=True;TrustServerCertificate=False;MultipleActiveResultSets=True"/>
</appSettings>

Similarly web.config of webrole project also requires change.

<connectionStrings>
  <add name="IBMMQConnection" providerName="" connectionString="Conname=<QM IP>(2424);QMName=QM.UNIVERSITY;Channel=UNIVERSITY.CHN;RequestQueue=REQUESTQ;ReplyQueue=REPLYQ" />
</connectionStrings>

Service Configuration changes

Service configuration file ServiceConfiguration.cloud.cfg need to be changed to suit the virtual network created above. Also ServiceConfiguration.cloud.cfg needs to be updated to use the correct sub-net that was created earlier.

<NetworkConfiguration>
  <VirtualNetworkSite name="VNMQCLOUD" />
  <AddressAssignments>
    <InstanceAddress roleName="mqWebSite">
      <Subnets>
        <Subnet name="FrontEndSubnet" />
      </Subnets>
    </InstanceAddress>
    <InstanceAddress roleName="mqSqlWorker">
      <Subnets>
        <Subnet name="BackEndSubnet" />
      </Subnets>
    </InstanceAddress>
  </AddressAssignments>
</NetworkConfiguration>

Build and Deploy

After making above changes, rebuild the project in Visual Studio 2012. After successful build, deploy the solution using the “Publish” menu. Use the cloud service created above for deploying the solution. Once publishing is over, the Azure deployment log will provide the URL of the application. Use the URL in browser to launch your application.