Please note: This example assumes that you have installed X# with the default installation options, and that the X# runtime is installed in the GAC.
If you have not done that then the example won't run. Please see the chapter about this in this documentation
As first example of XPorting VO apps we take the VO Explorer example.
Start the VO Xporter program and point it to the VO Explorer example:
On my machine the VO installation is in the C:\Cavo28SP3 folder. That may be different on your machine of course.
I have not changed any or the xPort options. The options are:
Option |
Description |
RemoveClassClause |
Remove the “Class Clause” for methods and accesses/assigns. This will group all methods inside a CLASS .. END CLASS block and then the CLASS clause at the method level is no longer required |
ChangeInitAxitToCtorDtor |
Init and Axit are reserved method names in VO. In DotNet these names are often used by classes. Vulcan and X# have introduced new keywords CONSTRUCTOR and DESTRUCTOR. This option automatically renames the Init and Axit Methods. Example: METHOD Init(oOwner) CLASS MyClass becomes CONSTRUCTOR(oOwner) |
RemoveDeclareMethod |
If you used strong typing in VO you needed to add DECLARE METHOD statements and/or DECLARE ACCESS and DECLARE ASSIGN. The X# compiler still recognizes these statements but no longer requires them |
RemoveExportLocalClause |
This option removes the EXPORT LOCAL clause that may be included in method declarations in VO code, but is ignored in X# |
AllClassesArePartial |
Partial classes is a mechanism in Vulcan and X# that allows you to split a class over multiple source files. That may be convenient if your classes have become very big or if you want to separate generated code from hand written code (like what the Windows Forms Editor in Visual Studio does). You can choose to make all Xporter classes partial. We have disabled this because there is a (small) performance penalty when you use this. Especially if you have split the Accesses and Assigns from your class over separate files. |
AddMissingConstructors |
VO allows you to declare a class without Init method / Constructor. In .Net this is also allowed., but then the compiler assumes you have a class with a constructor without parameters. This option will automatically generate missing constructors. Note that also the X# compiler supports emitting missing constructors even if they are not specified in the code, when the /vo16 compatibility option is enable. So this Xporter option is not necessary anymore and has been depreciated. |
IgnoreDuplicateDefines |
If you select this then duplicate defines will simply be ignored and not written to the output files. |
Don’tGenerateEmptyFiles |
Each module from your VO application will become a source file in X#. This option will suppress the generation of empty source files |
AdjustCallbackFunctions |
Some (advanced) VO code contains callback functions where the address of a function is passed to another function and will get called. The Windows API uses that a lot, for example for enumerating windows or printers. That mechanism will not work in .Net. This option will change your code and will help you to get a working solution. |
ExportOnlyDefines |
This option allows you to generate a DLL with only the defines from the AEF(s) or files you have selected. That may be useful if you have ported your code before with the Vulcan Transporter and want to get rid of the header files with the defines. |
Sort Entities by name |
This will sort all entities on name, Methods will be sorted inside the CLASS.. ENDCLASS and functions will be sorted as well |
Use XSharp Runtime |
When you select this (the default) then your app will be compiled against the X# runtime. Otherwise we will use the Vulcan runtime (which is not included with our product) |
Copy Resources to Project folder |
When you select this option then all BMP, ICO, CUR etc resources that are used in resource entities in your app will be copied to a Resources subfolder inside your project. |
Replace Resource Defines with Values |
This controls the way that the numeric identifiers associated with menu options and control identifiers on forms are exported to the external resource files |
Check For IVar and Property Conflicts |
In Visual Objects, it is allowed to have ACCESS/ASSIGN methods that have the same name with IVars (usually INSTANCE vars) of the same class. This is not allowed in .Net, so if this option is enabled, the Xporter will detect this and will prefix the IVar names with an underscore ("_"). |
Ignore code inside #ifdef...#endif |
As a means of preparing Visual Objects code to be ported to X#, it is common practice to provide a VO version and a X# version of the same code in the VO version of the source code, surrounded by #ifdef __XSHARP__ ... #else ... #endif preprocessor directives. When this option is set, Xporter does not touch any code that is surrounded by those directives. |
The XPorter will allow you to select a destination folder and names for your Visual Studio solution and project files.
After pressing xPort you will see the following folder s
C:\XporterOutput\Examples\Explorer
C:\XporterOutput\Examples\Explorer\Explorer
C:\XporterOutput\Examples\Explorer\Explorer\Resources
C:\XporterOutput\Examples\Explorer\Explorer\Properties
The first folder is the so called “Solution” folder
The subfolder contains the project and its files.
If you had selected multiple AEF files then each AEF would have its own subfolder under the Solution Folder
The solution folder contains the files:
File |
Contains |
Explorer.sln |
VS Solution file |
Explorer.viproj |
XIDE project file |
The project folder contains the files
File |
Contains |
Customer Explorer.prg |
Module source code |
Data Servers.prg |
Module source code |
Explorer Shell.prg |
Module source code |
Explorer.viapp |
XIDE Application file |
Explorer.xsproj |
VS Project file |
Help About.HelpAboutDialog.rc |
Form resource used by VS |
Help About.HelpAboutDialog.xsfrm |
Form "binary" used by VS |
Help About.prg |
Module source code |
Help About.rc |
Form resource used by XIDE |
Icons.ICONONE.rc |
Icon resource used by VS |
Icons.ICONTWO.rc |
Icon resource used by VS |
Icons.prg |
Module source code |
Icons.rc |
Icon resources used by XIDE |
Menus.CustomerExplorerMenu.rc |
Menu resource used by VS |
Menus.CustomerExplorerMenu.xsmnu |
Menu "binary" |
Menus.CustomerExplorerMenu_Accelerator.rc |
Menu accelerators resource used by VS |
Menus.EMPTYSHELLMENU.rc |
Menu resource used by VS |
Menus.EMPTYSHELLMENU.xsmnu |
Menu binary |
Menus.EMPTYSHELLMENU_Accelerator.rc |
Menu accelerator resource used by VS |
Menus.OrdersListViewMenu.rc |
Menu resource used by VS |
Menus.prg |
Module source code |
Menus.rc |
Menu resources for XIDE |
Start.prg |
Module source code |
To compile and build the project we open the file Explorer.SLN in Visual Studio. Inside Visual Studio it looks like:
The arrows in front of several modules show that there are subitems in these modules. Those subitems contain the Form, Menu and Icon resources.
Now let’s try to build the solution inside Visual Studio. (Menu option Build – Build Solution)
This compiles the application and builds a debuggable version in the c:\XporterOutput\Explorer\Debug folder. You will see that this folder contains an EXE, PDB (debug symbols) and copies of the VO runtime libraries:
Explorer.exe
Explorer.pdb
SDK_Defines.dll
VOGUIClasses.dll
VORDDClasses.dll
VOSystemClasses.dll
VOWin32APILibrary.dll
XSharp.VO.dll
XSharp.RT.dll
XSharp.Core.dll
Now can try to run the app. This works, but as soon as we select the File/Open menu option we will get a runtime error. After some resizing the screen looks similar to this
The error message is clear: the app uses the splitwindow control and this requires the splitwindow support DLL.
This DLL is located in the Redist folder of your VO installation. Simply copy the “Cato3spl.dll” file from your VO Redist folder to the output folder as well as the MSVCRT.DLL and try again.
You can also add the DLLs to your project (Add Existing Item, and point to the DLLs in the Redist folder). This will copy them to the project folder. Then set the build action for the 2 DLLs to None and the “Copy to Output Directory” property to “Preserve Newest”. When you now build your app the DLL will be copied to the right folder.
After that the code will run just like it did in VO with no code changes!
Let’s have a closer look at what the xPorter has done:
•Each module in VO has become a PRG file in the X# project
•Source code has been grouped by class and put in a CLASS .. END CLASS construct
•Init methods have been renamed to CONSTRUCTOR
•Compiler macros such as "%CavoSamplesRootDir%\Explorer\" have been replaced with literal values: "C:\cavo28SP3\Samples\Explorer\"
•Recourses have become “children” of the source file where they were defined
•Locations for resources have also been changed %CavoSamplesRootDir%\Explorer\TWO.ICO has been changed to ICONTWO Icon C:\cavo28SP3\Samples\Explorer\TWO.ICO.
Also the RESOURCE keyword has been removed.
•The binaries for the forms and menus have not been included in this version of the XPorter (Beta 11). That will change.
•The Start file has the biggest change. In VO there was a method in there App:Start(). However the App class is not defined in this application but part of the GUI Classes. There was also no Start function in the App. VO would call the Start function in the GUI classes and would merge the App:Start() method in the application with the rest of the App class in the GUI Classes.
This is not allowed in .Net. Classes cannot be spread over more than one assembly (the .Net name for of a Library, EXE or DLL).
Therefore the XPorter has created a new class (xApp) and moved the Start method to this Xapp class. It has also added a Start() function which instantiates the App class and calls the Start method inside XApp. You can also see in the example below that a TRY .. CATCH .. END TRY construct is added which captures the errors that are not catched anywhere else and shows an error message in an ErrorBox object. This is the errorbox that was shown before because the CATO3SPL.DLL was missing.
•Finally the Start function is marked with an attribute (The word between the square brackets). In this case the attribute is [STAThread] which means that the main function (and therefore the whole app) needs to run in Single Threaded Appartment mode. This is important if your app uses external code such as OCX/ActiveX controls.
-
•If you look closer to the solution explorer in Visual Studio and click on the References node in the tree you will see that the example has references to the Vulcan runtime and the VO Class libraries as well as the SDK defines library that was included with the XPorter.
•If you open the project properties you will see on the General page that the selected dialect is “Visual Object” , on the Dialect page are most VO options are set and on the Build page the platform target is x86 (because the GUI classes are designed to run in x86 mode) and several warnings have been suppressed. These warnings are:
Number |
Meaning |
162 |
Suppresses a warning about Unreachable code |
618 |
Suppresses a warning about the use of obsolete functions, such as CollectForced |
649 |
Suppresses a warning about unused private and/or internal fields. |
9025 |
Suppresses a warning about missing return statements |
9032 |
Suppresses a warning about return values inside ASSIGN methods and/or constructors/destructors |
9043 |
Suppresses a warning about ambiguous code, which could happen if two assemblies define a function with the same name. |
In this particular example only warning 618 is generated by the compiler because the CustomerExplorer:Close() method calls CollectForced. After commenting out that line you can remove all the “suppressed” warnings from the app and it will compile without any warnings.
You will find the "code before" and "code after" in the XSharp Examples folder
