|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.
Hopp is based on Net 6.0 and requires minimum Visual Studio 2002. Together with Hopp we provide an extension to Visual Studio to facilitate the handling of Migration Engines.
The extension assists with all the common operations in Visual Studio in connection to Hopp:
- Create new library projects for Source- and Target engines
- Add new c# class files for manual implementations of Bags and Rules to Source- and Target Engine projects
- Generation and Deployment of Engines
- Local Debug of Engines
Visual Studio must be closed before installing the extension. The VSIX installer for the Hopp Visual Studio Extension is made available by hopp tech as part of your Hopp license agreement on the current download page.
In order to create new engine projects and to deploy the engine projects to the Hopp Runtime, you need to set a few options in Visual Studio after installing the extension.
Open the Visual Studio Options dialog from the Tools -> Options menu:
In the Options dialog, locate the Hopp -> General options
Provide the values for the options:
|Accept untrusted certificates
|Set to True, if your installation has not provided a trusted SSL (https) certificate for the Portal.
If you see certificate warnings like below in the browser, when you access the Portal, you need to set this option to True.
|This is the URL you type in the browser to access the Hopp Portal
|Use local libraries and engine framework
|Hopp provides the Engine Generator as well as the libraries used by the Migration Engine projects on NuGet.
In some installations, Hopp runs in a ringfenced environment without access to the internet and thus git. If this is the case, you can set this option to True.
When the option is set to True, you must install the Hopp Libraries and the engine framework locally on your workstation. These are available from the Hopp download page
When the option is set to False, you must install the Hopp Generator tool from NuGet. This can be done from PowerShell with the command:
dotnet tool install hopp.tools.enginegenerator --global
|Use system browser for login
|By default, the Visual Studio extension will use an embedded browser to sign you in to the Hopp Portal.
In rare cases this can cause problems. Set this option to True to use your default system browser instead
Create new library projects for Source- and Target Engines
Adding new Engines projects is done through the normal Add Project... wizard in Visual Studio. Right-click the solution node or any solution folder in the Solution Explorer and choose Add -> New Project...
This will open the Add project wizard. Choosing migFx in the Project Type dropdown will quickly locate the templates provided by migFx for creating a new Source Engine or a new Target Engine.
Select the Source Engine template or the Target Engine template and click next.
Provide the Project name and the Location and click Create. The wizard will create the selected engine in the location folder provided.
The migFx.manifest file in the TargetEngine project and the SourceEngineCustom project respectively contains information for the migFx to call the engine generators correctly.
The manifest is an xml file containing these elements:
|The type attribute marks this to be a Target Engine or a Source Engine.
|The path to the xml file containing the xml of the corresponding map published from Studio.
When the generation is launched from Visual Studio, this information is used to check out the PublishedXml file from source control - if required.
|Contains a collection of Cmd elements, each defining a generator to be executed on generation. The manifest is created by migFx with the Cmd element to run either the Source- or the Target Engine generator according to project type.
But it is important to note that Cmd elements can be called to run other commands on code generation if desired.
|A Project element for each project of the engine. 1 for the Target Engine and 2 for the Source Engine.
Adding manual implementations of Bags and Rules
The Visual Studio extension also comes with templates for the manual implementations of Bags and Rules in both the Source and the Target Engine.
Adding a Rule
Simply right-click the folder in which you want to add a Rule implementation and choose Add Rule...:
Provide the name of the Rule you are implementing. This should be the same name as in migFx Studio:
A new .cs file will be added to the selected folder and will open in Visual Studio. The file is all prepared and all you now have to do is to override the method provided by the generated code:
Adding a Bag
Right-clicking the Bag folder gives the option of adding a Bag:
Again, provide the name of the Bag to implement - the same as in migFx Studio and the .cs file with the Bag implementation will be added to the Bag folder and opened in Visual Studio:
Generate, Deploy and Debug
A right click on a TargetEngine project or a SourceEngineCustom project will show the project context menu with the migFx submenu:
The Generate... context menu item open the generation dialog:
The dialog allows you to specify the Published xml file to use as input for the code generation. This is the file containing the published Source/Target Map from migFx Studio. By default, this is the Published xml file in the engine project, but you can override it before generation if you temporarily want to generate from another file.
The dialog gives you a label with the last modified time of this file as a sanity check. If the file is more than 10 minutes old, the label is red.
Click Ok to start the code generation. Visual Studio will show the output from the code generator in the Output tool window:
The Deploy... menu item will first build the engine in question. If the build succeeds, the Visual Studio extension will invoke the Portal. The Portal will in turn query the Runtime configuration and show a dialog with a list of all the tracks using the engine about to be deployed:
For each track, you can choose what should happen after the engine is deployed:
- Starting or Restarting the Track will cause the newly deployed engine to be loaded
- After starting the Track, you can choose to run the Set Up of the deployed engine
These actions are exactly the same as the ones normally done in the Portal Operation So you can also opt out of them here and simply deploy the engine without checking any options. You will then have to go to the individual tracks in Portal Operations and do the start/restart and setup from there.
If you have authorization to connect to the Hopp master and track databases, you can launch the migration of selected Business Objects from within Visual Studio.
This allows you to
- Set breakpoints in Visual Studio in order to debug and single step through Bag/Rules implementations
- Test and verify the generated engine locally before deploying it to the Director Runtime.
The Debug... menu item will first build the engine. If the build succeeds, the Visual Studio extension will invoke the Portal. The Portal will in turn query the Runtime configuration and show a dialog to select what to debug:
After selecting which Track to debug, you can run debug on a limited set of Business Objects selected
- By Business Object
- Any arbitrary
- On a Key
- That fired a given Event
- By Item Set
Click Start to launch a debug job in the Runtime. The Runtime will start the job process locally on your machine and the Visual Studio extension will attach the Visual Studio debugger to this job. The debugger will stop on any breakpoints it hits during execution.
We hope this article gave you a good impression of the benefits of the migFx Visual Studio extension. It is intended to give you a hand in driving the work with the actual engines generated on the basis of the migFx Studio mapping and help you be more productive.