Draft - 9 Sep 2009 - LJP
The following assumes that you are using Microsoft Visual Studio 2008 on a Microsoft Windows operating system with Internet Information Service (IIS) installed.
Two parts are required to create a new LabServer:
This part is optional but nice to have around as a reference:
Extract 'LabLibraries.zip' and 'Template.zip' to the same folder so that the folders './LabLibraries/...' and './Template/...' exist in the same folder. Open the Visual Studio solution './Template/Template.sln'. There are ten projects in the solution:
You only need to be concerned with these five:
DO NOT make changes to the other projects! Well, you may want to later on but just get something going first.
This project is provided in the solution to allow development of the LabServer and LabClient in an enviroment without an iLab ServiceBroker getting in the way. The 'DummyServiceBroker' simply provides pass-through methods to allow LabClient-to-LabServer communication. It also generates experiment IDs when experiments are submitted.
The 'LabClientHtml' web application and the 'LabEquipment', 'LabServer' and 'DummyServiceBroker' web service applications use ports on 'localhost' and there is no need to use IIS Virtual Directories. This makes it much easier to move the solution to different development computers or even folders or drives on a single computer. To check these settings, open the project's 'Properties' page and select the 'Web' tab. The 'Using Visual Studio Development Server' will be selected and 'Specific Port' will be assigned a value at or above '8081'.
Before we start making code changes, let's check a few things and then we can compile
the 'Template' solution. The startup project should be set to 'LabClientHtml'. Open
the 'Properties' page for the 'LabClientHtml' project and select the 'Web' tab.
The 'Start Action' should have 'Specific Page' selected with the entry
Check that the 'Active solution configuration' is set to 'Debug' and not 'Release'. This can be checked by selecting 'Build->Configuration Manager...' from the menu. Compile the solution. It should compile without any errors or warnings. Don't run the solution yet because there are a couple of things that need to be done first.
In the folder './Template/LabClientHtml', copy 'Web.config.template' to 'Web.config' and update the following keys:
In the folder './Template/LabLabServer', copy 'Web.config.template' to 'Web.config' and update the following keys:
In the folder './Template/LabEquipment', copy 'Web.config.template' to 'Web.config' and update the following keys:
The 'Web.config' file has already been supplied and does not need to be changed. 'DummyServiceBroker' is only used during development and does not get 'Published' in the 'Release' version.
There is no need to compile the solution after making changes to the configuration files. But let's not jump in and press 'F5' just yet. We need to run up the solution in an orderly fashion.
We need to check that this one runs ok. Open the 'Properties' page for the 'LabEquipment' project and select the 'Web' tab. Check that 'Start Action' is set to 'Specific Page' with the entry 'EquipmentService.asmx'. Now, right-click the 'LabEquipment' project in 'Solution Explorer' and select 'Debug->Start new instance' from the popup menu. If all goes well, you should be presented with the 'EquipmentService' webpage showing the operation 'ExecuteCommand'.
Click on 'ExecuteCommand' to run the operation. A 'Test' webpage appears where a command and several parameters can be entered. Enter the command 'Online' and enter '0' (zero) for each of the parameters and then click the 'Invoke' button. You should be presented with another webpage containing some information in XML format. If you get the error message 'Access Denied!' then close the web browser and edit the 'Web.config' file for the 'LabEquipment' project. Set the 'AuthenticateCaller' key value to 'false' and then save and close the 'Web.config' file. Run the procedure above again. If 'boolValue' is 'false' and there is no error message then the LabEquipment might still be initialising. Wait a bit and invoke the operation again. 'boolValue' should become 'true'.
Let's check the log file to see what was going on. Open the file './LabEquipment/LogFiles/YYYYMMDD.log' where 'YYYY' is the year, 'MM' is the month and 'DD' is the day that the logile was created. The logfile contains a lot of stuff but gives the developer some idea of what's going on. If things didn't didn't run as expected, check the logfile to find a possible cause.
We now need to check that this one runs ok. Open the 'Properties' page for the 'LabServer' project and select the 'Web' tab. Check that 'Start Action' is set to 'Specific Page' with the entry 'LabServerWebService.asmx'. Now, right-click the 'LabServer' project in 'Solution Explorer' and select 'Debug->Start new instance' from the popup menu. If all goes well, you should be presented with the 'LabServerWebService' webpage showing several operations including 'GetLabStatus'.
Click on 'GetLabStatus' to run the operation. A 'Test' webpage appears. No parameters can be entered for 'GetLabStatus' because it doesn't take any. Click the 'Invoke' button. You should be presented with another webpage containing some information in XML format. If you get the lab status message 'Access Denied!' then close the web browser and edit the 'Web.config' file for the 'LabServer' project. Set the 'AuthenticateCaller' key value to 'false' and then save and close the 'Web.config' file. Run the procedure above again. This time, 'online' should be 'true' and 'labStatusMessage' should be contain the string 'Ready'.
Check the log file for the 'LabServer' project to see what was going on. Open the file './LabServer/LogFiles/YYYYMMDD.log' just like you did for the 'LabEquipment' project. If things didn't didn't run as expected, check the logfile to find a possible cause.
Finally, we now need to check that this one runs ok. Open the 'Properties' page for the 'LabClientHtml' project and select the 'Web' tab. Check that 'Start Action' is set to 'Specific Page' with the entry 'LabClient.aspx?couponID=12345&passkey=100453924900132'. Now, either press 'F5' or right-click the 'LabClientHtml' project in 'Solution Explorer' and select 'Debug->Start new instance' from the popup menu. If all goes well, you should be presented with a webpage displaying the title 'Template', an image showing some resistors on a circuit board and a navigation menu.
Check the log file for the 'LabClientHtml' project to see what was going on. Open the file './LabClientHtml/LogFiles/YYYYMMDD.log' just like you did for the 'LabServer' project. If things didn't didn't run as expected, check the logfile to find a possible cause.
In the navigation menu, click 'Status'. The 'LabServer' should be 'Online' and 'Ready' with '0 experiments queued'.
In the navigation menu, click 'Setup'. There are two setups provided, one for driving the equipment and one for driving the simulation. These have almost no functionality but are privided as an example to work with. For each setup, click the 'Validate' button to validate the experiment specification for each setup. An estimated execution time will be indicated in the message.
Select the setup 'Setup for Equipment' and click the 'Submit' button to submit an experiment specification to the LabServer for processing. Then go to the 'Status' webpage to check the status of the experiment just submitted. The experiment number should be displayed so click the 'Check' button. A message will be displayed indicating the staus of the experiment.
When the experiment completes, navigate to the 'Results' webpage. The experiment number should be displayed so click the 'Retrieve' button. Information about the experiment should be displayed. The experiment results can be saved to a CSV file by clicking the 'Save' button.
In the descriptions that follow, references will be made to comments inserted in the code. These comments are either:
//
// YOUR CODE HERE
//
or
//
// YOUR CODE BETWEEN HERE ...
// ... AND HERE.
//
This makes it a bit easier to know where to change or add code.
There are four files here that need to be changed:
This is only a simple example of a hardware driver that drives 'pretend' hardware. Thow it away and add your own drivers or use this as a starting point for something.
This creates an instance of the hardware driver. There may be multiple hardware drivers depending on the equipment being used. The equipment may need to be powered down when not in use.
This web service processes the commands being received from the LabServer and calls upon the hardware drivers to carry out operations according to those commands.
Add extra keys as required for the Hardware drivers.
There are three files here that need to be changed:
This file contains the information required by the LabClient to display information on the 'Setup' webpage and populate the controls.
The LabClient may want to display various versions of an experiment ('Experiment Setup') that the user can choose from. The 'Configuration' element contains a list of the setups to display. Each setup has an 'id', 'name' and 'description'. The 'id' is used by both the LabServer and LabClient to determine what operations to perform. The 'name' and 'description' elements are displayed in fields in the 'Setup' webpage.
The 'Configuration' element may contain elements with information common to all listed setups.
An empty XML Validation element is provided so that the LabServer can determine if information in the experiment specification is valid.
An empty XML Specification element is provided so that the LabClient can fill in information and send it to the LabServer.
An empty ExperimentResults element is provided so that the LabServer can fill in information and send it to the LabClient.
Add extra keys as required for the Setup and Equipment Drivers.
This project contains the functionality specific to a LabServer. There are several files here that need to be changed:
Takes information from the 'Configuration' element of 'LabConfiguration.xml' and places it in private variables that can be accessed through 'Properties'. This is information is not the setups. The setups are already handled by the base class in 'LibraryLabServerEngine.LabConfiguration'.
String constants and XML string constants are placed here in one place. It makes them easier to find and helps to eliminate typing errors by using 'constants' instead of 'strings'.
This creates an instance of the driver for the specified setup that will execute the experiment.
Information is taken from the Specification and ResultInfo structure and placed in the XML ExperimentResult node which is then saved to local disk storage. This information is available for retrieval by the ServiceBroker.
Takes information from the XML Specification string and places it in private variables that can be accessed through 'Properties'. This information is then checked for validity. If the specification is valid, an instance of the driver for the specified setup is created to obtain the estimated execution time.
The 'ResultInfo' structure that contains the information that will be placed in the XML ExperimentResult node.
May or may not be used, depending on the experiment. Boundary conditions such as 'Minimum' and 'Maximum' values are checked here.
DO NOT EDIT. This file is auto-generated. It provides the interface to the LabEquipment web service. There is a batch file called 'MakeProxy.bat' that is run from a command prompt window to generate this file.
To generate this file, first run the LabEquipment web service. Then open a command prompt window and navigate to './Template/LibraryLabServer/Drivers/Equipment'. Run 'MakeProxy.bat' to generate 'EquipmentServiceProxy.cs'. When this file is generated successfully, the solution will need to be rebuilt.
This file will need be generated again each time any changes are made to the LabEquipment web service.
This is only a simple example of a driver that does not communicate with a LabEquipment web service. Instead of running a simulation, the driver could communicate with equipment over a network connection.
This drives the experiment for a particular 'setup' which makes calls to a LabEquipment web service.
This drives the experiment for a particular 'setup' which does not makes calls to a LabEquipment service.
There are several files here that need to be changed:
XML string constants and string constants are placed here in one place. It makes them easier to find.
Used by 'LabResults.ascx.cs', 'LabSetup.ascx.cs' and 'Result.cs'.
Obtains the experiment specification and result information strings that are used by 'Results.ascx.cs' to display information on the 'Results' webpage.
This file contains the HTML markup that provides the entry of the experiment specification. Uses the styles in 'LabControls.css'.
Add code to populate and update the webpage controls. The 'BuildSpecification' method takes information from the controls and places it in the XML specification node that is used by 'Setup.ascx.cs'.
Takes the information from the XML ExperimentResult node and places it into a 'ResultInfo' structure where it can be accessed by 'LabResults.ascx.cs'.
The 'ResultInfo' structure that contains the information taken from the XML ExperimentResult node.