| This is a detailed topic in our support portal in the Using migFx series and assumes that you have some prior knowledge or experience using migFx. If you want to know more about hopp tech and migFx, our comprehensive solution for complex data migration, please visit our web site hopp.tech. |
As laid out in the article Publishing Maps and Deploying Engines, the Source- and Target Engines for data migration projects are normally deployed to the Runtime environment to be loaded into the track where migration jobs are then executed.
But in many cases, you may want to test and/or debug a newly generated engine - or indeed a new or modified manual rule - in order to verify that everything is ok before actually deploying the new engine.
This article describes exactly how to do that.
Prequisite
As will be clear below, debugging the engine means running the engine in a local process on your own computer and connecting from this process to the Staging- and Migration Database of the given track.
This will only work if the process is able to establish a connection to these databases.
The credentials of the local process will be the credentials of the Visual Studio process. This is normally your own user, but it may be another user if Visual Studio is launched with the Runas command.
If the Runtime (in the Portal Configuration) is set up to use Integrated Security, this means that the credentials of the process must have access to these databases. On the other hand, if the Director Runtime is set up to use Sql Server authentication, then there should be no special prerequisites to running Debug.
With this important prerequisite in place, let's get to it.
An overview
At the end of the day, the goal here is to allow you to step through the code in Visual Studio on your own machine.
Here's an outline of the process to get to this point. Each step will be described in detail below.
| 1. Set Breakpoint(s) | Click the left gutter-margin in the Visual Studio Editor to set your breakpoints |
| 2. Launch Debug | Launch the Debug from the Hopp context menu in Visual Studio |
| 3. Select Business Object | Use the dialog provided to select the Business Object(s) you want to be the subject of your debug |
| 4. Run the debug | Hopp will start a job process locally on your machine and attach the Visual Studio debugger to it |
| 5. Step through your code | You can now step through the code and inspect the values of variables and fields along the way |
| 6. Clean up | Hopp will delete temporary files used by the debug session |
1. Set Breakpoints
Let's say you want to debug a manual rule implementation. Open the rule in Visual Studio and click in the left hand gutter to set your breakpoint.
Below the breakpoint is set in the Exit Rule CreateMissingInterests.cs in our demo Target Map.
2. Launch Debug
Right-click the project in the Visual Studio Solution Explorer and choose the Debug item from the Hopp sub-menu.
First Visual Studio will compile (build) the engine. But when it comes to setting up the debug session, Visual Studio needs the help of the Portal. It is the Portal that has a connection to the runtime environment and also the Portal that knows in which track(s) the engine is actually running.
So, Visual Studio connects to the Portal, and the Portal will query the runtime environment to show you a dialog to select a track and what to debug in this track.
Visual Studio will now wait for you to make your selections and for the Portal and the Runtime to do their magic and communicate back the id of the process to debug.
3. Select Business Object
Once the Visual Studio has received the necessary info from the Portal and Runtime, you can select exactly what to debug from the dialog.
Firstly, if the engine is deployed to more than 1 track, you need to select the track in which you want to debug.
Once the track is selected, you have several options to select what you want to debug in this track. These options are similar to the options in the Portal Operations to choose which Business Objects to export/import.
| Business Object | If you choose one of the Business Objects known to the selected track, you can select one of 3 options
| ||||||
| Item set | Debug an instance from an item set that has been created in the track | ||||||
| Limit | Limit how many instances you want to run through the debug (normally 1) |
4. Run the debug
Once the selection is completed, click the Start button to start the debug session.
Visual Studio will first close the selection dialog and then go to work:
- The current version of the Runtime libraries are downloaded from the runtime environment to a local, temporary folder on your machine
- A job is created in the track, but this job is not submitted to the scheduler in the running track on the runtime server
- Instead, the Visual Studio extension launches a process on your local machine to run the job. This process then blocks, waiting for the Visual Studio debugger to be attached
- The extension communicates the id of the process back to Visual Studio and then sits down to wait for the process to finish
- Visual Studio receives the process id from the extension and attaches the debugger to this process
- The process itself discovers that the debugger is now attached and unblocks, allowing the debug session to commence
5. Step through the code
The debugger is now attached and the process running the job is free and will continue on to - hopefully - hit your breakpoint. Hopefully, because the job may in fact exit without ever reaching your breakpoint.
For instance, consider these situations:
- Your selection did not in fact identify any Business Object instance to run
- The Runtime fails the job because the generated engine requires a setup job to be run
- The engine logic never reached your breakpoint
In these cases (and others) it is up to you to rectify the issue and retry the debug session. The log output from the job will appear in Visual Studios Output tool window, and you can probably find information there to explain why your breakpoint wasn't hit.
If no issues arise, the process will continue until it hits your breakpoint, at which point you can now single step through the code using the normal Visual Studio shortcuts. Normally F10 for Step Over, F11 for Step Into and F5 for Run to next breakpoint (or to finish if no more breakpoints)
Your can use the Visual Studio Local and Watch tool windows to inspect the values of variables and fields
The output emitted to the Director Job Instance log is also emitted to the Visual Studio Output tool window
Once you are ready to finish up, you can either hit F5 to tell the debugger to run to next breakpoint (or to finish). Or you can detach the debugger from the process and allow it to run to finish on its own.
You detach from Debug in the Visual Studio main menu
6. Clean up
Once the local process has exited, the Director - who has been patiently waiting for this to happen - will spring to life and delete the temporary folder containing the Runtime that was downloaded, leaving no trace behind on your machine.
Conclusion
Running a test of the local version of the generated engine is pretty straight forward using the Hopp functions provided in Visual Studio.
As outlined above, you can use this to debug manual rule implementations. But you can also just test an engine that has been generated based on some new mapping before deploying the engine for real.
A final note: Even though you are running a local process on your own machine using the local version of the engine, you are in fact migrating the selected items in the chosen track. So your job naturally shows up in the Portal Operations job list:
