Walkthrough: Debugging a Durable Session Client on a Windows HPC 2008 R2 Cluster

This walkthrough describes how to configure, launch, and debug a sample service-oriented architecture (SOA) project on a Windows HPC 2008 R2 cluster. This walkthrough helps you understand the elements of the Durable Session template and how to connect and configure the service and the client. It also describes how to use the debugger.

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

This guide includes the following sections:

• Step 1: Create a new WCF Service Library project in Visual Studio

• Step 2: Add a Durable Session Client project to the solution

• Step 3: Configure the Cluster-SOA Debugger

• Step 4: Set breakpoints in your code and then launch the Cluster-SOA Debugger

• Additional considerations

Step 1: Create a new WCF Service Library project in Visual Studio

The following procedure describes how to create a new Windows Communication Foundation (WCF) service named “SampleServiceLib” in a new solution named “ClusterSOASample”. For the purpose of this walkthrough, you use the default service code. The default service accepts and integer and returns a string.

The following procedure includes a step to configure the service library properties so that the local WCF Service Host does not host the service when you start debugging. For cluster debugging, the service is hosted on the compute nodes.

To create a WCF Service Library

1. Run Visual Studio 2008 as an Administrator.

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, expand Visual C# and then select WCF.

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

   3. In Name, type SampleServiceLib.

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

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

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

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

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

Step 2: Add a Durable Session Client project to the solution

The following procedure adds a new Durable Session Client project to the ClusterSOASample solution that you created. When you create an HPC Cluster-SOA Project, a series of dialog boxes appear to specify a head node and add a service reference to the client 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 steps to set two advanced options for the service reference:

• Generate asynchronous operations. This option generates methods such as BeginGetData and EndGetData in the resulting WCF client object.

• Always generate message contracts. This option implements the GetDataRequest and GetDataResponse data types for the BrokerClient object.

To create a Durable Session Client project

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

2. In the Add New Project dialog box:

   1. In Project Types, expand Visual C#, and then select HPC Cluster-SOA Project.

   2. In the list of templates, select Durable Session Client.

   3. In Name, type SampleDurableSessionClient.

   4. Click OK.

3. In the dialog box that appears, specify the name of the head node, and then click OK. (It might take a moment to populate the drop down menu with available head nodes on your network.)

4. In the next dialog box that appears, you can specify where the service reference comes from. In this case, select the From solution radio button, and then click OK.

5. The Add Service Reference dialog box appears. 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. Under Data Type, select the Always generate message contracts check box.

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

6. In Solution Explorer, right-click SampleDurableSessionClient and then click Set as StartUp Project. (In Solution Explorer, the name of the project that is set as the start-up project appears in bold.)

7. Verify that the Program.cs file for SampleDurableSessionClient includes the following:

   • Your service reference in the using statements (in this case, using Client.SampleServiceRef;).

   • Your head node in the schedulerName variable.

   • Your service interface to create the instance of the client object in the send request block and in the get responses block (in this case, the interface for SampleServiceLib is named IService1).

8. In Program.cs, in the serviceName variable, replace $SoaServiceName$ with SampleServiceLib.

9. In File, click Save.

Your Program.cs file in SampleDurableSessionClient will look similar to this:

Step 3: Configure 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.

The following procedure describes how to configure and launch the Cluster-SOA Debugger for SampleDurableSessionClient.

To configure the Cluster-SOA Debugger

1. In Solution Explorer, right-click SampleDurableSessionClient, 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 Debug Mode, select Services on all nodes.

5. In Select services to debug, select SampleServiceLib.

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

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

8. In File, click Save.

The Cluster-SOA Debug properties will look similar to this:

Step 4: Set breakpoints in your code and then launch the Cluster-SOA Debugger

In a durable session, the broker node does not start processing requests until the BrokerClient.EndRequests() method is called. EndRequets() confirms that all messages have been sent and ends the enumerator for the responses. In durable sessions, this call signals that the broker node should start processing requests.

To set breakpoints and launch the Cluster-SOA Debugger

1. In SampleDurableSessionClient, in Program.cs, set a breakpoint in following lines of code:

   client.SendRequest<GetDataRequest>(new Client.SampleServiceRef.GetDataRequest(), 0);

   and

   foreach (BrokerResponse<GetDataResponse> response in client.GetResponses<GetDataResponse>())

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

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

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

3. Press F5 to launch the debugger.

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

5. When the application pauses at the first breakpoint, open the Locals and the Processes windows. (During debugging, you can click the Debug menu, and then click Windows, and then click Locals or Processes to open the windows.)

   Notice the following:

   • After you complete the line of code session=session.Id, you will be able to see the assigned session ID in the Locals window. This corresponds to the Job ID of the job that is running your session on the cluster.

   • In the Processes window, you will see the remote debugger instances running on the specified compute nodes (in this walkthrough, you specified All Nodes).

   For example, in the following screenshot, you can see in the Locals window that the session ID is 414. In the Processes window, you can see that the client is running on the head node (because Visual Studio is running on the head node), and that an instance of the remote debugger is running on each core of the allocated nodes (DEV1, DEV2, and DEV4).

   

6. Press F10 (Step Over) to step through the code. Remember that the service does not start processing the requests until after client.EndRequests(). After that method call, the application pauses at the breakpoint that you set in the service code. In the Processes window, you can see what compute node you stepped into by looking in the Transport Qualifier column.

   For example, in the following screenshot, you can see that the application paused in the service code, and that the service request went to a compute node named DEV1. In this example, the client only sends one service request, so only one core is being used. The other remote debugger instances have timed out and are no longer present in the Processes window. You can step through individual processes by clicking the stepping buttons in the Processes window.

   

Additional considerations

Build behavior

By default, the Cluster-SOA debugger recompiles the entire solution before debugging. In some cases, you might not want to recompile every time you launch the debugger (for example, if you have a very large solution or if you select an external assembly as the service to debug and no project assemblies are included). To exclude projects from the build:

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

2. Under Configuration Properties, click Configuration.

3. For each project that you want to exclude from the build, clear the check box in the Build column, and then click OK.

Session timeouts

A session may timeout while a debugging session is active if the session is idle for more than five minutes. If the SOA session associated with the debugger experiences a timeout event the session must be terminated and restarted to continue debugging. To avoid this situation, the session timeout time limit can be set in the client code by using the SessionStartInfo.BrokerSettingsInfo.ClientIdleTimeout Property (in milliseconds). For example, the following code sets the timeout limit to 10 minutes. Adjust the time as appropriate for your debugging needs. Note the info object must be used as an argument to Session.CreateSession for the settings to take effect:

SessionStartInfo info = new SessionStartInfo(schedulerName, serviceName);  
info.BrokerSettings.ClientIdleTimeout = 10 * 60 * 1000;