MSMQ Triggers Topics | Previous | Next

Using MSMQ Triggers

Triggers and their rules are displayed in, and can be managed from, the Computer Management snap-in in the Microsoft Management Console (MMC) for Windows 2000 and Windows NT 4.0. For Windows 2000, you must first expand Services and Applications and then expand Message Queuing in the console tree (usually the left pane).

Under the Triggers folder, the Trigger definitions folder and the Rule definitions folder can then be expanded to view individual trigger and rule definitions respectively. Alternatively, a queue folder can also be expanded to view related triggers and rules. Simply right-click a trigger or rule to access properties and definitions.

Note

The version of MMC required for using MSMQ Triggers with the Computer Management snap-in is version 1.1. This version is not provided with Windows NT 4.0. For information on upgrading the version of MMC you are using, see:
Microsoft Management Console Home Page.

For more information on MMC and using snap-ins, see Windows Help for MMC.

Managing Triggers

All triggers created on the local computer are displayed in the Computer Management snap-in. The left pane displays the trigger set and the rule set, while the right pane displays additional properties associated with each trigger.

Triggers can be serialized. Serialized triggers will process messages in the order in which they arrive; however, the throughput is lower than for non-serialized triggers as messages are processed one at a time. Non-serialized triggers allow for higher throughput but may not process messages in the order in which they arrive, such as when multiple messages are processed simultaneously. Multiple triggers associated with a queue must be either all serialized or all non-serialized, otherwise their behavior cannot be defined. It is recommended that you use only a single trigger with the serialized option since the order of trigger firing is random according to their GUIDs.

The following describes the various tasks associated with managing triggers on a computer.

To create a trigger

1. In the console tree, expand Triggers, right-click Trigger definitions, point to New, and then click New trigger.
2. In Trigger name, enter a name for the trigger.
3. In Queue path name, enter the name of the queue to attach the trigger to. This must be the path name, not the format name for the queue. For example, Mycomputer\Myqueue is a valid format.
4. Select if the trigger is to be enabled or disabled.
5. Select if the trigger is to be serialized or not.
6. Create rules for this trigger as needed. For more information, see To create a rule.

Note

Before creating a trigger, verify that the account the MSMQ Trigger Service runs under has been granted the Peek Message permission for all existing queues that will be associated with triggers.

To edit a trigger definition

1. In the console tree, expand Triggers, double-click Trigger definitions, right-click the applicable trigger, and then click Properties.
2. Change the trigger properties as needed.

To delete a trigger

• In the console tree, double-click Triggers, expand Trigger definitions, right-click the applicable trigger, and then click Delete.

Managing Rules for Triggers

All rules created on the local computer are displayed in the Computer Management snap-in. You can assign multiple rules to a trigger; in this case, the rules are executed in the order they are displayed in the rules list. You can change the priority of rules in this list. Rules displayed are disabled by default, you must select the applicable check box next to the rule to enable it for use with the trigger.

To summarize, a rule is comprised of one or more conditions, with an action executed when the condition(s) are true. The condition is applied to a message when it arrives at the monitored queue, and yields either a true or false result. Multiple conditions must all be true for an action to be executed. If no condition is specified, this will always return a true value. This is useful when you want a trigger to fire unconditionally every time a message arrives at the monitored queue. The following table lists the supported conditions.

Actions taken when a condition is true are either expressed in the form of an executable file and arguments (parameters), or in the form of a COM component, method, and arguments. You can specify one or more arguments to be passed per action. The supported arguments are listed on the Action tab for the rule definitions property page.

When the action specified is in the form of a COM component, you can specify a return value that determines whether the MSMQ Trigger Service will continue processing rules or not. In this case, the return value should be of the enum type MSMQTriggerObjects::RulesProcessingStatus, and can have the values RULES_PROCESSING_CONTINUE or RULES_PROCESSING_STOP.

The following describes the various tasks associated with managing trigger rules.

To create a rule for a trigger

1. In the console tree, expand Triggers, right-click Rule definitions, point to New, and then click New rule.
2. On the General tab, enter a name and a description for the rule.
3. On the Conditions tab, select a condition from the list, enter the condition value or string in the space adjacent, and then click the plus (+) button. (You can also use the minus (-) button to remove a condition). Repeat this step as needed.
4. On the Action tab, do one of the following:
   • To start an executable when the condition is met, click Start standalone executable and in Standalone EXE path, enter the folder path and name to the executable file. If desired, select the Show window check box.
   • To start a COM component when the condition is met, click Invoke COM component , in COM component prog-id, enter the program ID or CLSID for the component, and in Method name, enter the method used.
5. In Parameters, select an argument from the list, and then click the plus (+) button. (You can also use the minus (-) button to remove an argument). Repeat this step as needed.
6. If applicable, click the up-arrow or down-arrow buttons to move each parameter higher or lower in priority. This changes the order in which the parameters are passed.
7. When finished, click Apply and then click OK.
8. In the console tree, right-click the trigger you want to associate the rule with and then click Add/remove rules.
9. On the Rules list tab, select the check box next to the new rule to enable it.

To edit a rule definition

1. In the console tree, expand Triggers, double-click Rule definitions, right-click the applicable rule, and then click Properties.
2. Change properties and values as needed.

To change the priority of a rule for a trigger

1. In the console tree, expand Triggers, expand Trigger definitions, and then expand the applicable trigger.
2. Right-click the applicable rule underneath the trigger, point to All Tasks, and then click Move Up or click Move Down as needed to give the rule a higher or lower priority respectively.

To delete a rule

• In the console tree, expand Triggers, expand Rule definitions, right-click the applicable rule, and then click Delete.

Changing Default Configuration Values

MSMQ Triggers installs with a set of default configuration values. You can change these values after installation using the Computer Management snap-in by right-clicking Triggers, clicking Properties, and then changing the values as needed.

All configuration information, as well as trigger definition information, is stored in the local registry under HKEY_LOCAL_MACHINE\Software\Microsoft\MSMQ\Triggers.

Notes

• The Default message body value is the size of the buffer that the MSMQ Triggers Service will allocate for an incoming message. This value should be set to a size that will accommodate 90% of all messages that are expected to arrive in monitored queues. If this value is set too small, it will force the service to reallocate these buffers for every message. If set too large, too much memory will be allocated.
• If you want to use MSMQ Triggers Monitor, you must first select the Write to log queue check box. For more information, see Using MSMQ Triggers Monitor.