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 Web Developer Express 2008 or higher
• Windows HTTP Services Certificate Configuration Tool
• Windows Identity Foundation
• 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 2010

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 2010 Express.
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 Microsoft SQL Server Installation

To configure the Microsoft SQL Server installation, follow the instructions in the Configuring Microsoft SQL Server 2008 Express document in the Installing Common Prerequisites section of this wiki.

Installing Windows Identity Foundation

Starting with the upcoming M2 Release, the Stonehenge StockTrader Sample Application includes support for claims-based security, and federated identity. Windows Identity Foundation 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 Windows Identity Foundation

1. In a web browser, navigate to http://www.microsoft.com/downloads/details.aspx?FamilyID=eb9c345f-e830-40b8-a5fe-ae7a864c4d76.
2. 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
   Windows6.1-KB974405-x64.msu	Choose this if you have a machine with a 64-bit processor, and are running a 64-bit version of Windows 7, or Windows Server 2008 R2.
   Windows6.1-KB974405-x86.msu	Choose this if you have a machine with a 32-bit processor, or are running a 32-bit version of Windows 7.
   Windows6.0-KB974405-x64.msu	Choose this if you have a machine with a 64-bit processor, and are running a 64-bit version of Windows Vista, or Windows Server 2008.
   Windows6.0-KB974405-x86.msu	Choose this if you have a machine with a 32-bit processor, or are running a 32-bit version of Windows Vista, or Windows Server 2008.

   Warning

   If these update packages report that they do not apply to your system, verify that your operating system meets the minimum requirements stated at the beginning of this page. If you are using Windows Vista, or Windows Server 2008, ensure that you have already applied Service Pack 2.

3. 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 install a Subversion client, follow the instructions in the Installing a Subversion Client document in the Installing Common Prerequisites section of this wiki.

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.

   Note

   In Windows 7, port exceptions are added through Windows Firewall with Advanced Security

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 initialize the database and create accounts:

1. Follow the instructions in the Preparing the StockTrader Database document in the Installing Common Prerequisites section of this wiki.

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.
28. At a command prompt, type and execute the following command to associate the OPSHost.pfx certificate in the personal store with the port 8005 to enable https for the Order Processor:

    netsh http add sslcert ipport=0.0.0.0:8005 certhash=fa0f58bb605fa43369e279e8f9088872fde09943 appid={C0C21DB2-6E94-4538-8A5E-C5AEBE6E3F8B} 
    

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.

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.