On-boarding a IBM Spectrum Symphony application with Visual Studio

This tutorial walks you through the steps for on-boarding a sample application using the IBM® Spectrum Symphony add-in for Visual Studio. After completing the tutorial, your sample application will be able to perform calculations in parallel on the grid. Familiarity with the Visual Studio IDE is recommended.

1. Test the sample.
   Before you start the on-boarding process, run the sample application to ensure your Visual Studio development environment is working properly.
   1. Locate the sample solution folder at %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\1-Before. To open the solution, double-click the solution file applicable to your version of Visual Studio.
   2. Select Debug > Start Without Debugging.

      Visual Studio builds the solution and executes the code.

   3. If your command window displays the following output, your development environment is working properly and you are all set to begin the on-boarding process. Proceed to Step 2.
      
2. Add the .NET class library to the solution.
   The following steps show you how to take the .NET class library that you built during the previous step and add it as a project to the sample solution.

   Important: Back up the sample Visual Studio solution before proceeding with the following steps in case you need to revert to the original files.
   1. In the Solution Explorer, right-click the solution. Select Add > New Project.

      The Add New Project dialog displays.

   2. Make the following selections:
      1. In the Project types pane, select Symphony.
      2. In the Templates pane, select Grid Enabled Library (x86).
   3. In the Name box, enter BasicGridCalculator.
      Note: The project name is used as a namespace in the generated code. To avoid potential conflicts, do not choose a project name that is used as a namespace or class in the original code.
   4. Click OK.

      The on-boarding wizard launches.

      The wizard adds the following three projects to the solution:

      • BasicGridCalculatorProxy (proxy class)
      • BasicGridCalculatorService (computational logic)
      • BasicGridCalculatorTransport (serializes/de-serializes proxy calls to/from the service)
   5. Click Add.

      The Open file dialog displays.

   6. Select the .NET class library BasicCalculator.dll that you built previously at BasicCalculator\bin\x86\Debug\.
   7. Click Open.

      The .NET class library is added to the list of .NET assemblies in the wizard.

   8. If we had additional items such as dependent libraries or configuration files, we would select the Library Dependencies tab and add them here. Click Next. Proceed to Step 3.
3. Expose the members in the .NET class library so that you can access them via the proxy.
   Exposing the methods, and properties of the .NET class library enables you to access them in the proxy so that you can interact with the grid-enabled class library as if it was a local object. Note that the wizard exposes all members of a selected class.
   1. In the wizard's object explorer, expand BasicCalculator.dll. Select the Calculator namespace. Ensure BasicCalculator under Classes in namespace "Calculator" is checked.
   2. Click Next.
   3. Fully expand BasicCalculator.dll and select BasicCalculator class.

      A list of the class's properties/methods and their respective roles displays. These are the methods and properties that will be exposed in the proxy object so that you can interact with the service; refer to Using Visual Studio as your development environment for a detailed description of property and method roles.

      Note: When on-boarding, ensure that you do not define any function named void Dispose() in your class code. The void Dispose function causes build errors.
   4. Click Next.
   5. In the Application Name textbox, enter BasicGridCalculatorApp. If we were connected to the grid, we would also need to specify a valid consumer to which the application belongs.
   6. Click Next.

      The wizard completes the code and project generation process and summarizes the generation activities. The sample application is registered and deployed to the grid.

   7. Click Next.
   8. At this point, all code and project generation is complete but if you were able to run the client program CalculateInterest.exe, it would still call the methods of the local .NET class library instead of the library on the grid. You can either manually add the proxy reference to the client and update the code to refer to the generated proxy class or you can let the wizard do it for you. Let’s have the wizard do the changes for us.

      In the Projects to be updated list, select CalculateInterest.NET.2013.

      Note: During this step, it is important to select only the projects where you want the wizard to update the client code and add references to the proxy that was just generated and not select any of the other libraries currently being on-boarded.
   9. Click Next.

      The wizard updates and builds the CalculateInterest.NET.2013 project.

      If you were to look at the code in the Program.cs file, you would see that a reference to the BasicGridCalculator class has been added and we are now using the BasicCalculator proxy class in our code instead.

      using BasicGridCalculator;
      ...
      //Main program
      ...
      calculator = new BasicGridCalculator.BasicCalculator();
      

   10. Click Next.
       We have now reached the last page of the wizard. All the activities performed by the wizard are recorded in build.log at the following locations:

       1. Proxy build log: %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\1-Before\BasicGridCalculator\BasicGridCalculatorProxy
       2. Service build log: %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\1-Before\BasicGridCalculator\BasicGridCalculatorService
       3. Transport build log: %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\1-Before\BasicGridCalculator\BasicGridCalculatorTransport
   11. Check that both Open the generated Readme.html after the wizard exits and Open the generated Report.txt after the wizard exits are selected.
   12. Click Finish.
       The wizard closes and the Readme.html and Report.txt pages are displayed. The Readme file provides descriptions and code samples of the properties and methods that are available through the proxy. The readme file uses a color-coding scheme to distinguish the classes and methods, as follows:

       • Blue: links to proxy classes or methods that are derived from the original user-defined classes or methods
       • Green: links to classes or methods on these proxy objects that have been added by the wizard to make the classes or methods more grid-capable.

       The Report.txt file summarizes all the activities performed by the wizard during the on-boarding process including client code updates, creating and building projects, deploying service packages, and registering the application.

       Proceed to Step 4

4. Run the sample on the grid
   Before proceeding, test the application on the grid to ensure it is working properly:
   1. Select Debug > Start Without Debugging.

      Visual Studio builds the solution and executes the code.

   2. Verify that your command window displays the same output as in step 1.
   3. You can also verify that the workload was successfully completed by accessing the cluster management console through the IBM Spectrum Symphony menu extensions for Visual Studio. Before you can connect to the cluster management console, you must first select the respective service for the application. This is necessary since each service project stores its respective application profile and service package and an on-boarded application can generate multiple service projects.

      In the Solution Explorer, select the BasicGridCalculatorService project.

   4. Select Symphony > Monitor Workload.
   5. In the cluster management console, check that the Sessions page shows 1 session with 16 tasks done. For an explanation on how on-boarded application methods are mapped to workload, refer to Using Visual Studio as your development environment.

      Proceed to Step 5.

5. Free up IBM Spectrum Symphony resources.

   It is good programming practice to free up IBM Spectrum Symphony resources when they are no longer needed. For example, the client may have used a proxy and has no intention of using it anymore but the client is expected to run for several minutes after that. During this time, the session would remain open unnecessarily in IBM Spectrum Symphony. To address this issue, we can call the Dispose() method on the proxy object at a point where we no longer need the proxy and just before the reference goes out of scope.

   ...
        Calculate(principalAmounts, calculator);
   }
   catch (Exception E)
   {
        Console.WriteLine("{0}\n{1}", E.Message, E.StackTrace);
   
   }
   finally 
   {
       if (null != calculator)
                   {
                       calculator.Dispose();
                   }
   }
    

   Refer to Using Visual Studio as your development environment for more information about the Dispose() method.

   Next, we will look at how to optimize the client code to maximize the benefits of running our application on the grid.

6. Optimizing the code for the grid.

   In the previous step where we ran our application on the grid, our client interacted with the grid-enabled library and the calculations were actually performed on the grid. But the interaction between the client and the service was synchronous in nature as each input task was sent to the service, one at a time, in a blocking mode.

   The following code snippet was taken from the client file Program.cs.

   foreach (double amount in principalAmounts)
   {
       double interest = calculator.SimpleInterest(amount);
       Console.WriteLine("Principal : ${0},\t Interest: ${1}",
       amount, interest);
   }
   

   In the code, we can see that the main execution thread loops through the principal amounts, one at a time, and waits for the result of each calculation to return before it calls the next method. Although the code executes and results are collected, this approach does not benefit from running on the grid. Benefits can only be realized when you execute methods in parallel across multiple computing resources available on the grid.

7. Run the optimized sample on the grid.

   For instructions on how to run the optimized grid sample, refer to the Basic Calculator (After on-boarding) readme file in the %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\2-After directory.

8. Port the code sample to 64 bit.
   By default, the code sample is 32 bit for Windows 32-bit and 64-bit platforms. If you want to on-board the sample as a 64-bit application, you must first port the 32-bit sample into 64 bit, and perform the application on-boarding as a 64-bit project.
   1. Locate the sample solution folder from the %SOAM_HOME%\version\samples\AppOnboarding\DotNet\CS\Calc\1-Before directory. Double-click BasicCalculator_2013.sln to open the solution.
   2. In the Solution Explorer, right-click Solution 'BasicCalculator_2013' (2 projects), and select Configuration Manager....
   3. In the list of Active solution platform, select <New...>.
   4. In the list of Type or select the new platform, select x64.
   5. In the list of Copy settings from, make sure x86 is selected. Also, ensure that the Create new project platforms box is checked.
   6. Click OK. You can now on-board the 64-bit sample as described in this document for 32 bit, with the exception of the path for BasicCalculator.dll, which becomes BasicCalculator\bin\x64\Debug\.