ReadmeHPC Square Service

Lab version: 1.0.0

Last updated: 5/23/2023

Contents

OVERVIEW................................................................................................................................................. 3

GETTING STARTED................................................................................................................................... 4Task 1 – Inspecting the WCF Service Project.......................................................................................4

Task 2 – Inspecting the WCF Service Configuration.............................................................................5

Task 3 – Inspecting the Client Configuration.......................................................................................6

Task 4 – Inspecting the Client Code for an Interactive Session............................................................7

Task 5 – Inspecting the Client Code for a Durable Session.................................................................10

DEPLOYMENT.......................................................................................................................................... 13Task 1 – Copying the WCF Service Configuration to the Head Node.................................................13

Task 2 – Deploying the WCF Service to On-Premises Nodes..............................................................13

Task 3 – Deploying the WCF Service to Windows Azure Nodes.........................................................15

RUNNING THE CLIENT............................................................................................................................ 16Task 1 – Verifying Cluster State.........................................................................................................16

Task 2 – Running the Client Application............................................................................................17

INSPECTING THE SERVICE OUTPUT....................................................................................................19Task 1 – Checking the Tasks’ Output Window...................................................................................19

Task 2 – Inspecting the Job’s Trace Files............................................................................................20

SUMMARY................................................................................................................................................ 23

Overview

The HPC Square service demonstrates how to build, deploy, and execute an HPC SOA application that can run in Windows Azure. This sample includes a WCF service project and a client application that consumes it.

The client application demonstrates the interactive and durable session modes of the HPC SOA application, which are used to call a WCF service that is deployed to the HPC cluster, whether it resides in an on-premises node or in a Windows Azure node. The client application also demonstrates how to use the interactive session with both a service reference generated proxy and the BrokerClient class.

Note: Though this sample was originally developed for Windows HPC Server 2008 R2 SP1, it has been verified to run under Windows HPC Server 2008 R2 SP2. The sample should preferably be run under Windows HPC Server 2008 R2 SP2.

Key Features

This sample demonstrates the following:

Creation of a WCF service and its configuration to run in an HPC cluster.

Deploying of the WCF service in the cluster (both on-premises and in Windows Azure).

Creation of a client HPC SOA application that calls the WCF service using the following session types:

◦ Interactive session

◦ Durable session

Sending of messages to the hosted WCF services using the following WCF client types:

◦ Service reference proxy (generated by the Add Service Reference tool)

◦ BrokerClient<T> generic class

Getting Started

To run this sample, you must install the HPC Pack 2008 R2 Client Utilities Redistributable Package with Service Pack 1 (or higher) and the HPC Pack 2008 R2 SDK with Service Pack 1 (or higher). In addition, you need to have administrative access to your HPC cluster’s head node and WCF broker node.

To run the WCF service in Windows Azure nodes, you must have a valid Windows Azure account, a Windows Azure worker node template defined in your head node, and several Windows Azure worker nodes in the HPC cluster that are started and online. See the Deploying Azure Worker Nodes in Windows HPC Server 2008 R2 SP1 Step-by-Step Guide on TechNet for further information.

Note: Although this solution is for Visual Studio 2010, the SquareService project uses .NET Framework 3.5; this is because currently the HPC cluster cannot host WCF services compiled for .NET Framework 4.

Task 1 – Inspecting the WCF Service Project

In this task, you will inspect the WCF service project to see the contract and implementation of the service.

1. Open Microsoft Visual Studio 2010 from Start | All Programs | Microsoft Visual Studio 2010 | Microsoft Visual Studio 2010.

2. Open the SquareService.sln solution file located in the SquareService\Source folder.

3. In the Solution Explorer window, expand the SquareService project node, as shown in Figure 1:

Figure 1The SquareService project

4. Open the ISquareService.cs file and inspect the service contract. The service contract contains only one method: the Square method.

5. Open the SquareService.cs file and inspect the contents of the service. The service implementation is a basic square calculation.

a. Note the Console.WriteLine method call. This call will output a message, which you will be able to see in the task results window in the HPC 2008 R2 Cluster Manager application.

b. Also note the ServiceContext.Logger.TraceEvent method calls. These method calls write debug information to a local trace file, which are collected after the job finishes running.

Task 2 – Inspecting the WCF Service Configuration

In this task, you will inspect the contents of the service’s configuration file. The service configuration file allows you to set how the HPC service host locates your service and hosts it. The configuration file also includes information on how to expose the service through the WCF broker node.

1. In the SquareService project, open the SquareService.config file. Look for the <microsoft.Hpc.Session.ServiceRegistration> XML element:

SquareService.config

<microsoft.Hpc.Session.ServiceRegistration> <service assembly="\\MyHeadNode\Apps\SquareService\SquareService.dll" contract="SquareServiceContracts.ISquareService" type="Services.SquareService" includeExceptionDetailInFaults="true" maxConcurrentCalls="0" serviceInitializationTimeout="60000" stdError="" maxMessageSize="65536"> </service></microsoft.Hpc.Session.ServiceRegistration>

2. The following attributes are required to configure how the service is hosted:

a. assembly. Defines the location of the service’s assembly file, which should contain both the service contract and the service implementation. Change the name of the head node machine to match yours.

b. contract. Defines the fully qualified name of the service contract.

c. type. Defines the fully qualified name of the service’s implementation class.

3. Inside the SquareService.config file, locate the <brokerServiceAddresses> XML element under the <microsoft.Hpc.Broker>\<services> element. Each of the <add> XML elements defines a base address that the WCF broker node uses to listen for client service requests.

4. Inside the SquareService.config file, locate the <system.serviceModel> XML element and inspect the contents of that element. This XML element contains the configuration for the

broker service’s message logging as well as the binding configuration for the endpoints exposed by the broker service.

Task 3 – Inspecting the Client Configuration

In this task, you will explore the client configuration used to create the new service job (also referred to as session).

1. In the Solution Explorer window, expand the Client project node.

Figure 2The Client project

2. In the Client project, open the app.config file and locate the <appSettings> XML element:

C#

<appSettings> <add key="HeadNodeName" value="MyHeadNode"/> <add key="SoaServiceName" value="SquareService"/> <add key="NodeGroup" value="AzureWorkerNodes"/></appSettings>

3. Set the HeadNodeName key to match your head node’s machine name. If you intend to test this sample with on-premises nodes in addition to Windows Azure nodes, change the name of the NodeGroup key to name of the required nodes group.

Note: There is no need to change the SoaServiceName key as this attribute is currently set to the name of the tested service, which is SquareService.

Task 4 – Inspecting the Client Code for an Interactive Session

In this task, you will examine the client code that creates an interactive session and then calls the hosted WCF service in the HPC cluster. Interactive sessions are service jobs that host WCF services in the HPC cluster, and allow interaction with the services through the WCF broker node that routes requests and responses from the client to the cluster and back.

1. In the Client project open the Program.cs file, and locate the CreateSessionAndCall method.

2. The CreateSessionAndCall method creates a new Microsoft.Hpc.Scheduler.Session.SessionStartInfo object and then sets its properties, as shown in the following code snippet:

C#

// The name of the head node in the cluster.string schedulerName = ConfigurationManager.AppSettings["HeadNodeName"];

// The name of the called service.string serviceName = ConfigurationManager.AppSettings["SoaServiceName"];

SessionStartInfo info = new SessionStartInfo(schedulerName, serviceName);

info.Secure = false;

info.NodeGroupList.Add( ConfigurationManager.AppSettings["NodeGroup"]);

Note: You can also set other properties of the SessionStartInfo object to configure how the job executes. For instance, you can set the SessionResourceUnitType property to SessionUnitType.Cores and then set the MinimumUnits and MaximumUnits to define how many cores will be available for each hosted service.

3. After setting the session start information, the CreateSessionAndCall method creates a new session object using the Microsoft.HPC.Scheduler.Session.Session class, and then calls a delegate that uses the session to send requests to the service, as shown in the following code snippet:

C#

using (Session session = Session.CreateSession(info)){ Console.WriteLine("Session ID: " + session.Id); serviceCallDelegate(session); Console.WriteLine("Done retrieving {0} responses\n", _numOfRequests); // Close connections and delete messages stored in the system session.Close();}

The Session class is responsible for creating a new job with a service task in the job scheduler. Once the session starts, the client application can send service requests to the WCF broker node that will route them to the available WCF services in the HPC cluster.

4. In order to call the WCF broker node, the CreateSessionAndCall method calls one of the following delegates:

Note: The CreateSessionAndCall method receives the delegate as a parameter from the program’s static Main method.

a. InteractiveUsingServiceReference. Calls the WCF broker node using the generated service reference proxy.

b. InteractiveUsingBrokerClient. Calls the WCF broker node using the BrokerClient<T> generic class.

5. In the Program.cs file, locate the InteractiveUsingServiceReference method and examine its contents. This method uses the service reference class created for the square service to call the service asynchronously and print out the responses returned by the service, as shown in the following code snippet:

C#

int count = 0;AutoResetEvent done = new AutoResetEvent(false); SquareServiceClient proxy = new SquareServiceClient( new NetTcpBinding(SecurityMode.None), session.NetTcpEndpointReference); proxy.SquareCompleted += (sender, e) => { try { int reply = e.Result.SquareResult; Console.WriteLine("Received response for request {0}: {1}", e.UserState, reply); } catch (SessionException ex) {

Console.WriteLine("SessionException while getting responses in callback {0}", ex.Message); } catch (Exception ex) { Console.WriteLine("Exception while getting responses in callback: {0}",ex.Message); } if (Interlocked.Increment(ref count) == _numOfRequests) { done.Set(); } }; // start to send requestsConsole.WriteLine("Sending {0} requests...", _numOfRequests);for (int i = 0; i < _numOfRequests; i++){ proxy.SquareAsync(new SquareRequest(1000 + i), i);} // Main thread block here waiting for the retrieval process// to complete. As the thread that receives the "_numOfRequests"// responses does a Set() on the event, "done.WaitOne()" will popdone.WaitOne();

Note: The client’s proxy uses NetTcpBinding with no security. If you change the proxy to use transport security, you will also need to change the SessionStartInfo.Secure property to true. You cannot use bindings other than the NetTcp binding.

6. Next, locate the InteractiveUsingBrokerClient method. This method works in a similar way as the previous method, only this time the BrokerClient<T> generic class is used to call the service.

Note: The generic argument T of the BrokerClient<T> class is the service’s contract type.

a. To register to the service request’s callback method, call the BrokerClient<T>.SetResponseHandler<TMessage> generic method, where TMessage is the type of the message class representing the response type of the called service operation, as shown in the following code snippet:

C#

client.SetResponseHandler<SquareResponse>((response) =>{ try { int reply = response.Result.SquareResult; Console.WriteLine( "Received response for request {0}: {1}", response.GetUserData<int>(), reply); } catch (SessionException ex) { Console.WriteLine( "SessionException while getting responses in callback: {0}", ex.Message); } catch (Exception ex) { Console.WriteLine( "Exception while getting responses in callback: {0}", ex.Message); } if (Interlocked.Increment(ref count) == _numOfRequests) { done.Set(); }});

Note: The message classes were created by the Add Service Reference tool in Visual Studio 2010 by checking the Always generate message contract checkbox in the Service Reference Settings window (accessible by clicking the Advanced… button in the Add Service Reference window).

b. To send a request to the service, you call the BrokerClient<T>.SendRequest<TMessage> generic method, where TMessage is the type of the message class containing the parameters required by the service operation, as shown in the following code snippet:

C#

// start to send requestsConsole.WriteLine("Sending {0} requests...", _numOfRequests);for (int i = 0; i < _numOfRequests; i++){ client.SendRequest<SquareRequest>(new SquareRequest(1000 + i), i);}

client.EndRequests();

Task 5 – Inspecting the Client Code for a Durable Session

In this task, you will examine the client code that creates a durable session, sends requests to the WCF service hosted in the HPC cluster, and then reconnects to the session to retrieve the responses returned by the hosted services. Durable sessions are different from interactive sessions by the fact that the WCF broker queues the responses the WCF service return, thus allowing clients to disconnect from the session after sending requests to the WCF broker node, and later on reconnect to the durable session and retrieve the responses.

1. In the Client project’s Program.cs file, locate the CreateDurableSessionAndCall method and examine its contents.

2. This method also uses the Microsoft.Hpc.Scheduler.Session.SessionStartInfo type to define how to start the session, but this time the session is a durable session, created by the Microsoft.Hpc.Scheduler.Session.DurableSession.CreateSession method, as shown in the following code snippet:

C#

using (DurableSession session = DurableSession.CreateSession(info)){ sessionId = session.Id; Console.WriteLine("Session ID: " + sessionId); serviceCallDelegate(session); Console.WriteLine("Done sending {0} requests", _numOfRequests);}

3. After creating the session and sending requests to the service, the session object is disposed, but the durable session keeps running in the job scheduler, collecting responses from the running services. To connect to the running session, the DurableSession.AttachSession method is called with an object of type Microsoft.Hpc.Scheduler.Session.SessionAttachInfo that contains the ID of the running durable session, as shown in the following code snippet:

C#

SessionAttachInfo attachInfo = new SessionAttachInfo(schedulerName, sessionId); Console.WriteLine("Attaching to session {0}...", sessionId);// Attach to an already running session using (DurableSession session = DurableSession.AttachSession(attachInfo)){ serviceReceiveDelegate(session);

// Close the session to reclaim the system storage // used to store the results. After the session is closed // you cannot attach to the same session again

session.Close();}

4. In the Program.cs file, locate the DurableSendUsingBrokerClient method and examine its contents. This method performs the same action as the InteractiveUsingServiceReference method, but does not register to the callback. Instead, a different method will handle the response, after the client reattaches to the session.

5. Locate the DurableReceiveUsingBrokerClient method. This method creates a BrokerClient<T> object and then iterates the service responses received from the WCF broker node by calling the BrokerClient<T>.GetResponses<TMessage> generic method. In this method, TMessage is the type of the message class representing the response type of the called service operation, as shown in the following code snippet:

C#

// Create a client proxyusing (BrokerClient<ISquareService> client = new BrokerClient<ISquareService>(session)){ Console.WriteLine("Retrieving results..."); // Get all the results foreach (BrokerResponse<SquareResponse> response in client.GetResponses<SquareResponse>()) { int reply = response.Result.SquareResult; Console.WriteLine( "\tReceived response for request {0}: {1}", response.GetUserData<int>(), reply); } Console.WriteLine("Done retrieving results.");}

6. Build the SquareService solution.

Deployment

In order to run this sample, you will need to deploy the WCF service assemblies and configuration to your head node, your on-premises nodes, and your Windows Azure nodes.

Task 1 – Copying the WCF Service Configuration to the Head Node

In this task, you will copy the WCF service configuration file to the head node’s service registration folder. This allows you to use the HPC 2008 R2 Cluster Manager application to diagnose the service deployment and create new service tasks for the service. It also allows clients to create new sessions (interactive and durable) against the head node.

1. Open the command prompt window from Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | Visual Studio Command Prompt (2010).

2. Navigate to the SquareService labs folder, and from there navigate to the Source\SquareService\bin\Debug folder.

3. Run the following command to copy the service configuration file to the head node:

CMD

xcopy SquareService.config \\MyHeadNode\HpcServiceRegistration\ /Y

Note: Replace the MyHeadNode machine name with the name of your head node machine. The HpcServiceRegistration share is created when installing the head node.

Task 2 – Deploying the WCF Service to On-Premises Nodes

In this task, you will deploy the WCF service to your HPC cluster’s on-premises nodes.

Note: If this sample is only being tested on Windows Azure nodes, you can skip this task.

There are two ways in which you can copy the WCF service such that it is accessible by your on-premises nodes:

Copy the service assembly to a shared folder in the HPC cluster.

Copy the service assembly to each of the on-premises nodes in the HPC cluster.

If you examine the service configuration file (task 2 in the Getting Started section above), you will notice that the location of the service assembly is set to a shared folder in the head node machine, therefore the following steps should be followed:

1. In your head node machine, create a share named apps. Verify that all the on-premises nodes can access this share.

2. Open the command prompt window from Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | Visual Studio Command Prompt (2010).

3. Navigate to the SquareService labs folder, and from there navigate to the Source\SquareService\bin\Debug folder.

4. Run the following command to copy the service assembly to the head node:

CMD

xcopy *.* \\MyHeadNode\apps\SquareService\ /EY

Note: Replace the MyHeadNode machine name with the name of your head node machine.

If you want to deploy the service assembly to each on-premises node, follow these instructions:

1. Change the Square service configuration file to point to a local folder in which the service assembly is located in each on-premises node. For example:

SquareService.config

<microsoft.Hpc.Session.ServiceRegistration> <service assembly="e:\apps\SquareService\SquareService.dll" contract="SquareServiceContracts.ISquareService" type="Services.SquareService" includeExceptionDetailInFaults="true" maxConcurrentCalls="0" serviceInitializationTimeout="60000" stdError="" maxMessageSize="65536"> </service></microsoft.Hpc.Session.ServiceRegistration>

Note: The assembly must be located in the same folder on all the on-premises nodes.

2. Copy the updated service configuration file to the head node, as specified in the previous task.

3. Copy the service assembly to the target location in each of the on-premises nodes. If you already have the service assembly located in the head node, you can run the following command to automatically copy the files to all the on-premises nodes:

CMD

clusrun /nodegroup:ComputeNodes xcopy \\MyHeadNode\apps\SquareService\*.* E:\apps\SquareService\ /EY

Note: If you only want to deploy the service to some of the compute nodes, change the node group specified in the nodegroup parameter. Also, remember to rename the MyHeadNode machine name to that of your head node machine.

Task 3 – Deploying the WCF Service to Windows Azure Nodes

In this task, you will deploy the WCF service to your Windows Azure nodes.

1. Open the command prompt window from Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | Visual Studio Command Prompt (2010).

2. Navigate to the SquareService labs folder, and from there navigate to the Source\SquareService folder.

3. Run the following command to create a deployment package for the service:

CMD

hpcpack create SquareService.zip bin\debug\

Note: Do not change the name of the package; the name must match that of the service configuration file and the service name used by the client application.

4. Run the following command to upload the deployment package to the Windows Azure package storage:

CMD

hpcpack upload SquareService.zip /nodetemplate:"Azure node template"

Note: Change the value of the nodetemplate parameter to the name of your Windows Azure node template.

5. If you already have Windows Azure nodes started in the HPC cluster, you need to copy the new package to them. To sync the Windows Azure nodes with the new packages stored in the application packages blob, run the following command:

CMD

clusrun /nodegroup:AzureWorkerNodes hpcsync

Running the Client

Task 1 – Verifying Cluster State

In this task, you will verify that the nodes in your cluster are online.

1. Open the HPC 2008 R2 Cluster Manager application from Start | All Programs | Microsoft HPC Pack 2008 R2 | HPC Cluster Manager.

2. In the Cluster Manager application, enter the Node Management section and verify that the Windows Azure nodes in the cluster are online, as shown in Figure 3:

Figure 3Verifying the State of the Windows Azure Nodes

3. Enter the Configuration section, select the Services option from the configuration list, and run the SOA Service Loading Diagnostics Test on the SquareService service, as shown in Figure 4:

Figure 4Running Service Load Diagnostics

4. In the Run Diagnostic Tests window, select the AzureWorkerNodes node group from the Nodes in this group drop-down list, check the Go to Test Results to see test progress and results checkbox, and then click Run.

5. In the Diagnostics window, wait for the test to complete and verify its success.

Note: If the service diagnostic fails, view the diagnostic information and perform the required fix. If this involves changing the service configuration or recompiling the service assembly, you will need to redeploy your service before running the diagnostics again.

Task 2 – Running the Client Application

In this task, you will test the WCF service in the HPC cluster by running the client application.

1. Open Microsoft Visual Studio 2010 from Start | All Programs | Microsoft Visual Studio 2010 | Microsoft Visual Studio 2010.

2. Open the SquareService.sln solution file located in the SquareService\Source folder.

3. In the Solution Explorer window, expand the Client project, and open the Program.cs file.

4. In the Program.cs file, locate the _numOfRequests static variable and set its value to at least twice the number of Windows Azure nodes you have provisioned for this test.

5. In the Solution Explorer window, set the Client project as the startup project.

6. Build the solution and run the Client project. You should see the following output:

Figure 5SquareService Client Output

Note: The order of the responses appearing in your output may be different, and the number of responses depends on the value you have set for the _numOfRequests static variable.

7. Before closing the console output, write down the session ID of the first test; you will use this number in the next section to find that session’s job history.

Inspecting the Service Output

Task 1 – Checking the Tasks’ Output Window

In this task, you will check the output created by the service tasks to find out which node handled which service requests.

1. Open the HPC 2008 R2 Cluster Manager application from Start | All Programs | Microsoft HPC Pack 2008 R2 | HPC Cluster Manager.

2. In the Cluster Manager application, enter the Job Management section, locate the finished job according to the Session ID you wrote down in task 2 in the previous section, and then click View Job…, as shown in Figure 6:

Figure 6Viewing Finished Job Information

3. In the View Job window, click the View Tasks section, and then select each task to see which requests each node handled, as shown in Figure 7:

Figure 7Viewing Task’s Output

Task 2 – Inspecting the Job’s Trace Files

In this task, you will create the trace output for the finished job and inspect the trace files created for each node.

1. Open the HPC 2008 R2 Cluster Manager application from Start | All Programs | Microsoft HPC Pack 2008 R2 | HPC Cluster Manager.

2. In the Cluster Manager application, enter the Job Management section, locate the finished job according to the Session ID you found in task 2 in the previous section, and then click Collect Trace… from the Actions section, as shown in the following image:

Figure 8Collecting Trace Information

3. In the Collect Trace window, specify the target directory in which the trace files will be saved, and click OK. After the operation completes, the target directory will open in a Windows Explorer window.

4. Open each of the trace files by double-clicking it. The trace file will open in the Microsoft Service Trace Viewer application; use the application to look at the trace outputted by the service.

Figure 9Viewing the Contents of the Trace File

Summary

After running the square service sample you should have learned the following:

How to create a WCF service that can run inside Windows Azure nodes, as well as in on-premises nodes.

How to create a configuration file for the WCF service and how to deploy it to the head node.

How to deploy a WCF service assembly to on-premises nodes and to Windows Azure nodes.

How to use an interactive session and a durable session to call the WCF service.

How to diagnose your service and inspect the output of a service task.