Using the product
This section assumes you have a binary build of the product. One is available from the
Downloads section, or one can be created by
building the sources. This section refers to the directory where the product build is located as
build root, and all command examples assume it is c:\projects\laharsub\build.
Running the server
There are two ways of running the Laharsub server: as a Windows Console Application, or as a Windows Service. Running as a Windows Console Application is more convenient during development, while Windows Service is the recommended way for actual deployment.
Note than running the server requires .NET Framework 4.0.
Configuring the server
Laharsub server consists of the Laharsub.exe executable and Laharsub.exe.config configuration file. Configuration file contains a set of options (documented in the file itself) that control the behavior of the service. The defaults should work well out of
the box, but you may want to adjust the settings further down the road. The configuration file is only read when the server starts up. Changes to the settings made while the server is running do not take effect until the server is stopped and started again.
Running the server as a Windows Console Application
You must have administrative privileges to start the Laharsub server as a console application. This is because the server needs to open a new HTTP listener. To start the server as a console application, open a cmd.exe window with administrative provileges,
This will show the set of configuration options the server is running with, and if all goes well start the server. The terminal window will be blocked. The server can be stopped with Ctrl-C.
Running the server as a Windows Service
This method is suitable for actual deployment, as the server will restart automatically after a system reboot. We will use sc.exe tool that comes with Windows to create, start, and stop the service. The tool must be run with administrative privileges. By
default, the service will be running under Local System account. To create the service, run:
sc.exe create laharsub binPath= c:\projects\laharsub\build\bin\Laharsub.exe start= auto
It is important to provide a fully qualified path name to Laharsub.exe. Also please note the spaces following equal signs.
After the service has been created, it can be started, stopped, and deleted with the following commands, respectively:
sc.exe start laharsub
sc.exe stop laharsub
sc.exe delete laharsub
Note that the service will start automatically after a system reboot since this was the option passed to
Current status of the service can be checked with:
sc.exe queryex laharsub
Verifying the server is running
To verify if the server is running successfully, open up a browser of your choice and navigate to
http://localhost/ps/memory (assuming the default configuration of the base address in Laharsub.exe.config has not been changed). A standard WCF service welcome page should show. If this does not happen, a few cheap ways of troubleshooting before
resorting to debugging include checking the event viewer, checking if the service is running with
sc.exe queryex laharsub (assuming the server is running as a Windows Service), or trying to run the service as a Windows Console Application with
Laharsub.exe /console to see if any exceptions are thrown at startup.
Creating a virtual directory in IIS
The most convenient way of running the samples included in each binary release or built from the source code is to create a virtual directory in IIS that points to the output location of these files.
Each build drop comes with sample web applications (e.g. jquery.chat.html) in the vroot subdirectory of the build root. To run these applications, create a virtual directory in IIS that points to the vroot subdirectory
of the build root. To do this, start Internet Information Services (IIS) Manager, expand <you machine name>|Sites, then right click on Default Web Site and select Add Virtual Directory. In the
dialog that shows up, specify laharsub in the Alias field, and the full path to the vroot directory in the "Physical path" field (e.g. c:\projects\laharsub\build\vroot).
Click OK. The new virtual directory should be created. To verify this step, open a browser window and navigate tohttp://localhost/laharsub/jquery.chat.html. If you are denied access, make sure the ACLs on the c:\projects\laharsub\build\vroot
directory permit read access for users on your machine.
Running a sample chat application: jquery.chat.html
Each build drop comes with sample web chat application (jquery.chat.html) in the
vroot subdirectory of the build root. The web chat application demonstrates how several browser instances can exchange messages using the publish\subscribe mechanism offered by the Laharsub service. The web chat application is implemented in HTML
and demonstrates the use the jQuery pub/sub extension included in this project which implements the client side of the protocol.
To see the chat application in action, you can follow this script:
- make sure you have created the virtual directory in IIS as descried in the previous step,
- make sure the Laharsub server is running (using the steps above),
- navigate to http://localhost/laharsub/jquery.chat.html in the browser of your choice on the same machine where the Laharsub is running (or adjust the host portion of the address if running the client on a different machine),
- create a new chat room by clicking the Create new chat room button,
- copy the updated URL from the address bar and paste it into the address bar of another browser instance (alternatively, manually enter the chat room number in a second browser instance and click the
Join chat room button,
- type some text in one browser, press enter, and see the text appear in the other browser instance.
Running manual tests: jquery.test.html
Another sample that ships with each build allows for manual experimentation with the protocol as well as casual latency tests. The
jquery.test.html allows you to manually invoke individual publish\subscribe REST APIs (create a topic, publish a message to a topic, subscribe to one or more topics). It also contains a simple latency test, whereby the publishes a specified number
of messages at specified time interval to a topic while subscribing to the same topic, and measures the roundtrip latency for these messages. Please refer to the code of
jquery.test.html for details if the UI is not self explanatory enough.