Walkthrough: Debugging an Interactive SOA Application on a Windows HPC 2008 Cluster

This walkthrough describes how to configure, launch, and debug a sample service-oriented architecture (SOA) project on a Windows HPC Server 2008 cluster. This walkthrough helps you understand the elements of the HPC Cluster-SOA template and how to connect and configure the service and the client. It also describes how to use the debugger to follow a request from the client code to an instance of your service that is running on the cluster, then back to the client.

Before following the steps in this walkthrough, ensure that you have the required software, software updates, and system configurations as listed in Requirements for Using the C# Cluster-SOA Debugger for Windows HPC 2008.

This guide includes the following steps:

• Step 1: Create a new Cluster-SOA client project in Visual Studio

• Step 2: Add a new WCF service to the solution

• Step 3: Add the service reference to the client project

• Step 4: Specify the head node and the WCF client proxy in the client code

• Step 5: Add the service contract name to the configuration file for the client application

• Step 6: Modify the configuration file for the WCF service project

• Step 7: Configure the WCF service library properties

• Step 8: Set breakpoints in the client code and the service code

• Configure and launch the Cluster-SOA Debugger

Step 1: Create a new Cluster-SOA client project in Visual Studio

The following procedure describes how to create a new project named “SampleClientApp” by using the HPC Cluster-SOA Project template. The project is part of a new solution named “ClusterSOASample.”

To create a Cluster-SOA client project

1. Run Visual Studio 2008.

2. Click File, point to New, and then click Project.

3. Provide the following information in the New Project dialog box:

   1. In Project Types, select Visual C#.

   2. In the list of templates, select HPC Cluster-SOA Project.

   3. In Name, type SampleClientApp.

   4. In Solution name, type ClusterSOASample.

   5. Click OK to create the project and close the dialog box.

4. In Solution Explorer, verify that your solution contains one project named SampleClientApp.

   The Program.cs file contains the outline of the client code. You modify the client code in Step 4 of the walkthrough.

Step 2: Add a new WCF service to the solution

The following procedure adds a new Windows Communication Foundation (WCF) service to the ClusterSOASample solution that you created. For the purpose of this walkthrough, you use the default service code. The default service accepts and integer and returns a string.

The procedure includes a step to build the service library project. When you build the project, the SampleServiceLib.dll and SampleServiceLib.dll.config files are generated in the bin\Debug folder for the project.

To create and build a new WCF service

1. With your ClusterSOASample.sln open in Visual Studio, click File, point to Add, then click New Project.

2. In the Add New Project dialog box:

   1. In Project Types, expand Visual C#, then select WCF.

   2. In the list of templates, select WCF Service Library.

   3. In Name, type SampleServiceLib.

   4. Click OK.

3. In Solution Explorer, verify that the ClusterSOASample solution includes two projects: SampleClientApp and SampleServiceLib.

4. In Solution Explorer, right-click SampleServiceLib, and then click Build.

Step 3: Add the service reference to the client project

The following procedure describes how to add a service reference to the SampleClientApp project. When you add a service reference to a project in Visual Studio, the WCF client objects (client proxies) are created automatically. This procedure includes a step to generate asynchronous operations (such as BeginGetData and EndGetData) in the resulting WCF client object.

To add the service reference

1. In Solution Explorer, right-click SampleClientApp, then click Add Service Reference.

2. In the Add Service Reference dialog box:

   1. Click the down arrow on the Discover button, and then click Services in Solution. After a few moments, a service URL appears under Address.

   2. Click Go to discover the service. Service1 appears under Services.

   3. In Namespace, type SampleServiceRef.

   4. Click Advanced to modify the service reference settings.

   5. In the Service Reference Settings dialog box, do the following:

      1. Under Client, select the Generate asynchronous operations check box.

      2. Click OK to accept the change and return to the Add Service Reference dialog box.

   6. Click OK to add the service reference and close the dialog box.

3. Verify the following:

   1. In Solution Explorer, under SampleClientApp, expand the Service References node to see the reference that you added.

   2. Right-click SampleServiceRef, and then click View in Object Browser.

   3. In Object Browser, expand the Client.SampleServiceRef namespace, and then click Service1Client to see the methods that are available in the WCF client object. In Step 4 of the walkthrough, you add this namespace to the using directives in the client code and then use the methods in Service1Client to invoke the service.

Step 4: Specify the head node and the WCF client proxy in the client code

This procedure describes how to modify the default client code in the Program.cs file that is included with the HPC Cluster-SOA Project template. You must modify the code to specify your cluster head node and to use the WCF client object that was generated when you added the service reference.

To specify the head node and the WCF client proxy in the client code

1. In Solution Explorer, under SampleClientApp, double-click Program.cs.

2. In the Program.cs code, at the end of the using directives, type the following to add a directive for the Client.SampleServiceRef namespace:

   using Client.SampleServiceRef;

3. In the Main function, the name of the head node and the name of the service are specified with the following code:

   public static void Main(string[] args)
   {
       // The name of the head node in the cluster.
       string schedulerName = "HeadNodeName";
       // The name of the debugee service.
       string serviceName = "SoaServiceName";
   

   Replace HeadNodeName with the name of your head node.

   Replace SoaServiceName with SampleServiceLib.

4. In the Main function, in the try block, an instance of the client object is created with the following statement:

   var client = new Client("HpcSoaDebuggingEndpoint", session.EndpointReference);

   Replace new Client with new Service1Client so that the statement appears as follows:

   var client = new Service1Client ("HpcSoaDebuggingEndpoint", session.EndpointReference);

5. Similarly, in the CallBack function, replace Client with Service1Client so that the first statement in the CallBack function appears as follows:

   private static void CallBack(IAsyncResult result)
   {
       // TODO: Replace following "Client" by your own service client.
       var client = result.AsyncState as Service1Client;
   

6. In File, click Save.

Step 5: Add the service contract name to the configuration file for the client application

The following procedure describes how to add the service contract name to the configuration file for the client application. In app.config, the first endpoint element defines the HPC SOA Debugging Endpoint. The contract attribute has a placeholder value of [Service_Contract_Name]. You must replace this with the service contract name. The service contract name generated automatically when you added the service reference. In this example, the service contract name is SampleServiceRef.IService1.

To add the service contract name to app.config

1. In Solution Explorer, under SampleClientApp, double-click app.config to open the configuration file.

2. In app.config, replace [Service_Contract_Name] with SampleServiceRef.IService1 so that the HPC SOA Debugging Endpoint attributes are defined as follows:

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <system.serviceModel>
   
       <client>
         <endpoint behaviorConfiguration="" binding="netTcpBinding" bindingConfiguration="HpcSoaDebuggingBinding"
           contract="SampleServiceRef.IService1" name="HpcSoaDebuggingEndpoint" />
   

3. In File, click Save, and then close app.config.

Step 6: Modify the configuration file for the WCF service project

The following procedure describes how to replace the App.config file in SampleServiceLib with app.config.TemplateForService.xml. This configuration file is included in the HPC Cluster-SOA Project template. The procedure includes steps for replacing placeholder values in app.config.TemplateForService.xml for the service name and the service contract name. The service name property corresponds to the namespace and class (Namespace.Class) of the service (SampleServiceLib.Service1). The contract corresponds to the namespace and public interface (Namespace.Interface) that is offered by the service (SampleServiceLib.IService1).

To modify the service configuration file

1. In Solution Explorer, under SampleClientApp, right-click app.config.TemplateForService.xml, and then click Copy.

2. Right-click SampleServiceLib, and then click Paste. A copy of app.config.TemplateForService.xml appears in the SampleServiceLib project.

3. Under SampleServiceLib, right-click App.config, click Rename, and then rename the file to App.config.old. If a dialog box appears, click Yes to confirm the change.

4. Under SampleServiceLib, right-click app.config.TemplateForService.xml, click Rename, and then rename the file to App.config.

5. Double-click App.config to open the file.

6. In App.config, replace [Service_Name] with SampleServiceLib.Service1, and replace [Service_Contract_Name] with SampleServiceLib.IService1 so that the service attributes are defined as follows:

   <services>
     <!--Replace following [Service_Name] by the real service name-->
     <service behaviorConfiguration="ServiceBehavior" name="SampleServiceLib.Service1">
   
       <!--Replace following [Service_Contract_Name] by the real service contract name-->
       <endpoint address="" binding="netTcpBinding" contract="SampleServiceLib.IService1"
         bindingConfiguration="HpcSoaDebuggingBinding" />
   
       <endpoint address="mex" behaviorConfiguration="" binding="mexHttpBinding"
         contract="IMetadataExchange" />
     </service>
   </services>
   

7. In File, click Save, and then close App.config.

Step 7: Configure the WCF service library properties

The following procedure describes how to configure the WCF service library properties for SampleServiceLib.

To configure the WCF service library properties

1. In Solution Explorer, right-click SampleServiceLib, and then click Properties.

2. In the properties page, click the WCF Options tab.

3. Clear the Start WCF Service Host when debugging another project in the same solution check box.

4. In File, click Save, and then close the properties page.

Step 8: Set breakpoints in the client code and the service code

To step through the code during debugging, you must set breakpoints in the code. All of the debugging modes in the Cluster-SOA Debugger require a breakpoint in the service code. To follow a request from the client to the service on the cluster, and then back to the client, you must also set breakpoints in the client before you invoke the service and in the callback method.

The following procedure describes how to set breakpoints when Session.CreateSession is called, in the CallBack method of the client, and in the GetData method of the service.

To set breakpoints in Program.cs and Service1.cs

1. In Solution Explorer, under SampleClientApp, double-click Program.cs to open the file.

2. In Program.cs, set a breakpoint in following line of code:

   using (Session session = Session.CreateSession(startInfo, 60 * 1000))

   To set a breakpoint, right-click the line of code, point to Breakpoint, then click Insert Breakpoint.

3. Set a breakpoint in the CallBack method in the following line of code:

   var client = result.AsyncState as Service1Client;

4. In Solution Explorer, under SampleServiceLib, double-click Service1.cs to open the file.

5. In Service1.cs, set a breakpoint in the GetData method in the following line of code:

   return string.Format("You entered: {0}", value);

6. In File, click Save All.

Configure and launch the Cluster-SOA Debugger

Before you launch the debugger, you must specify the head node and the service to debug in the Cluster-SOA Debugger properties. Optionally, you can configure additional properties for the debugging session. The Cluster-SOA Debugger properties that you set are saved as part of the project file. For more information about the configuration options and default values, see How to: Configure and Launch the Cluster-SOA Debugger.

The following procedure describes how to configure and launch the Cluster-SOA Debugger for SampleClientApp. The default Debug mode enables you to follow a request end-to-end, stopping at the breakpoints that you set in the client and in the service code.

To configure the Cluster-SOA Debugger

1. In Solution Explorer, right-click SampleClientApp, and then click Properties.

2. In the properties page, click the Cluster-SOA Debug tab.

3. In Select a head node, select the name of your head node from the drop-down list. This is the same head node that you specified in the client code.

4. In Select services to debug, select SampleServiceLib.

5. Optionally: In Deployment folder, specify the shared folder to use for staging deployment to the cluster.

6. Optionally: In Working directory on each compute node, specify the working directory to use on each compute node in the cluster.

7. In File, click Save.

To launch the Cluster-SOA Debugger and follow a request end-to-end

1. Press F5 to launch the debugger.

2. When prompted, type your password to connect to the cluster, and then click OK.

3. A Command Prompt window appears, and the application pauses at the first breakpoint in the statement to create the session.

4. Press F10 (Step Over) to step through the code.

5. If prompted, type your password in the Command Prompt window.

6. Continue pressing F10 until you reach the following line of code:

   client.BeginGetData(i, CallBack, client);

7. Press F11 (Step Into) to follow the request.

   Note

   Because this is an asynchronous operation, the debugger may not step immediately into the service process. You can press F5 (Continue) to continue to the breakpoint in the service.

8. The application stops at the breakpoint in the GetData method in the service code.

9. Press F11 again to follow the request to the CallBack function in the client code.

10. To stop debugging, in the Debug menu, click Stop Debugging.

See Also

Using the C# Cluster-SOA Debugger for Windows HPC 2008 (Visual Studio 2008)
Configuration Properties for the Cluster-SOA Debugger
HPC Cluster-SOA Client Template
How to: Configure and Launch the Cluster-SOA Debugger