WebMAP configuration file
Last updated
Last updated
The WebMAP conversion tool allows the user to customize several conversion parameters, to adjust the output code outcome. This process can be made by loading different customizations into a configuration file called webmap.config.
This section will show the basic concepts that can be handled by the WebMAP configuration file and the needed steps to successfully create a new configuration fitting for the needs of a specific application as well.
The following section will explain every section found in the configuration file.
The excluded section is used to mark a specific project as non-convertible, this means that that specific project will not be converted by the Conversion Tool and will remain the same without any changes in the output project.
This option is typically used for projects that have been converted from VB6 code using the Mobilize's tool, which includes helper projects that do not need to be converted into a web infrastructure.
To exclude a project from the conversion process it needs to be included into the excluded-projects with the following format:
It must be contained in a project tag
It needs to have a name attribute. Its value can be the real project name or a place holder like "unknown"
The project tag value must be the project's GUID
Sample snippet below.
The packages section contains all the configurable references that are needed to properly convert and execute the new application.
It used to control the following conversion steps:
Load default mapping mechanism based on existing DCPs
Include Back-end runtime references
HTML conversion templates
Compatibility Platforms
The Compatibility Platforms section includes the DCP references that will be included directly into the converted application.
It is required to have at least one DCP library in order to be able to perform a code conversion, otherwise the code will not be processed at all.
The Mobilize.Web.BundleBasic library is set a default. The BundleBasic library contains the necessary runtime to be able to execute an application coming directly from Windows Forms with no third-party components. It also contains the default maps that are needed to convert from the Window Forms types (such as System.Windows.Forms.Button) to the Mobilize own types (such as Mobilize.Web.Button).
The order in which the DCP references are placed in the file is important for the map loading process. In case of having a type clash it will prioritize the one that is on top of the list.
To include a new DCP reference use the following format:
Create a package tag into compatibility-platforms tag
It must have an id attribute, which must have the project name
It must have a version attribute which corresponds to the nuget version that can be found in here
The Visual Components section includes the Angular components references that will be included directly into the converted application.
The @mobilize/winforms-components library is set a default. This package contains the necessary runtime to be able to execute an application coming directly from Windows Forms with no third-party components for the front-end application.
To include a new Angular component reference use the following format:
Create a package tag into visual-components tag
It must have an id attribute, which must have the package name
It must have a version attribute which corresponds to the package version that can be found in here
The library section contains the libraries required to correctly create the HTML files for the front-end application. The libraries are referred as HTML Generator projects and provide a set of templates used to create the HTML tags found in a converted application.
The Mobilize.HtmlGenerator.WFNet.All library is set a default. This package contains the necessary templates in order to map a Windows Form control with its corresponding Mobilize Angular component. For Example:
A System.Windows.Forms.Button is converted to
It is required to have at least one HTML Generator library in order to be able to perform a code conversion, otherwise the resulting front-end application will not be executable.
The order in which the HTML Generator references are placed in the file is important for the transformation loading process. In case of having a type clash it will prioritize the one that is on top of the list.
To include a new HTML Generator reference use the following format:
Create a package tag into libraries tag
It must have an id attribute, which must have the project name
It must have a version attribute which corresponds to the nuget version that can be found in here
The dependencies section is used to set any nuget reference that needs to be included directly into the converted project's references, which are included in every C# project found in the original solution, except for excluded projects.
To include a nuget reference use the following format:
Create a package tag into dependencies tag
It must have an id attribute, which must have the project name
It must have a version attribute which corresponds to the nuget version
The additional dependencies sections is mainly used to include type mappings that are needed by the conversion tool in order to be able to resolve the proper type conversion form the Windows Forms type to the Mobilize types that can be commonly found in the DCP libraries provided during the conversion process.
Maps
The Maps attribute is used to indicate were are located the .map files used by the conversion tool to transform from a given type to another one during the conversion process. For example, lets say that a .map files exists including he following information:
Which means that each type a statement of type System.ComponentModel.IComponent is found in the code it will be replaced with the Mobilize.WebMap.Common.DCP.IControl type.
By default the maps applied are the ones that are provided the DCP references provided in the Compatibility Platforms section.
To include custom maps use the following format:
Create a path tag into maps tag
It must have a value attribute, indicating the folder location in which the map files are located
The path must be relative to the webmap.config file location.
The additional Parameters section handles the configuration of supplementary options regarding to the approach that needs to be used to solve some known situations.
ByRef
As part of WebMAP conversion in some case there is the need to modified a project structure, which may create some incompatibilities with the new code.
WebMAP by default converts a class field into a property to be able to track said field state properly, however, this presents an issue related to the conversion of methods that receive parameters by ref, which in many cases may use a field as parameter, however, since said parameter is now a property it will cause a compilation error that has to be handled. For this scenario WebMAP provides a mechanism that deals with this issue by applying a special conversion for those methods.
The by ref conversion is optional and can be turn off by modifying the following:
Create a param tag into additional-parameters tag
It must have an id attribute, with ByRef as its value
It must have a value attribute, indicating whether this this feature is active or turned off
The ByRef value can only have one of two values: Off or ByRefWithDynamic
Stub Filter
A stub is a mechanism created to avoid compilation in converted applications when a non mapped member (it will not be replaced by a Mobilize or user define member) is found in a given source code, when this happens the mechanism creates a new member (class, method, property, event, etc.) based on the original member.
For multiple reasons in some cases it is not desired to create a stub member for a non mapped member, so, for this cases a Stub Filtering mechanism is provided by WebMAP in order to include the members that should not be converted as stubs, but keep its original member instead.
For further configuration please go to this section.
To include custom filters use the following format:
Create a param tag into additional-parameters tag
It must have a param attribute, with StubFilter value
It must have a value, indicating the folder location in which the StubFilter file
The path must be relative to the webmap.config file location.
The Web Modules section includes additional Angular imports that will be included directly into the converted application.
The @mobilize/wfnet-c1-components module is set a default. This package contains the necessary runtime to be able to execute an application coming that includes third-party components that need to referenced independently from the Windows Forms runtime.
To include a new Angular module reference use the following format:
Create a module tag into web-modules tag
It must have a package attribute, which must have the module name
It must have a name attribute, which must have the import module name
The Web Styles section includes additional style imports that will be included directly into the converted application.
To include a new style reference use the following format:
Create a style tag into web-styles tag
It must have a path attribute, which must have the style file's location
This sections includes different core settings that need to be specified in order to be able to perform the conversion correctly.
Package sources
In order to be able to load most of the configurations mentioned above there must be a source repository which is used to host the Mobilize nuget and npm packages used by the conversion process, said repository is set in the package sources section.
By default the packages.mobilize.net repository is used. This setting must be changed only in cases in which any of the above sections contains a nuget package that needs to be obtained from a specific source repository.
It is highly recommended to always keep the default repository, otherwise, the conversion will not be able to be performed.
To include a new style reference use the following format:
Create a package-source tag into package-sources tag
It must have a key attribute, it indicates repository visibility
It must have a value attribute, it indicates the repository URL
Componentizable controls
During the conversion process WebMAP creates an independent Angular component only for Forms and User Controls since they are considered as top container controls, however, Windows Forms has several other container controls such as Tab Controls, Group Boxes, Panels, etc. These containers are transformed into regular Angular Components that are contained as part of a User Control o Form component, in some cases there is a need to create an independent component for any specific control container. That information is handled by the Componentizable controls section.
The image below shows the final result of the conversion of a Form containing a Tab Control without the componentization featured enabled.
The image below shows the same Form with the componentization feature enabled. In this case instead of creating just one component for the the Form it creates two, one for the Form and other for the Tab Control.
Create a control tag into componentizable-controls tag
It must have a key attribute, it indicates the control's fully qualified name.
Search visual generator parents
WebMAP generate Angular components for an application's controls purely based on their original type. which means that if there is a DataGridView it will get transformed into a <wm-data-grid-view> component which is already implemented as part of the basic WebMAP components, but, in the case of having a control that inherits from the grid - lets say for example MyGridView control - the conversion tool will generate another component <my-grid-view> that is not related to the its base component. WebMAP provides a mechanism to change the type of a the generated component in order change the original type with its base in case no other map is found for it. This configuration can be set in the Search visual generator parents section.
The image below shows the conversion result of a control that inherits from Windows Forms native control, the generated Angular component is directly associated to the control type, so, the resulting component for the MyGrid type would be MyGridComponent which may need to be implemented independently from its base type.
The image below shows the conversion result of the same control as above that inherits from a Data Grid View is converted as Data Grid View Component instead of using a new component created for this specific control type.
To include a componentizable control use the following format:
Create an include tag into search-visual-generator-parents tag
It must have an all attribute set to true, to turn the feature on an treat all control inheritance with this feature.
Create an exclude tag into search-visual-generator-parents tag
It must have a control attribute with the fully qualified name of the control that needs to be excluded form this feature
By default the conversion tool keeps the original using references declared for each class file, however, in some occasions removing some of those usings may be needed in order to warranty the new code to be able to compile correctly, for these scenarios there is an usings to remove section which allow to set a list of namespaces that will be excluding from the converted code.
To include a exclude a namespace form the code usings use the following format:
Create a using tag into usings-to-remove tag
It must have an namespace attribute, which must have the namespace name
It is possible to include as many namespaces as needed.
To load a custom configuration a modified version of the webmap.config file needs to be added to the WebMAP wizard in order to be able to apply the new settings.
A sample webmap.config file is attached below.
To perform this follows this steps:
Launch the WebMAP conversion UI.
Select the configuration button ⚙.
In the General tab go to Custom conversion file and select the browse option
Select the modified file
Select the Save option
Continue with the conversion process
