Tutorial 1 Creating a client and worker from scratch

What this tutorial will teach you

This tutorial will demonstrate the following:

1. How to create a OneCompute solution from scratch using standard project templates.
2. How to run a very simple calculation in Azure Batch.
3. How to retrieve status and progress messages from a worker running in Azure Batch and display them in the client application.
4. How to cancel a running calculation.

Note

This is a tutorial for the use of the OneCompute libraries, not all steps are relevant in the context of OneComputePlatform.

The end result

At the end of this tutorial, the solution you build will comprise 3 projects:

1. A Worker project that defines custom calculations to run in Azure Batch.
2. A WPF Client application that provides a user interface to run on the desktop.
3. A Common project that defines custom types that are shared between the Worker and WPF Client projects.

You will be able to build and run the solution to learn how to put together a OneCompute application and adapt it to your own requirements.

A complete example is available in the PIEstimatorSample.

Tutorial scenario

Once you complete the tutorial, the application that is created will take a range of integers as input and dispatch work to be run in Azure Batch to calculate the square of each number. Status and progress messages for the calculations are fed back from the Worker to the client application for display in a log in the user interface.

// In this simple example, we specify a set of numbers to be squared.
var numbersToSquare = Enumerable.Range(0, 5).ToList().AsReadOnly();

The calculation (i.e. squaring a number) used in this tutorial is intentionally trivial so as not to become a distraction from learning how to use OneCompute. However, the calculation represents how you might use existing libraries that contain your business logic (e.g. hydraulic models, structural analyses etc.) and utilize them in OneCompute and deploy them to Azure Batch.

The code that calculates the square of a number is also artificially broken down in to a series of iterations with a sleep/delay between each iteration. This is obviously not necessary simply to calculate the square of a number, but is useful for demonstrating a cancelable operation which is hard to demonstrate otherwise.

Prerequisites

To run through this tutorial successfully requires the following:

• Visual Studio 2022.
• .NET 6.0 or higher (installed by default in Visual Studio 2022)
• The One NuGet Package Sources to be configured in Visual Studio.
• The PowerShell Tools for Visual Studio extension to be installed into Visual Studio.
• An Azure Batch account with a pool already created.
• An Azure Storage account with a blob container already created.
• An Internet connection.

For more information on configuring the One NuGet Package Source and configuring the prerequisite Azure resources, please see the following links:

• One NuGet Package Sources
• Azure resources

Instructions

Step 1 - Create the WPF client application project

In this step we will create a new WPF client application project and add it to a new solution that we also create.

1. Open Visual Studio.
2. Select File > New > Project....
3. In the New Project dialog, select C#, All platforms and Desktop from the filters.
4. Select the WPF Application (.NET Framework) project template.
5. Set the target framework to .NET Framework 4.6.1.
6. For the project name, enter OneComputeWpfClient.
7. For the project location, browse to a folder of your choosing.
8. For the solution name, enter OneComputeTutorial.
9. Click OK to create the solution and project.

Step 2 - Create the Worker class library project

In this step we will create a add a new Worker class library project and add it to the solution created in the previous step.

1. Select File > New > Project....
2. In the New Project dialog, select C#, All platforms and All project types from the filters.
3. Select the Class Library (.NET Framework) project template.
4. Set the target framework to .NET Framework 4.6.1.
5. For the project name, enter OneComputeWorker.
6. For the solution option, select Add to solution.
7. Leave the project location at the default value.
8. Click OK to create the project and add it to the solution.

Step 3 - Create the Common class library project

In this step we will create a add a new Common class library project and add it to the same solution. This project contains types that are used by the WPF client application and Worker projects.

1. Select File > New > Project....
2. In the New Project dialog, select C#, All platforms and All project types from the filters.
3. Select the Class Library (.NET Framework) project template.
4. Set the target framework to .NET Framework 4.6.1.
5. For the project name, enter OneComputeCommon.
6. For the solution option, select Add to solution.
7. Leave the project location at the default value.
8. Click OK to create the project and add it to the solution.

Step 4 - Configure project dependencies for the OneComputeWorker project

In this step we will establish project dependencies between the OneComputeWorker and OneComputeCommon projects.

1. In Solution Explorer, navigate to OneComputeWorker > References.
2. Right-click the References node in the tree and click Add Reference....
3. Select the Projects node in the tree on the left hand side of the dialog.
4. Check the box to establish a dependency on the OneComputeCommon project.
5. Click OK.

Step 5 - Configure project dependencies for the OneComputeWpfClient project

In this step we will establish project dependencies between the OneComputeWpfClient and OneComputeCommon projects.

1. In Solution Explorer, navigate to OneComputeWpfClient > References.
2. Right-click the References node in the tree and click Add Reference....
3. Select the Projects node in the tree on the left hand side of the dialog.
4. Check the box to establish a dependency on the OneComputeCommon project.
5. Click OK.

Step 6 - Adding NuGet packages

In this step we will add references to OneCompute NuGet packages.

• Add the latest DNVGL.One.Compute.Scheduling.AzureBatch NuGet package reference to the OneComputeWpfClient project
• Add the latest DNVGL.One.Compute.WorkerHost.AzureBatch NuGet package reference to the OnComputeWorker project

Step 7 - Build the solution

In this step we will build the solution to make sure that everything compiles. You will not be able to run the application just yet, even after building it, but this will be a useful validation step to make sure that everything is configured correctly so far.

1. Select Build > Build Solution.
2. Confirm that all 3 projects built successfully by checking the Output window.

Step 8 - Adding OneComputeCommon code

Add the following files to the OneComputeCommon project:

• MyInput.cs
• MyResult.cs

Remove any default classes that were already added to the project (e.g. class1).

Step 9 - Add OneComputeWorker code

Add the following files to the OneComputeWorker project:

• Calculator.cs
• Worker.cs

Add the following file to the OneComputeWorker project in a Deployment folder:

• Deployment\CreateApplicationPackage.ps1

Remove any default classes that were already added to the project (e.g. class1).

Step 9 - Adding OneComputeWpfClient code

Add the following files to the OneComputeWpfClient project in the specified folders:

• Azure\AzureBatchConstants.cs
• Azure\AzureBatchWorkItemScheduler.cs
• Azure\AzureStorageConstants.cs
• Services\OneComputeServices.cs
• Services\TraceLogger.cs
• Support\NotifyPropertyChangedBase.cs
• Support\ParameterlessRelayCommand.cs
• ViewModels\LogEntryViewModel.cs
• ViewModels\MainViewModel.cs
• Views\MainView.xaml
• Views\MainView.xaml.cs

Remove MainWindowView.xaml and MainWindowView.xaml.cs.

Finally, change the StartupUri in App.xaml to use Views/MainView.xaml

<Application x:Class="OneComputeWpfClient.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:local="clr-namespace:OneComputeWpfClient"
             StartupUri="Views/MainView.xaml">
    <Application.Resources>

    </Application.Resources>
</Application>

Step 10 - Complete the TODO action items in the code

In this step we will complete a number of TODO action items left in the code provided in the previous step. This involves entering account names, keys and various other credentials for connecting to your Azure resources, amongst other things. Some settings are optional and you can choose to keep the default value provided if you wish, while others are mandatory and the application will not run successfully unless they are specified.

1. Select View > Task List to display the Task List window.

2. Double-click each TODO item sequentially to jump to that location in the code and specify the necessary values using the table below as a guide.

   TODO Item	Project	File	Required	Instructions
   Define your Azure Batch pool Id.	OneComputeWpfClient	Azure\AzureBatchConstants.cs	Yes
   Define your Azure Batch account key.	OneComputeWpfClient	Azure\AzureBatchConstants.cs	Yes
   Define your Azure Batch account name.	OneComputeWpfClient	Azure\AzureBatchConstants.cs	Yes
   Define your Azure Batch account URL.	OneComputeWpfClient	Azure\AzureBatchConstants.cs	Yes
   Define your worker host application package environment variable name.	OneComputeWpfClient	Azure\AzureBatchWorkItemScheduler.cs	Yes	Name this AZ_BATCH_APP_PACKAGE_SQUARERWORKER.
   Define your Azure Storage Blob container name.	OneComputeWpfClient	Azure\AzureStorageConstants.cs	Yes
   Define your Azure Storage account key.	OneComputeWpfClient	Azure\AzureStorageConstants.cs	Yes
   Define your Azure Storage account name.	OneComputeWpfClient	Azure\AzureStorageConstants.cs	Yes
   Define your user Id, which must be an email address.	OneComputeWpfClient	ViewModels\MainViewModel.cs	No
   Define your preferred task monitoring update frequency.	OneComputeWpfClient	ViewModels\MainViewModel.cs	No	No changes required.
   Define your Azure Batch application package Id's.	OneComputeWpfClient	ViewModels\MainViewModel.cs	Yes	Name this SquarerWorker.
   Define your job's work to be done.	OneComputeWpfClient	ViewModels\MainViewModel.cs	No	No changes required.
   Define your job in terms of parallel and/or sequential work.	OneComputeWpfClient	ViewModels\MainViewModel.cs	No	No changes required.
   Define your preferred work unit status update frequency.	OneComputeWpfClient	ViewModels\MainViewModel.cs	No	No changes required.

Step 11 - Build the solution in the Release configuration

In this step we will build the solution in the Release configuration. This will validate that the solution builds successfully after making changes. Building the Release configuration is also an important prerequisite for creating an Azure Batch application package as explained in a later step.

1. Switch the solution build configuration to Release.
2. Select Build > Build Solution.
3. Confirm that the solution built successfully by checking the Output window.

Step 12 - Create an Azure Batch application package for the worker

In this step we will run a PowerShell script to create an application package zip file ready for deployment to Azure Batch. The application package zip file that is created will contain the OneComputeWorker project

1. In Solution Explorer, navigate to OneComputeWorker > Deployment > CreateApplicationPackage.ps1.
2. Double-click CreateApplicationPackage.ps1 to open it in the editor.

3. Scroll to the last line of the script and replace xxxxxx with SquarerWorker as shown below.

   # Before:
   CreateApplicationPackage "xxxxxx" "..\OneComputeWorker\bin\Release"
   
   # After:
   CreateApplicationPackage "SquarerWorker" "..\OneComputeWorker\bin\Release"
   

4. Save the changes to the file.

5. In the Solution Explorer, right-click CreateApplicationPackage.ps1 and select the Execute File menu option.

   Tip

   If you do not see the Execute File menu option, ensure you have the PowerShell Tools for Visual Studio extension installed, or use another method for executing the PowerShell script.

6. Check the Output window for any errors.

7. Confirm that the \Deployment\AppPkgZips\SquarerWorker.zip was created in the folder where your OneComputeWorker project is located.

   Warning

   The CreateApplicationPackage.ps1 PowerShell script always zips from the Release folder and never from the Debug folder, therefore, the PowerShell script will fail if the Release configuration has never been built.

Step 13 - Deploy the application package zip file to Azure Batch

In this step we will deploy the SquarerWorker.zip application package to your Azure Batch account. The application package needs to be uploaded to the pool that you specified in the AzureBatchConstants.cs file.

For information on using Azure Batch, configuring a pool and deploying an application package, please consult the Microsoft Azure Batch documentation.

Tip

In addition, within the worker template we have provided an Azure CLI script that you can adapt to deploy your application package zip to Azure Batch. This is located in OneComputeWorker > Deployment > DeployApplicationPackageToAzureBatch.azcli. Information about the usage of this can be found here.

Step 14 - Run the application

In this step we will run the application and check if everything works as expected.

1. Switch the solution build configuration to Debug.
2. Select Build > Build Solution.
3. Confirm that the solution built successfully by checking the Output window.

4. Confirm that your Azure Batch pool is configured with compute nodes that are available and ready to receive jobs.

   Note

   It is recommended that you first ensure your Azure Batch pool is configured with compute nodes that are available and ready to receive jobs, otherwise the application will appear to take a long time to run. This is perhaps most pertinent if your pool uses an auto scale formula as it can take several minutes for the pool to resize and the compute node(s) to become available.

5. Select Debug > Start Debugging to run the application through the Visual Studio debugger.

6. When the application loads, click the Run button.

7. Check the log for any error messages.

   Note

   You should see that the Run button disables and the Cancel button enables, and messages should start to appear in the log. The application will probably take a minute to several minutes to run depending on the characteristics of your Azure Batch pool. The calculation is complete when the Run button re-enables and the Cancel button disables.

   Note

   The log will display work item and job progress and status messages.

8. Close the application.

Step 15 - Cancel a running calculation

In this step we will run the application and cancel the operation before it completes to demonstrate how a client application can request cancellation of remote operations executing in Azure Batch.

1. Select Debug > Start Debugging to run the application through the Visual Studio debugger.
2. When the application loads, click the Run button.

3. Wait approximately 10 to 15 seconds, and then click the Cancel button.

   Note

   Depending on exactly when you click the Cancel button will determine how quickly the operation is canceled and the Run and Cancel buttons toggle their enabled/disabled states. If you happen to click the Cancel button while the job and tasks are still being scheduled in Azure Batch, then the operation will likely cancel quite quickly and the Run button will re-enable. If however the job was already scheduled with Azure Batch before you clicked the Cancel button, then it may take a few or several seconds before the operation is canceled and the Run button re-enables. This is because there are calculations (Azure Batch tasks) that are running that must be interrupted and canceled. So timing will dictate the exact experience you get, and is of course very difficult to predict and is subject to resources beyond your direct control.

4. Check the log for messages indicating that the calculations have been cancelled/aborted.

5. Close the application.

Summary

This brings us to the end of the tutorial. In this tutorial you have learned how to:

1. Create a OneCompute solution from scratch.
2. Run a very simple calculation in Azure Batch.
3. Retrieve status and progress messages from a worker running in Azure Batch and display them in the client application.
4. Cancel a running calculation.

Next steps

You can use the sample application that you just created in this tutorial and adapt it to solve a real scenario relevant to your domain. Just follow through the TODO items in the code and make the necessary adjustments. For example, you can replace the calculator (Calculator.cs) that was used in this tutorial with your own business logic.