How to change MSMQ Queues for the EventBus
KB000198
PRODUCTK2 blackpearl
SEE ALSO See the following MSDN articles on MSMQ:
Destination Queues
Referencing a Queue
Direct Format Names
K2 Server
LEGACY/ARCHIVED CONTENT
This article has been archived, and/or refers to legacy products, components or features. The content in this article is offered "as is" and will no longer be updated. Archived content is provided for reference purposes only. This content does not infer that the product, component or feature is supported, or that the product, component or feature will continue to function as described herein.
Introduction
The K2 blackpearl EventBus uses Microsoft Message Queuing (MSMQ) for storage of messages sent from the K2 Host Server. Typically, the destination queue is a local queue on a server. Client applications send messages to the destination queue on the server computer (in this case the server computer can also be referred to as the target computer), and the server applications process the messages after they arrive.
Destination queues can be public or private. When designing a distributed Message Queuing application, you must decide if the destination queues should be public or private queues. Whether a queue is public or private is specified when the queue is created.
After installing K2 blackpearl, a public queue is created. However, you can change the queue to another format (such as Private, or Direct) by modifying the SourceCode.Eventbus.Server.config and the SourceCode.Eventbus.ClientRecorder.dll.config files.
Destination queues can be public or private. When designing a distributed Message Queuing application, you must decide if the destination queues should be public or private queues. Whether a queue is public or private is specified when the queue is created.
After installing K2 blackpearl, a public queue is created. However, you can change the queue to another format (such as Private, or Direct) by modifying the SourceCode.Eventbus.Server.config and the SourceCode.Eventbus.ClientRecorder.dll.config files.
- In K2 4.6.9 and later, the SourceCode.Eventbus.ClientRecorder.dll.config and the SourceCode.EventBus.Server.config files are consolidated into a single configuration file, K2HostServer.exe.Config, which is located at <install drive>K2 blackpearlHost ServerBin on the K2 Server. The connection strings previously stored in the Event Bus config files are now stored in K2HostServer.exe.config.
- Modifying the configuration files should only be done by someone who is familiar with updating XML configuration files and who has knowledge of the environment and connection strings for MSMQ.
MSMQ Options
There are two options for configuring MSMQ queues:
- Public Queues
The advantage of public destination queues is that they are registered in the directory service, where they can be located by other Message Queuing applications. Public queues are persistent, and their registration information can be backed up on the enterprise, making them good for long-term use.
A public queue is created upon installing K2 blackpearl. It is referenced by MachineNameQueueName
- Private Queues
Private queues have the advantage of minimal directory service overhead (faster to create, no latency, and no replication). Local private queues can be created and deleted when the directory service is not working, making private queues attractive for offline operations, where the directory service may not be available.
You can configure a private queue separately. It is referenced by MachineNamePrivate$QueueName
Remote Queues cannot be used as transactions on remote MSMQ Servers is not supported.
Additionally, in order to access queues in different Active Directory forests, you must reference the queue by using the Direct Format Name.
Direct format names are used to reference public or private queues without accessing the directory service. Direct format names are used when performing the following operations:
- Sending messages directly to a computer.
- Sending messages to computers over the Internet.
- Sending messages across forest boundaries.
- Sending messages to any queue while operating in domain, workgroup, or offline mode.
- Reading messages while operating in domain, workgroup, or offline mode.
It is referenced by FormatName:DIRECT=OS:MachineNameQueueName
Queues cannot be created automatically by K2 blackpearl, except for the default public queue created upon installation. You will need to manually create the queues, and then update the K2 blackpearl configuration files to point to the new queue.
MSMQ Queues created by K2 blackpearl
Upon installing K2 blackpearl, two public queues are created. These are visible under the Computer Management > Services and Applications > Message Queuing section on your server.
"Figure 1. Public Queues created by K2 blackpearl]
You can create additional MSMQ Queues using the Computer Management features of your server. For more information on MSMQ Best Practices, refer to MSMQ Best Practices (http://download.microsoft.com/download/F/C/9/FC9989A2-DA75-4D96-B654-4BD29CF6AEE1/MSMQBestPractice.doc)
How to change the Queue Configuration
The steps below describe how the change the MSMQPath used by the Eventbus. This will allow you to change the default queue used by K2 blackpearl.
-
- Locate the SourceCode.Eventbus.Server.config file in the "C:Program FilesK2 blackpearlHost ServerBin" directory
- Use notepad to edit the file and locate the appsettings section (as shown below) <configuration>
<appsettings>
...
<msmqpath>BLACKPEARLEventBus</msmqpath>
<msmqerrorpath>BLACKPEARLEventBus Error</msmqerrorpath>
...
</appsettings>
</configuration> - Change the value for the MSMQPath key, and if necessary, also the MSMQErrorPath key
- Close and save the file
- Locate the SourceCode.Eventbus.ClientRecorder.dll.config file in the "C:Program FilesK2 blackpearlHost ServerBin" directory
- Use notepad to edit the file and locate the appsettings section (as shown below) <configuration>
<appsettings>
...
<msmqpath>BLACKPEARLEventBus</msmqpath>
<msmqerrorpath>BLACKPEARLEventBus Error</msmqerrorpath>
...
</appsettings>
</configuration>
- Change the value for the MSMQPath key
- Close and save the file
Once you make your changes, be sure to save and close the configuration files, and then restart the K2 server.