MSMQ on Pocket PC 2003

Introduction

A few years ago mainstream software development was all about desktops and servers, both being Personal Computers. This is rapidly changing as more and more devices emerge. Today's world has Smartphones, Pocket PCs, Tablet PCs, Media Centers and many more to emerge. As complex as it is to understand all these devices and their differences, Microsoft has made it equally complex it to understand the different Windows brands -Windows Embedded, Windows CE, Windows Mobile, etc.

A few years ago it seemed to be cool and bleeding edge to support different devices other then the mainstream PC. But as more devices emerge and as it becomes easier to develop software for those devices, the more rapidly consumers and corporations will adopt them. A few years from now it will be essential to support such devices and for developers to have experience with development on such devices. This article builds on top of the existing article "MSMQ, your reliable asynchronous message processing". It will show how MSMQ can be used on Pocket PC 2003 and at the same time provide an introduction to mobile development and the Compact Framework (CF).

Understanding the different Windows brands

Microsoft uses three main Windows brands. Each brand is targeted towards a different set of devices. There are gray areas between the different brands, but the device to support will determine which Windows version to use:

Windows Embedded - This encompasses all versions of Windows targeted towards any device other then the PC (desktop and server). Windows Embedded consists of two main brands - Windows XP Embedded and Windows CE.
Windows XP Embedded - This is a componentized version of Windows XP Professional. Thus you select from the existing Windows XP Professional components which ones you want to include in your OS image. This allows you to create smaller OS images for different devices while still supporting any Windows-based application (as long as the components the application requires are included in the OS image). Windows XP Embedded only supports Intel x86 hardware and is not a real time OS. Examples would be kiosks, retail devices, ATM's, etc.
Windows CE - Is a real time operating system which also supports platforms other than Intel x86. It is not bound to a specific device but rather contains components to support a wide variety of small devices.
Windows Mobile - Microsoft created Windows Mobile to provide a rich experience for end users as well as to provide strict guidelines for Pocket PCs and Smartphones. Windows Mobile only runs on devices which support the Windows Mobile standard. The three main types of devices supported are:

The diagram below visualizes the three brands. This is not a complete diagram but rather concentrates on the Windows CE and Windows Mobile brands. It also shows the development tools available to build applications on these platforms. This MSDN article answers a number of questions about how to develop for these devices and platforms.

Microsoft also ships a Compact Framework used to build .NET applications for Windows CE and Windows Mobile (both Windows Pocket PC and Windows Smartphone).

Building your Pocket PC 2003 application

When you create a new project you can select the project type (list on the left side). Under Visual Basic and under Visual C# you see an entry called "Smart Device". Underneath it you find Pocket PC 2003, Smartphone 2003 and Windows CE. These are the three different devices you can use the Compact Framework on and which VS.NET 2005 allows you to create applications for. You can create for each an application (Windows forms), class library or control library (not supported for Smartphones). This by default references the Compact Framework. Under the references you suddenly also see an "mscorlib", which is the "mscorlib" for the Compact Framework. When you add new references you see also that the list is smaller. That is because the Compact Framework only supports a subset of the full framework. The Compact Framework 2.0 added the System.Messaging assembly/namespace which provides full support for MSMQ on Pocket PC and Windows CE but not for Smartphones.

Windows forms is available for all three devices and differs from the traditional desktop Windows forms in that the screen size available is much smaller. The designer shows a fixed-size window which reflects the size available on selected devices. How to add controls through the toolbox, how to position and resize it, how to set its properties and how to add event handlers is the same as for the traditional desktop Windows forms. The list of properties and events will be shorter as not all are supported by the Compact Framework, or more specifically by the devices themselves.

When running the application the VS.NET IDE shows a deployment dialog. You can choose where to deploy and run the application. VS.NET provides Emulators so you can run and test the applications without requiring an actual physical device. Emulators are available for Pocket PC 2003, Smartphone 2003 and Windows CE 5.0. You can also choose a form factor, meaning the skin used when showing the device in the emulator. For example you can choose between a "Pocket PC 2003 Portrait" and a "Pocket PC Phone 2003 Portrait".

Running on a Pocket PC 2003 Emulator

Choose "Pocket PC 2003 SE Emulator" to deploy and run your application on the Pocket PC Emulator. This starts a virtual machine and loads the Pocket PC 2003 OS into that virtual machine. Devices like Pocket PCs and Smartphones can utilize an Intel x86 processor or an ARM (Advanced RISC Machines ) processor. The emulators which come with VS.NET are emulating ARM-based devices. All device emulator images are stored in the following location - "C:\Program Files\Microsoft Visual Studio 8\SmartDevices\Emulators\Images". You find the Pocket PC image under the sub folder "PocketPC\2003\1033" and the Smartphone image under the sub folder "Smartphone\2003\1033". Keep in mind that because emulators are emulating a Pocket PC or Smartphone it will always be slower then an actual device itself.

The emulator window shows a Pocket PC booting up, like a real Pocket PC. It then asks in the emulator window if the Pocket PC is connected to the Internet or Work - choose "The Internet". Since this is the first time the emulator is started and no Compact Framework is yet loaded, VS.NET first deploys the Compact Framework onto the emulator. After that VS.NET shows again the dialog to choose where to deploy the application (it is unclear to me why this is required, but if you always deploy to the same device or emulator you can unselect the option "Show me this dialog each time I deploy the application"). Now VS.NET starts deploying your application files onto the Pocket PC emulator. When completed VS.NET will start the application on the Pocket PC while remotely connecting to it so you can debug the application remotely. In our example it will show an exception as soon as a System.Messaging type gets loaded and called. This is the case because MSMQ is not yet installed and configured on your Pocket PC emulator.

Loading and installing MSMQ on the Pocket PC emulator

You can tell the VS.NET IDE to upload not just the project files but also any other files you need to get onto the Emulator. The MSMQ redistributable files can be found at the following location - "C:\Program Files\Microsoft Visual Studio 8\SmartDevices\SDK\SDKRedist\MSMQ". Because the emulator is ARM-based we take them from the ARM sub folder. Add all six files to the project and set "Build Action" in the file properties (in VS.NET) to "Content". All files marked as content will be deployed in the same folder as your project. To change the location where your application gets deployed to, bring up the Project properties (in VS 2005 double click on the item Properties). Go to the "Device" tab and change the "Output file folder". This by default always points to "\Program Files" followed by your project name. Also any files you marked with "Content" in the build action are deployed into this folder. To deploy your application again, run it again, or choose "Build | Deploy Solution". After redeploying the application, go to the Pocket PC emulator window so we can setup MSMQ on it.

The basics of using the Pocket PC Emulator

The Emulator shows you Pocket PC as it would be on any real Pocket PC device. In the upper left corner you see the "Windows start button". Click on the start button and it will show the start menu. Select "Programs" to bring up the installed programs, one of them being the "File Explorer". Open the "File Explorer" by double clicking on it which shows by default the "My Documents" folder. Click on the white space at the bottom of the file explorer and keep the mouse pressed till the popup menu shows. Select from the menu "View All Files" so we see all files. Right under the Windows start button in the upper left corner it shows "My Documents" with a down arrow. This is your current location and clicking on the down arrow brings up a menu. Click on it and select "My Device" to jump to the root folder of your device. Next double click on "Program Files". This shows the "Program Files" folder where you see a "NET CF 2.0" folder where VS.NET deployed the Compact Framework as well as an "MSMQ Pocket PC" folder where our application has been deployed. Now we want to copy the MSMQ redistributable files to the Windows folder. Go to the "MSMQ Pocket PC folder" and select the following six files (by holding down the CTRL key and clicking on each file) - visadm, msmqrt, msmqd, msmqadmext, mqoa and msmqadm. Click on one of the selected files and hold down the mouse till the popup menu shows, then select "Copy". Next click again on the arrow beside the current folder location (right under the Windows start button) and select "My Device" from the menu. This shows again the root folder of the device. Double click on the "Windows" folder, press the END key to jump to the end of the file list, click on an empty space and hold the mouse key down till the menu appears and select "Paste". Now all six files have been copied to the Windows folder.

Next we configure MSMQ on this Pocket PC. This requires changing the default Pocket PC name. Click on the Windows start button and select "Settings" from the start menu. Select the "System" tab at the bottom and then double click on the "About" icon in the list. This shows the Windows "about" screen. Select the tab "Device ID" at the bottom which shows the current Device name as "Pocket_PC". Change the name to something like "EnterpriseMinds" and click the Ok button in the upper right corner. This brings you back to the Settings screen which you can close with the "X" in the upper right corner. This brings you back to the File Explorer which still shows the files we copied into the Windows folder. Double click on "visadm" to bring up the visual MSMQ administrator console. Click on the "Shortcuts" button and select "Install" from the menu. Click again on the "Shortcuts" button and select "Register" this time. Next we need to restart the Pocket PC for the changes to take effect. Click on the "Exit" button to close "visadm" and next on the Emulator window itself click on the "Power button" (upper right corner). This will ask you if you are sure and you say yes which shuts down the device, shows a black screen and then boots it up again (this may take a while). Now we have reset the device and we want to check if MSMQ has been set up properly. Go back to the File Explorer, which now also appears in the start menu and by default jumps back into the Windows folder. Start "visadm" again, click on the "Shortcut" button and select "Verify". This shows that MSMQ has been properly installed. Now we can go back and run our sample application. First close "visadm" with the "X" in the upper right corner, as well as the File Explorer. Run again the sample application from your VS.NET IDE, which will redeploy any changed files, then launch our sample application while still being connected to it remotely so you can debug through the VS.NET IDE.

Changes to the MSMQ Pocket PC sample application

This sample application is based on the original desktop application attached to the article "MSMQ, your reliable asynchronous message processing". There are five main differences in the MessageQueueManager type:

GetMessageQueueProperties() - The MessageQueue type does not support the following four properties - Authenticate, Category, EncryptionRequired and MulticastAddress. These four properties have been removed.
GetMessageDetails() - The Message type does not support the following ten properties - AttachSenderId, Authenticated, AuthenticationProviderName, AuthenticationProviderType, ConnectorType, EncryptionAlgorithm, LookupId, TransactionStatusQueue, UseAuthentication and UseEncryption. These ten properties have been removed.
StartTransaction() - The type MessageQueueTransaction is not supported at all. Only single message transactions are supported. So we completely removed this method.
SendMessage() - Instead of using a MessageQueueTransaction type we use the MessageQueueTransactionType enumeration to specify if this message is sent under a single-message-transaction or non-transactional.
GetListOfPrivateMessageQueues() - Used Environment.MachineName which is not supported by the Compact Framework. This is set by default to "." which means local machine.

All other System.Messaging types are fully supported. MSMQ on Pocket PC 2003 only allows you to work with local private message queues (no remote private queues and no public queues).

Some more useful comments on the Emulator and CF

This MSDN article answers a wealth of questions when it comes to developing with the Compact Framework. When exiting the emulator it asks you if you want to save the state. This allows you to save its current state, for example our MSMQ configuration, changes to the device ID, etc. This also means that VS.NET doesn't have to deploy the Compact Framework next time as it is already on the device. Next time the emulator is started up it remembers that exact state. You can reset the emulator, which will remove all saved state and bring the emulator back to its original configuration. In the emulator window click on the menu "File | Reset".
Your emulated Pocket PC has an IP address assigned to it. Open up the settings (select Settings from the Windows start menu), select the "Connections" tab and then double click on the "Network Cards" icon. Out of the box the network card "NE2000 Compatible Ethernet Driver" is mapped to the physical network card on your machine. Through that the Pocket PC gets network access. The drop down list "My network card connects to" has the value "The Internet" selected out of the box. Leave this value and click on the NE2000 driver. This brings up a window which shows you the current IP address. Ping that IP address from your physical machine and you will see that you get a response back. Click ok in the upper right corner, click ok to the message shown and then ok to close the connections window.

If you have no network connectivity or use an ISP which only allows a few named machines to connect to the ISP but you already used all of those, then use the "Microsoft Loopback Adapter". Choose the "Add hardware" wizard from the control panel. It will first try to detect any new hardware and then ask you if the hardware has already been connected. Answer yes and from the following list select the item "Add a new hardware device". Next select the option "Install the hardware that I manually select from a list" and then select from the following list the item "Network adapter". From the list select the "Microsoft Loopback Adapter" and finish the installation of this adapter. When the adapter has been installed, open up the properties of the "My Network Places". You will see a new "Local Area Connection". Open its properties, select the item "Internet Protocol (TCP/IP) and open its properties. Choose the option "Use the following IP address" and enter as IP address "192.168.0.1" and as subnet mask "255.255.255.0" Click ok twice to save the new IP settings for this "Microsoft Loopback Adapter". Finally we need to configure the Pocket PC Emulator to use this Loopback Adapter.

In the VS.NET IDE go to the menu "Tools | Options" and then in the list on the left side choose the option "Device Tools" and then underneath it "Devices". This shows the list of devices on the right side. Select the item "Pocket PC 2003 SE Emulator" and click on the Properties button. On the new dialog click on the "Emulator Properties" button and on the next dialog choose the "Network" tab. The option "Enable NE2000 PCMCIA Network Adapter to bind to" is enabled and in the drop down below it has the item "Connected network card" selected. From the drop down list choose the "Microsoft Loopback Adapter" and click ok three times to save the settings of each dialog. Next launch the Pocket PC Emulator through the menu "Tools | Connect to Device", select the "Pocket PC 2003 SE Emulator from the list of devices to launch and click the "Connect" button. In the Pocket PC Emulator click on the "Windows start button" and select Settings from the start menu. Select the tab "Connections" at the bottom and double click on the "Network Cards" icon. The drop down list "My network card connects to" has the option "The Internet" selected. Keep that selection and click on the "NE2000 Compatible Ethernet Driver". In the new window select the option "Use specific IP address" and enter as IP address "192.168.0.2" and as subnet mask "255.255.255.0". Click on ok in the upper right corner, click ok on the message box and again ok to close the "Connections" window. Finally we want to test if we have connectivity (which assumes you have an IIS running on your local physical machine). Click on the "Windows start button" and select "Internet Explorer" from the start menu. In the address bar type in the URL for your local IIS which is "http://192.168.0.1". This brings up the home page of your local IIS.

You can also share a folder on your local machine and connect to it through the Pocket PC Emulator which makes it easy to copy files onto the Pocket PC. First share a folder (right click on the folder and select "Sharing and security", select the option "Share this folder" and enter a name, for example MSMQ) and make sure that everyone has "read" rights to it. In the Pocket PC Emulator open the File Explorer and then click on the "Open" button in the lower left corner. In the new window type in the network path to connect to, for example "\\192.168.0.1\msmq" which then opens that share and you can copy files onto your Pocket PC. Please note that with VS 2005 Beta1 I was unable to do this while using the "Microsoft Loopback Adapter". It showed the error "The network path was not found".

When you close applications on the Pocket PC with the "X" in the upper right corner, this does not really close the application. It just hides the window so it appears to be closed to the user. This is to improve overall responsiveness of the Pocket PC. You can check which applications are running and can close them. Click on the "Windows start button" and select "Settings" from the start menu. Select the tab "System" at the bottom and double click on the icon "Memory". It shows the total memory available and how much is used at the moment. Click on the tab "Running Programs" to see a list of running programs. Select the one desired and click "Stop" to close the program or click "Stop All" to stop all programs.

Summary

Developing mobile applications, whether for Windows CE, Pocket PC or Smartphones can be a daunting task at the beginning, mostly due to the fact that there are many new things to learn - the Compact Framework, the Pocket PC interface, how to work with the Pocket PC emulator, etc. The bigger issue is not that it is very complex to do but rather just getting a good introduction to it. Unfortunately the documentation available is rather lacking. This article hopefully gives you a very good introduction about mobile development, about the Pocket PC interface and how to work with the Pocket PC emulator. After getting over that initial learning curve you will see that it is very easy to developer mobile applications with the Compact Framework and to test and debug them with the available emulators.