[[PageOutline]]
= 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 ===
Your Windows user 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 your user:
 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 [attachment:FindPrivateKey.exe 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 your user (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. [attachment:"HeuristicLabServicesDemo.zip" 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`.

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