Overview

Apache Stonehenge .NET StockTrader is a fork of Microsoft's .NET StockTrader Sample Application available on MSDN. It is one of many implementations of the Stonehenge StockTrader Sample Application. This document is designed to serve as a guide for installing the Apache Stonehenge .NET StockTrader sample application. It assumes an audience of experienced developers with at least limited conceptual knowledge of SOA, WCF, and the C# language.

Minimum System Requirements

Prerequisites

The following components are required for the Apache Stonehenge .NET StockTrader Sample Application to properly function.

• Microsoft SQL Server 2008 with mixed mode authentication enabled
• Microsoft .NET Framework 3.5 with Service Pack 1
• Microsoft Visual Studio 2008 or Visual Web Developer Express 2008
• Windows HTTP Services Certificate Configuration Tool
• Geneva Framework SDK
• MySQL Connector/Net

Installing the Microsoft Web Platform

The Microsoft Web Platform Installer is a tool created to install software and components necessary to develop and host web applications in a Microsoft Windows environment. It will be used in this guide to install most of the prerequisite requirements for the Stonehenge StockTrader Sample Application.

This process will install the following prerequisite components:

• Internet Information Services (IIS)
• Microsoft .NET Framework 3.5 with Service Pack 1
• Microsoft SQL Server 2008 Express Edition
• Visual Web Developer Express 2008

To install the Microsoft Web Platform:

1. Download the latest version of the Microsoft Web Platform Installer.
2. Run the Web Platform Installer. This will open a wizard that allows you to select the products that you would like to install on your machine.
3. In the Web Platform Installer, select the Web Platform tab.
4. In the Web Server section, click the Customize link.
5. In the Application Development group, check the boxes next to the following items:
   • ASP.NET
   • .NET Extensibility
6. In the Common HTTP Features group, check all available boxes.
7. In the Health and Diagnostics group, check the boxes next to the following items:
   • HTTP Logging
   • Logging Tools
   • Request Monitor
   • Tracing

     Note

     These are not required, but may prove useful for troubleshooting purposes.

8. In the Management group, check the boxes next to the following items:
   • IIS Management Console
   • IIS Management Scripts and Tools
9. In the Security group, check all available boxes.
10. Click the Back to Web Platform link.
11. In the Frameworks and Runtimes section, click the Customize link.
12. In the .NET Framework group, check the boxes next to the following items:
    • ASP.NET
    • .NET Framework 3.5 SP1
13. Click the Back to Web Platform link.
14. In the Database section, click the Customize link.
15. In the SQL group, check the boxes next to the following items:
    • SQL Server Express 2008 with Service Pack 1
    • SQL Server 2008 Management Studio Express
    • SQL Server 2008 Management Objects

      Note

      If these options are not available for selection, make sure that your system meets the minimum requirements for SQL Server Express 2008.

16. Click the Back to Web Platform link.
17. In the Tools section, click the Customize link.
18. In the Developer Tools group, check the box next to Visual Web Developer 2008 Express with SP1.
19. Click the Back to Web Platform link.
20. Click the Install button.

    Note

    You will be presented with a license agreement for all of the products that you are installing.

21. Click I Accept to continue installation.

    Warning

    If you do not agree with the license terms, click I Decline. You will not be able to continue with installation if you do not agree to the license terms.

22. On the following page, configure the installation of SQL Server Express using the values shown in the table below:

    Setting	Value
    Authentication Mode	Mixed Mode Authentication (recommended for application development)
    Password	A strong memorable password

23. Click the Continue button.

    Note

    The Microsoft Web Platform Installer will begin to download and install the items that you have selected. You may be required to restart your computer for the installation to complete.

24. Once the installation completes, click the Finish button.
25. Click Exit to close the Microsoft Web Platform Installer.

Configuring an Existing Microsoft SQL Server Installation

To enable Mixed Mode Authentication and the sa account:

1. Open SQL Server 2008 Management Studio.
2. Connect to your SQL Server using Windows Authentication.
3. In Object Explorer, right-click the name of the server, and then click Properties.
4. On the Security tab, select SQL Server and Windows Authentication mode.

   Note

   This allows users that are controlled by Windows, and users that are only registered with SQL Server to be able to access resources managed by SQL Server.

5. Click the OK button, and confirm your choice in any prompts that may appear.
6. In Object Explorer, right-click the name of the server, click Restart, and then confirm your choice in any prompts that may appear.
7. In Object Explorer, expand the Security > Logins node.
8. Right-click on the sa login, and then click Properties.
9. On the Status tab, configure the settings using the values shown in the table below:

   Setting	Value
   Permission to connect to the database engine	Grant
   Login	Enabled

10. On the General tab, in the Password box, type a strong memorable password.
11. Type this same password in the Confirm Password box.
12. Click the OK button.

Installing the "Geneva" Framework SDK

Starting with the upcoming M2 Release, the Stonehenge StockTrader Sample Application includes support for claims-based security, and federated identity. Microsoft Code Name "Geneva" includes a framework for dealing with claims, and creating custom Secure Token Services. This framework is used heavily within the .NET implementation of the Stonehenge StockTrader Sample Application to provide the enhanced identity management capabilities that will be found in the M2 release.

To install Microsoft Code Name "Geneva" Framework SDK

1. In a web browser, navigate to http://msdn.microsoft.com/en-us/evalcenter/dd440951.aspx.
2. On the web site, click the Get Started Today button.
3. Log-in with your Live ID.
4. Click the Continue button to register for the download.
5. At the bottom of the page, click the Download button next to the file you desire. Use the table below to determine the appropriate download:

   File	Description
   GenevaFrameworkSDK.amd64.msi	Choose this if you have a machine with a 64-bit processor, and are running a 64-bit operating system.
   GenevaFrameworkSDK.x86.msi	Choose this if you have a machine with a 32-bit processor, or are running a 32-bit operating system.

6. Execute the file downloaded, and then step through the installation wizard.

Installing the Windows HTTP Services Certificate Configuration Tool

In order to configure permissions for the X.509 certificates used by the services that are components of the Stonehenge StockTrader Sample Application, the Windows HTTP Services Certificate Configuration Tool will need to be installed.

To install the Windows HTTP Services Certificate Configuration Tool

1. Download the Installer.
2. Execute the installation package downloaded.
3. Step through the installation wizard.

Installing MySQL Connector/Net

To install MqSQL Connector/Net:

1. In a web browser, navigate to http://dev.mysql.com/get/Downloads/Connector-Net/mysql-connector-net-6.1.2.zip/from/pick#mirrors.
2. Select a mirror from which to download the required files.
3. Extract, and run the .msi file inside the .zip file downloaded.
4. Step through the installation wizard.

Installing a Subversion Client

To manage group development, and multiple versions of files under development, the Apache Stonehenge project makes use of a source control management solution called Subversion. In order to access the latest source code, it will be necessary to download a Subversion client. For simplicity, later sections of this document will assume that you are using the TortoiseSVN Client software.

To install TortoiseSVN Client software:

1. Download either the 64-bit setup package or the 32-bit setup package.
2. Execute the installation package downloaded.
3. Step through the installation wizard.

Installing Apache Stonehenge StockTrader

This section of the document covers the actual installation of the Stonehenge StockTrader Sample Application. It requires that all of the prerequisite components already discussed have been installed and configured properly. If this is not the case, please first go through the previous sections of this document.

Preparing for Installation

To configure your firewall:

1. On the Windows Start menu, click Control Panel.
2. In Control Panel, in the Security section, click the Allow a program through Windows Firewall link.
3. On the Exceptions tab, click the Add port... button.
4. Configure an exception using the values shown in the table below:

   Name	Port	Protocol
   Configuration Service	7000	TCP

1. Using the same process, create exceptions using the values shown in the table below:

   Name	Port	Protocol
   Order Processing Service	8000	TCP
   Business Service	9000	TCP
   Active STS	9001	TCP

Installing the Trader Client Application

To download the latest source code:

1. Create a folder with a path similar to: *C:\StockTraderDemo*
2. In Windows Explorer, Navigate to the folder that you created.
3. Right-click the background of that folder, and then click SVN Checkout...

   Note

   This assumes that you have installed TortoiseSVN client as described in one of the preceeding sections. If you are using a different SVN client, observe the steps given, and replicate them as appropriate using your preferred client software.

4. In the Checkout dialog, configure the checkout using the values shown in the table below, and then click the OK button:

   Setting	Value
   URL of repository	https://svn.apache.org/repos/asf/incubator/stonehenge/trunk/stocktrader/dotnet/
   Checkout directory	C:\StockTraderDemo (or whichever path you used in the previous steps)
   Checkout Depth	Fully recursive
   Omit externals	Unchecked
   Revision	HEAD Revision

5. Once the checkout has completed, click the OK button.

To seed the database and create accounts:

1. Open the solution now located at C:\StockTraderDemo\setup_utilities\SetupActions\SetupActions.sln.
2. In Solution Explorer, double-click App.config

   Note

   When you compile this project, App.config will be renamed to SetupActions.exe.config and copied to the \bin\Debug\ folder under the solution's directory.

3. Update the value for the dbServer key to point to your SQL Server instance:

   <add key"dbServer" value="INSTANCE HERE" />
   

   Note

   If you are using SQL Server 2008 Standard Edition (as opposed to express) you can likely leave this setting as it is. If you are using SQL Server 2008 Express, you will likely need to update this path to COMPUTER_NAME\SQLExpress or simply .\SQLExpress if SQL Server Express is running locally.

4. If you checked out the solution to a directory other than C:\StockTraderDemo, then update the value for the installPath key:

   <add key"installPath" value="ALTERNATE PATH HERE" />
   

5. Update the value for the dbPassword key to match the password for the sa account in SQL Server:

   <add key"dbPassword" value="PASSWORD HERE" />
   

6. Press F5 to run the project.
7. Press any key once the SetupActions program has completed.

   Note

   If you receive any error messages here, they should be forwarded on to the development mailing list.

To update the database server name in the database:

1. On the Start menu, click All Programs > Microsoft SQL Server 2008 > SQL Server Management Studio
2. In the Connect to Server dialog, click the Connect button.
3. In Object Explorer, expand the Databases > StockTraderDB > Tables node.
4. Right-click the dbo.DBCONFIG table, and then click Edit Top 200 Rows.
5. In the MSSQL row, in the HOSTNAME column, type the instance name of your SQL Server instance, and then press Enter.

   Note

   If you are using SQL Server 2008 Standard Edition (as opposed to express) you can likely leave this setting as it is. If you are using SQL Server 2008 Express, you will likely need to update this path to COMPUTER_NAME\SQLExpress or simply .\SQLExpress if SQL Server Express is running locally.

6. Close Microsoft SQL Server Management Studio.

To configure database access for the configuration service:

1. Open the XML-based configuration file located at C:\StockTraderDemo\config_service\ConfigServiceConsoleHost\App.config
2. Update the value for the DBServer key to point to your SQL Server instance:

   <add key"DBServer" value="INSTANCE HERE" />
   

   Note

   If you are using SQL Server 2008 Standard Edition (as opposed to express) you can likely leave this setting as it is. If you are using SQL Server 2008 Express, you will likely need to update this path to COMPUTER_NAME\SQLExpress or simply .\SQLExpress if SQL Server Express is running locally.

3. Save, and then close the configuration file.

To configure database access for the Passive STS:

1. Open the XML-based configuration file located at C:\StockTraderDemo\identity_provider\PassiveSts\web.config
2. In the appSettings section under the configuration node, update the value for the SqlConnection key to point to your SQL Server instance:

   <add
       key="SqlConnection"
       value="server=INSTANCE HERE;initial catalog=StockTraderDB;User=trade;Password=yyy"
   />
   

   Note

   If you are using SQL Server 2008 Standard Edition (as opposed to express) you can likely leave this setting as it is. If you are using SQL Server 2008 Express, you will likely need to update this path to COMPUTER_NAME\SQLExpress or simply .\SQLExpress if SQL Server Express is running locally.

3. Save, and then close the configuration file.

To setup the StockTrader web sites in Internet Information Services (IIS):

1. On the Windows Start menu, click Control Panel.
2. Click the Classic View link, and then double click Administrative Tools.
3. Double-click Internet Information Services (IIS) Manager.
4. In the left pane, expand the COMPUTER_NAME > Sites node.
5. Right-click Default Web Site, and then click Add Application...
6. Configure the application using the values shown in the table below, and then click OK:

   Setting	Value
   Alias	trade
   Physical path	C:\StockTraderDemo\trader_client\Trade

7. Right-click Default Web Site, and then click Add Application...
8. Configure the application using the values shown in the table below, and then click OK:

   Setting	Value
   Alias	trade_identity
   Physical path	C:\StockTraderDemo\identity_provider\PassiveSts

To install the test certificates:

1. Click the Start menu, and then type mmc.
2. Press the Enter key to launch Microsoft Management Console.
3. On the File menu, click Add/Remove Snap-in...
4. In the Available snap-ins list, click Certificates, and then click the Add > button.
5. In the Certificates snap-in dialog, click Computer account, and then click the Next > button.
6. In the Select Computer dialog, click the Finish button.
7. In the Add or Remove Snap-ins dialog, click the OK button to close the dialog.
8. In the Console Root, expand the Certificates (Local Computer) node.
9. Right-click the Personal node, and then click All Tasks > Import...
10. On the Welcome page of the Certificate Import Wizard, click the Next > button.
11. On the File to Import page, click the Browse... button.
12. Browse to and select C:\StockTraderDemo\setup_utilities\Util\stocktraderpfxfile.pfx.

    Note

    In the file filter list, you will have to select Personal Information Exchange (*.pfx;*.p12)

13. On the File to Import page, click the Next > button.

14. In the Password box, type yyy, and then check the box next to Mark this key as exportable [...].

15. On the Password page, click the Next > button.
16. Click Next > on any remaining pages, and then click the Finish button on the final page.
17. Click the OK button in the success message that appears.
18. In the left pane of Microsoft Management Console, expand the Personal node and click on Certificates.
19. In the center pane, right-click Trade.com and click All Tasks > Manage Private Keys...
20. In the Permissions for Trade.com private keys dialog, click the Add... button.
21. In the Enter object names to select box, type the name of the account that is the application pool identity for the StockTrader site that you set up in IIS, and then click the OK button.

    Note

    If nothing has been modified from defaults, you should type Network Service.

22. In the Group or user names list, click the account you added, and then in the Permissions for ACCOUNT NAME HERE list, check the Allow box next to Full control.
23. In the Permissions for Trade.com private keys dialog, click the OK button.
24. Leave Microsoft Management Console open, and then repeat the same import process for the following certificates:

    Certificate Name	Certificate Path
    OPS.Com	C:\StockTraderDemo\setup_utilities\Util\OPSHost.pfx
    BSL.Com	C:\StockTraderDemo\setup_utilities\Util\BSLClient.pfx

25. In the center pane of Microsoft Management Console, select the three certificates imported.

    Note

    If there are any certificates in between them, you will have to click each one individually, while holding down the Ctrl key to select all of them at once.

26. On the Action menu, click Copy.
27. In the left pane, right-click on the Trusted People node, and then click Paste.

To allow WCF services access to required resources:

1. In Windows Explorer open the folder C:\StockTraderDemo\setup_utilities\Util
2. Right-click AuthorizeWcfServices.bat, and then click Run as administrator.
3. At the command prompt, type 1.
4. Press Enter at the command prompt when execution is complete.

To compile the StockTrader application:

1. Execute the script C:\StockTraderDemo\BuildDotNet.cmd.
2. In Visual Web Developer 2008 Express or Visual Studio 2008, open the file C:\StockTraderDemo\trader_client\StockTraderWebAppSolution.sln.
3. On the Build menu, click Build Solution.

Running the StockTrader sample application

To run the sample application:

1. Execute the script C:\StockTraderDemo\RunServices.bat.
2. At the command prompt, type 1.
3. In a web browser, access http://localhost/trade

Configuring Apache Stonehenge StockTrader

To configure the StockTrader application:

1. In a web browser, access http://localhost/trade.
2. In the toolbar, click the Config button.
3. On the Configuration page, in the Business Service list, select the Business Service endpoint that you wish to use.

   Note

   If you do not see the endpoint that you wish to use already included in these lists, use the Advanced Configuration option to create endpoint configurations of your choosing.

4. In the Order Processing Service list, select the Order Processing Service endpoint that you wish to use.
5. Click the Set button to save the configuration.

Examining Available Utilities

Inside the setup_utilities/Util folder, you will find a number of different scripts. For more information about these scripts see the .NET Utilities List.