4 Creating a Hopex C# macro
You can create macros used by Hopex using the C# language.
Macros should implement a public class and have public methods that can be called from Hopex.
The C# code must be built as C# DLL (Class Library).
4.1 Creating a new class library project in Visual Studio
Visual Studio 2022 is strongly recommended, all variants are valid (Community, Professional, Enterprise).
To create a class library project in Visual Studio:
1. Select .NET 8 version (V6 is still supported until end of 2024).
2. Complete the initialization of the project and go in the Solution Explorer.
3. Expand the solution.
4. Right-click Dependencies and select Add Project Reference.
A window appears.
5. Click Browse.
6. Find the Mega.Macro.Wrapper.dll, in the System folder, which is inside the Hopex installation directory:
C:\ProgramData\MEGA\Hopex Application Server\<port number>\.shadowFiles\hopex.core\<version number>\System\
Now you can use all the Hopex classes inside your C# macro.
4.2 Building the DLL with the Hopex macro
From Visual Studio, select Build > Build Solution menu (short cut Ctrl+Shift+B).
The DLL will be built in your defined output directory.
Note that, if your target output path is the same path where the DLLs should be placed, and Hopex is running, the build will fail because the DLL cannot be replaced while Hopex is active.
If you want to test the DLL in debug, build it in debug mode. When you are done with the debugging, remember to build it in release mode to improve its performance.
4.3 Placing the DLL inside Hopex
The recommended folder where to place the DLLs depends if you want to deploy it as module, inside a customization package, or not.
• Recommended path:
<Hopex installation directory>/.shadowfiles/Macros/<Your module name>/<your version number>/hopex.core/dotnet/assemblies/
• Possible path (useful for the development cycle):
<Hopex installation directory>/.shadowfiles/hopex.core/<your version number>/dotnet/assemblies_usr/
4.4 Try to avoid adding dependencies to the DLL
The DLL will not require any standard C# DLL to work, they will be provided by Hopex. Try also to avoid using old DLLs like Newtonsoft.Json because they are fully replaced by better functions native of .NET 6 and 8.
If you really need to add external libraries, be sure they are available as NuGet packages.
4.5 Structure of the code
You can place as many classes as you want inside the DLLs. Only public methods inside public classes will be directly accessible from Hopex.
A typical class will look like:
You can use all the standard Hopex API's classes like MegaRoot, MegaObject, MegaCollection.
4.6 Defining the Macro in Hopex
Once your DLL is built and deployed, you must define it in Hopex. This must be performed in HOPEX Windows Front-End.
1. In HOPEX, create an item of type macro and follow the wizard.
Make sure to use the full namespace of your class and to write the exact name of the DLL you will build and deploy.
The DLL is expected to be called MyExampleCSharp.dll (and placed in one of the previously mentioned folders).
In case the namespace (that is case sensitive as the class name) is wrong or the name of the DLL (not case sensitive) is wrong, the macro will not be loaded and executed.
4.7 Testing your Macro
To test your macro:
1. In Hopex, open the script editor.
2. Enter the following code:
Note: the second line is an example, your method will have a different name.
set m = currentEnvironment.getMacro(“My Example Macro”)
print m.HelloWorld(getRoot, “John Doe”)
Make sure you drag and drop the Macro you created before inside the getMacro statement to place its ID. You can also open the properties of the macro and copy its ID and then place it as parameter of getMacro.
4.8 Debugging your macros with Visual Studio
To debug your macro:
1. In Visual Studio, select Debug > Attach to process menu. (Ctrl+Alt+P)
2. Select the processes you want to debug.
Do not change the connection mode (keep it as automatic) and select all processes with “Hopex” in their names (yes there can be multiple of them).
3. Place a breakpoint in your code and run the macro.
The breakpoint should be hit, and you can run step by step and inspect variables.
In case you see a warning when setting the breakpoint, be aware that C# DLLs are not loaded at startup but only when needed. The solution is to execute your macro first and then attach Visual Studio to the process and place the breakpoint.
In case your breakpoint says that symbols are approximate be sure you copy not only the DLL of the macro but also the PDB file that is generated in debug mode. This will allow you to debug the code with single instruction precision.