> For the complete documentation index, see [llms.txt](https://docs.gapvelocity.ai/webmap/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gapvelocity.ai/webmap/winforms/extend-or-modify-the-converted-application/conversion-configuration/webmap-configuration-file.md).
# WebMAP configuration file
### WebMAP configuration file
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.
### File content
The following section will explain every section found in the configuration file.
#### Excluded Projects
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 [VBUC ](https://docs.gapvelocity.ai/vbuc/)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.
```xml
9BE0611B-C698-4268-CB56-81D679F07025
```
#### Packages
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](/webmap/general/backend/dcp-desktop-compatibly-platform.md)
* Include Back-end runtime references
* HTML conversion templates
```xml
```
**Compatibility Platforms**
The Compatibility Platforms section includes the [DCP references ](/webmap/general/backend/dcp-desktop-compatibly-platform.md)that will be included directly into the converted application.
{% hint style="warning" %}
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.
{% endhint %}
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).
{% hint style="warning" %}
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.
{% endhint %}
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](https://packages.mobilize.net/feeds/mobilizenet-nuget/Mobilize.Web.BundleBasic.All/versions/all)
```xml
```
#### Visual Components
The Visual Components section includes the [Angular components references ](/webmap/general/frontend/documentation/winforms-angular-components.md)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](https://packages.mobilize.net/feeds/mobilizenet-npm/@mobilize/winforms-components/versions/all)
```xml
```
#### Libraries
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
```html
```
{% hint style="warning" %}
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.
{% endhint %}
{% hint style="warning" %}
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.
{% endhint %}
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](https://packages.mobilize.net/feeds/mobilizenet-nuget/Mobilize.HtmlGenerator.WFNet.All/versions/all)
```xml
```
#### Dependencies
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
```xml
```
#### Additional Dependencies
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.
```xml
```
**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:
```log
type System.ComponentModel.IComponent => Mobilize.WebMap.Common.DCP.IControl;
```
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
{% hint style="info" %}
The path must be relative to the webmap.config file location.
{% endhint %}
```xml
```
#### Additional Parameters
The additional Parameters section handles the configuration of supplementary options regarding to the approach that needs to be used to solve some known situations.
```xml
```
**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
{% hint style="info" %}
The ByRef value can only have one of two values: Off or ByRefWithDynamic
{% endhint %}
```xml
```
**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 ](/webmap/winforms/extend-or-modify-the-converted-application/conversion-configuration/stub-filter.md)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
{% hint style="info" %}
The path must be relative to the webmap.config file location.
{% endhint %}
```xml
```
#### Web Modules
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
```xml
```
#### Web Styles
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
```xml
```
#### Settings
This sections includes different core settings that need to be specified in order to be able to perform the conversion correctly.
```xml
```
**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.
{% hint style="warning" %}
It is highly recommended to always keep the default repository, otherwise, the conversion will not be able to be performed.
{% endhint %}
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
```xml
```
**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.
```xml
```
**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 \ 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
```xml
```
#### **Usings to remove**
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
{% hint style="info" %}
It is possible to include as many namespaces as needed.
{% endhint %}
```xml
```
### How to setup the configuration file
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.
{% file src="/files/08Gj3i5BQwhCiCpgNI21" %}
WebMAP configuration file sample.
{% endfile %}
To perform this follows this steps:
1. Launch the WebMAP conversion UI.
2. Select the configuration button **⚙**.
3. In the **General** tab go to Custom conversion file and select the browse option
Select the modified file
4. Select the Save option
5. Continue with the conversion process
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.gapvelocity.ai/webmap/winforms/extend-or-modify-the-converted-application/conversion-configuration/webmap-configuration-file.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.