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 HeuriticLab 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:

   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).