How to ... Develop HeuristicLab Services

This guide describes how to set up an environment for developing HeuristicLab services. Execute the following steps and you will be able to develop and test services and client applications locally on your machine. Please note that these steps are not sufficient for production use. If you want to set up a production system for hosting your services, some additional steps (especially concerning permissions and certificate creation) are necessary. However, if you develop your services and client applications locally as described below, they can be easily hosted on one of the HeuristicLab production servers (such as services.heuristiclab.com for example).

Software Requirements

Before starting to develop your own HeuristicLab services, you should have the following software installed on your machine:

• Microsoft Visual Studio 2010
• Microsoft SQL Server 2008 Express (usually automatically installed by Visual Studio)

Environment Setup

1. Create Database for Users and Roles

You have to add a database named HeuristicLab.Authentication to your local SQL Server instance which stores users, roles, etc.:

1. Start the Visual Studio Command Prompt which is automatically installed and added to your programs by Visual Studio.
2. Execute the following command which creates the HeuristicLab.Authentication database and adds all required tables, views, etc.:

   aspnet_regsql.exe -C "data source=.\SQLEXPRESS;Integrated Security=SSPI" -A all -d HeuristicLab.Authentication
   

3. Optionally you can start the SQL Server Management Studio or create a new data connection in Visual Studio to check, if the database is really there.

This database is usually used by HeuristicLab services for authentication and authorization. The two classes System.Web.Security.SqlMembershipProvider and System.Web.Security.SqlRoleProvider are used to access this database and to read and write users or roles. Usually there should be no need to access the database directly and you should not have to worry about its data model.

2. Create a Self-Signed Certificate

For encrypting the service communication, a certificate has to be created for your machine:

1. Start the Visual Studio Command Prompt again and run it with Administrator privileges (choose Run as administrator in the context menu).
2. Execute the following command which creates a new self-signed certificate named localhost and adds it to the Personal category of the LocalMachine certificate store:

   makecert.exe -r -pe -sky exchange -sr LocalMachine -ss My -n CN=localhost
   

3. Optionally you can start the Microsoft Management Console (mmc.exe) to check, if the certificate is really there (choose File -> Add/Remove Snap-in to add the Certificates snap-in and to explore the content of the LocalMachine certificate store).

3. Allow Read Access to the Certificate's Private Key

Network services must have read access to the private key of the certificate created in the previous step. Therefore, you have to locate the private key file on your hard disk first and then you have to grant read access to it for the Network Service account of your machine:

1. Start the Visual Studio Command Prompt again and run it with Administrator privileges (choose Run as administrator in the context menu).
2. Execute the following command (please note that the console application findprivatekey.exe is attached to this page​, if you do not have it on your system):

   findprivatekey.exe My LocalMachine -n CN=localhost
   

3. Have a look at the output. It shows you the path and the filename of the private key and should look like this:

   C:\...>findprivatekey.exe My LocalMachine -n CN=localhost
   Private key directory:
   C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys
   Private key file name:
   fef2c81190d59a105313d83fb ... eb8c6a
   

4. Allow read access to this file for the Network Service account of your machine (in the context menu of the file choose Properties -> Security -> Edit -> Add).

Development

After you have successfully completed all the steps described above, you are ready to start developing your own services and client applications. Attached to this page​, you can find a Visual Studio 2010 solution file which contains two sample projects, one for a service (HeuristicLab.Services.DemoService) and one for a client (HeuristicLab.DemoClient). These projects are a good starting point for developing custom HeuristicLab services. But before you are able to execute these two sample projects, some additional steps are necessary:

1. Update Client Service Reference

As you have created a new server certificate, you have to update the service reference in the client project:

1. Open the HeuristicLabServicesDemo.sln solution file.
2. Update the service reference of the project HeuristicLab.DemoClient.
3. Add the attribute behaviorConfiguration="DefaultEndpointBehavior" to the endpoint specification of the client section in the app.config file of the client project (please note that updating the service reference of the client overwrites the whole client section each time; therefore adding the behavior configuration has to be done everytime after updating the service reference). The client section should look like this:

   <client>
     <endpoint address="http://localhost:34825/Service.svc" binding="wsHttpBinding" behaviorConfiguration="DefaultEndpointBehavior"
               bindingConfiguration="WSHttpBinding_IService" contract="Services.DemoService.IService"
               name="WSHttpBinding_IService">
       <identity>
         <certificate encodedValue="AwAAAAEAAAAUAAAA ... B+3eQE6Y8inFygk=" />
       </identity>
     </endpoint>
   </client>
   

2. Create Users and Roles

You also have to add some users and roles for testing purposes. Users and roles can be administered using the ASP.NET Web Site Administration Tool which can be started in the solution explorer after clicking on the service project (have a close look at the tool bar of the solution explorer). Please note that the administration tool will not work, if the path of the service project contains any spaces or special characters. Both sample projects require that there is a user called Alice who is member of the role Everyone and whose password is YouWillNeverKnow.

3. Run the Services Demo

Now you should be able to execute the two projects contained in the services demo solution. Yes? It works? Great. Congratulations.