Queued Components Sample

Queued Components Sample

     (Windows Forms Application)

This document contains the release information for the .NET Framework Queued Components sample. You will find the following sections below:

Overview

Queued Components is a COM+ feature built on top of Message Queueing Services (MSMQ) that provides a mechanism for invoking and executing components asynchronously. When a client makes a call to a queued object, the call is actually made to a recorder, which packages it as a message and places that message in a queue. A listener reads the message from the queue and passes it to the player. The player makes the actual method calls on the server object.

In order for the server to receive queued messages, it must be activated in some way. Server components can be activated manually, using scripting in combination with the task scheduler, or programmatically. In this sample, we will activate the server component manually.

The sample code consists of a client application and a managed object that is marked for InterfaceQueueing. The listener is enabled by means of a class attribute. On building the application, COM+ creates a queue whose name is the same as the specified COM+ application.

The client application contains a single button. Clicking the button invokes the queued component recorder by means of a queue moniker. All calls through the returned reference are packaged and placed in the appropriate message queue.

Queued method calls will be unpackaged and delivered to the actual server component when it is activated in the Component Services administrative tool. The sample server displays a simple message box to show that the call has made it to the server.

Topics

The following bullets briefly describe the technologies used by this sample.

Location

This sample is located in the Technologies\ComponentServices\QueuedComponents subdirectory of the .NET Framework SDK samples directory.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\QueuedComponents

Building the Sample

In order to properly build and run this sample, the following steps need to be performed.

IMPORTANT: in order to build and execute this sample, MSMQ must be installed on your computer in Workgroup mode.

Double-click My Computer\Control Panel\Add/Remove Programs.

In the Add/Remove Programs dialog, click 'Add/Remove Windows Components' and check the item labeled 'Message Queuing Services'. Click 'Next'.

Windows 2000 has additional steps to install MSMQ:

In the subsequent 'Message Queuing Type' wizard page, click the checkbox labeled 'Manually select access mode to Active Directory'. Click 'Next'.

In the subsequent 'Message Queuing Server' page, click the radio button labeled 'Message Queuing will not access a directory service'. Click 'Next' and setup will complete. Click 'Finished'.

After installing MSMQ, build the sample code by typing BuildAll.bat from the command line.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\QueuedComponents>buildall.bat

If you're building the sample from Visual Studio 7, you will need to register the QCDemoSvr.dll assembly to setup the Message Queue before running the sample. Note: The regsvcs.exe program is located in the %systemroot%\Microsoft.NET\Framework\<version> directory.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\QueuedComponents\CS>regsvcs QCDemoSvr.dll

you will also need to install the QCDemoSvr.dll assembly to the Global Assembly Cache before running the sample. Note: The gacutil.exe program is located in the SDK\v1.1\Bin directory.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\QueuedComponents\CS>gacutil -i QCDemoSvr.dll

The sample builds a C# and VB version of the client application and COM+ component. Source code for each language is stored in subdirectories named \CS and \VB. The C# component has 'CS' appended to its name as viewed in the Component Services administrative tool, 'QCDemoServerCS.QComponent'. The VB version is named 'QCDemoServerVB.QComponent'. When working with the sample code, be sure to observe and/or modify the version of the COM+ component that corresponds to the client application you launch.

Review comments in the source code and build.bat files for more information on sample binary creation and registration steps.

Running the Sample

In order to run this sample, follow the instructions listed below.

  • NOTE: The COM+ .NET samples require Windows 2000 or higher in order to build and run.
  • Build the Queued Components sample code following the instructions above.
  • Type QCDemo.exe from the command line (or launch qcdemo.exe from the Windows explorer).

    For Example:

    C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\QueuedComponents\CS>qcdemo.exe

  • Click the button labeled 'Send Queued Msg'. Alter the string value in the text edit field, and click 'Send Queued Msg' a second time. This should place two packaged method calls in the queue.
  • Next, examine the messages in the QCDemoSvr queue. Right-Click 'My Computer' and select 'Manage' from the pop-up menu. Expand 'Services and Applications\Message Queueing\Private Queues' in the Computer Management console. You should see a queue named 'qcdemosvr' in this node. The queue name corresponds to the name of the COM+ application that holds the queued component (we'll examine the application in a later step).
  • Expand 'qcdemosvr' and select 'Queue messages'. You should see two messages in the right-hand pane, corresponding to the two queued component methods calls we made in the client application.
  • Launch the Component Services administrative tool (also called the 'COM+ explorer'), by clicking 'Start\Settings\Control Panel' then double-clicking 'Administrative Tools\Component Services'.
  • Locate the QCDemoSvr COM+ application by expanding Component Services\Computers\My Computer\COM+ Applications in the left-hand COM+ explorer pane.
  • Right-click the QCDemoSvr application and select 'Start' from the popup menu. This activates the server component. The listener/player will pull messages from the qcdemosvr queue and call into the server. As a result, you should see two message boxes which contain the text strings from the original calls from the sample client application.
  • You can return to the Computer Management console to observe that the qcdemosvr no longer contains queued messages. Subsequent calls from the client application are passed directly to the server and message boxes will appear immediately for each button click.
  • NOTE: in order to return to queuing messages, you must shut down the QCDemoSvr COM+ application (by right-clicking the application in the COM+ explorer and selecting 'Shut down'). Due to a problem in Windows 2000, the QCDemo client .exe must be closed before the QCDemoSvr COM+ application will shut down. This problem will be fixed in a later version of Windows.

Uninstalling the Sample

In order to uninstall this sample, follow the instructions listed below.

  • To uninstall this sample, run buildall.bat -u. or build.bat -u. The batch file will then call regsvcs and gacutil with the /u switch in order to remove the sample files from the COM+ catalog and Global Assembly Cache.

Notes

For the .Net Framework samples to function properly, your Path, Include, and Lib environment variables must be set correctly. In many cases, the SDK install program updates these environment variables for you. However, if you installed the .Net Framework SDK using Visual Studio .NET, or unselected "register environment variables" during setup, these environment variables will not be updated. You can set the Path, Include and Lib environment variables by running SDKVars.bat, located in the <SDKRoot>\Bin directory. SDKVars.bat must be executed in every command shell.