Get Started
In the following section, you will find a detailed description of each phase of the VBUC Tool.
After the VBUC tool is installed and activated, you can use it to upgrade VB6 or ASP projects. To do this, it is highly recommended that you follow the next steps to get the maximum benefits from the Visual Basic Upgrade Companion.
To get started, you need to open the icon created by the installation wizard, located on your desktop.
When the VBUC tool is executed, it will ask you for permissions. Once you have accepted the request, it will show a splash window with the general information about the VBUC tool.
VBUC Splash window
Once the VBUC tool is loaded, the first screen you will see is the solution tab.
VBUC Solution Tab
In this first screen, you can see the side panel on the left of the screen. It shows the current upgrade solution step. Also, at the top, you can see the available options to configure the initial steps to upgrade the original project.
Click on the New button, the Upgrade Solution Properties window will be opened.
Upgrade Solution Properties Window
The previous window will show the basic properties of the solution:
- 1.The name of the solution to be created.
- 2.The source path, where the VB6 or ASP code is located.
- 3.The output path, where the upgraded code will be saved.
- 4.Binary references folder, where the binaries needed by the solution are located.
Once you have selected the original project, the source code path will appear in the text area. The output path will be generated based on the source code path, but you can change it to the path of your choice.
Upgrade Solution Properties Window filled after a project was selected
By default, the source code folder will be added to the Binary references folder, but you can add as many as you need.
Once the basic properties are defined, click on the OK button. A window will be shown, indicating the output path does not exist and it will be created. Click on the Yes button to create it and continue with the next steps.
Invalid directory message
Now you can see the name of the solution created at the top of the VBUC tool, the project or projects contained by the original project listed in the working area, and a green checkmark in the Solution step in the side panel.
VBUC Solution Tab
VBUC Solution Tab options
In the image above, you can see the solution options. The purpose of the previous options will be explained below.
- 1.New - Create a new VBUC solution.
- 2.Open - Load a previous VBUC solution stored on your computer.
- 3.Close - Close a solution to load or create a different one.
- 4.Save - Save the current VBUC solution.
- 5.Save As - Save the current VBUC solution with a different name than the one with which it was created.
- 6.Solution Properties - Opens the solution properties of the current VBUC solution.
- 7.Refresh - If you have made a change in the original project, you can refresh the current solution to have the latest changes without creating a new one.
Project Options in the solution tab
In the image above, you can see the selected project options. The purpose of the previous options will be explained below.
- 1.Add Project - With this option, you can add a new VB6 or ASP project to the current solution.
- 2.Remove Project - Once you have selected a project, you can remove it from the current solution.
- 3.Open Container Folder - When you select a project, you can use this option to open the project location folder in the explorer.
If there is a warning in the Resolve References option located in the side panel, you must complete the following steps. Otherwise, you can skip this section.
For the next step, you need to move to the Resolve References tab. In this tab, you can see the Reference List in the center and the available options at the top. References Used By is a panel with the name of projects which are using the selected reference, and is located at the right of the screen. The Type column indicates whether a reference is classified as internal (a project within the migration solution) or external (a third-party library). Make sure that all projects referenced within the migration solution are set as internal because this greatly impacts the output code quality. The VBUC will try to automatically mark as many internal references as possible, but sometimes, because of broken binary compatibility, it is not possible to reliably determine if a given binary is produced by an internal vb6 project. Therefore, some manual interaction might be needed.
At the bottom of the screen, you can see the Binary Folders, which is a list of folders where the references are being searched. Above this, the Unresolved CreateObjects panel will show statements to create an object for which we are unable to determine the type because the reference cannot be found, or it is using a variable or expression to create an object instead of a string.
You can skip this section even if you have a CreateObject error, but it will affect the upgraded code and may cause compilation or runtime errors.
Resolve References Tab
If a reference cannot be determined automatically, then you can use the Analyze References button to try to determine which references are missing. Once you have the missing references on the screen, you need to add it manually. There are two different ways to add a reference:
- 1.Internal, you can set the reference to another project.
- 2.External, you can set the reference to a type library file in your computer (.exe, .tlb, .dll, .ocx).
You just need to resolve a reference once, even if you have multiple projects referencing it, but you need to resolve all the missing references to continue.
To resolve a reference you just need to select it, then click on the option Set Reference Manually at the top of the current tab or right-click on the reference to be resolved and click on the option Set Reference Manually. After you have selected a reference to resolve, a window will be shown.
Locate Component Window
Click on the Browse button and search for the directory where the type library file is located, then select the respective file. If the file is correct, the reference's information will be loaded and shown in the Locate Component window.
Locate component window filled after a reference file was selected
Once you have selected the file to resolve the reference, click on the OK button to close the Locate Component window. Now you can see all the references with a green checkmark.
Resolve References Tab with all references resolved
At the bottom of the "Resolve References" screen, we find the Binary Folders section, which shows the paths where the binary components are located.
Include binary reference folders section
You can optionally add directories where referenced components can be found. The VBUC will try to resolve references automatically to components found in these folders.
By default, the source path is included in this section; it is recommended that you leave this directory in the list.
Include binary reference folders buttons
In the image above, you can see the Binary Reference options. The purpose of the previous options will be explained below:
- 1.Add Binary Folder - This option allows to include a directory to consider more references.
- 2.Remove Binary Folder - This option allows to remove a directory from Binary Folders.
Analyze Option in the Resolve References tab
In the image above, you can see the Analyze option. This option analyzes the references in the project and tries to determine what those references are.
References Options in the Resolve References tab
In the previous one, you can see the references option. This option allows the user to set a reference manually.
Unresolved CreateObjects Options in the Resolve References tab
In the image above, you can see the unresolved create objects options. The purpose of the previous options will be explained below:
- 1.Set Reference Manually - This allows you to set a reference manually for a CreateObject error (same function as the reference).
- 2.Open Code Section - A screen will be shown highlighting the error section. As shown in the image below about the code section.
- 3.Open VB6 Project - The original project will be opened using Visual Basic 6.
Code section window with the create object error
This section could be the most important when you want to upgrade a VB6 or ASP project. Here you can choose the different options to upgrade code, and each option can generate different outputs.
For the next step, you need to move to the Upgrade Options tab. In this tab, you can see, at the center of the screen, the features that you can select. You can change the options list to see the features that you are using or the full list by changing the option at the right of the screen, and the different options associated with this tab at the top of the screen.
Upgrade Options Tab
To upgrade to .NET Framework you just need to select the target language, the Visual Studio version, the .NET platform, and the helpers integration. All of these options are located at the top of the screen. Once you have selected these options, you can confirm the upgrade options selected by default by clicking on the Confirm Options button, or you can change the options according to your needs.
You can click the combo box of any option to see which options it has and select the one you wish to use.
Selecting an option for an upgrade option
Once you have confirmed the upgrade options, you will see a green checkmark on the side panel.
To upgrade to .NET Core or .NET 5 / .NET 6 you need to select that option in the .NET Platform combo box at the top of the screen, as you can see in the next section. If you choose .NET Core you can only upgrade to C# as the target language. If you have selected VB.NET as the target language, the .NET Core option will not be available in the .NET Platform combo box.
Some upgrade options will be disabled due to their incompatibility with .NET Core / .NET 5 / .NET 6 and you will not be able to use them. In those cases, if there is not any other option available, you only can use the option To COM Interop.
Disable options for .NET Core / .NET 5 / .NET 6
The following table shows the different options available between upgrading to .NET Core / .NET 5 vs .NET Framework.
Platform | Target language | Visual Studio version | Helpers Integration |
.NET Framework | C#, VB.NET | 2010, 2012, 2013, 2015, 2017, 2019, 2022 | Binary, NuGet, Source Code |
.NET Core | C# | 2019, 2022 | NuGet, Source Code |
.NET 5 | C#, VB.NET | 2019, 2022 | NuGet, Source Code |
.NET 6 | C#, VB.NET | 2019, 2022 | NuGet, Source Code |
Upgrade Output options for the Upgrade Options tab
In the image above, you can see the Upgrade Output options. The purpose of the options will be explained below:
- 1.Target Language - With this option you can select which language you want for the output code.
- C#
- VB.NET
- 2.Visual Studio Version - This option allows you to select a specific Visual Studio version.
- 2010
- 2012
- 2013
- 2015
- 2017
- 2019
- 2022
- 3..NET Platform - This option allows you to select the platform for which the code will be generated. Depending on the Visual Studio version selected previously, there can be more options available. In the table below we can find the platform versions that can be selected depending on the version of Visual Studio. Important: If VB.NET was chosen as the target language .NET Core 3.1 will not be available as an option.
- 4.Helpers Integration - You can select what kind of integration you want to have with the helpers generated by the VBUC tool.
- Source code - The helpers will be added as code allowing the user to modify them.
- Binary - The helpers will be added as binary files. The user can't modify them.
- NuGet - The helpers will be added as a package, allowing the user to change their version but not the code.
Important: The NuGet option is only available for using Visual Studio 2019 or Visual Studio 2022.
.NET Platform | Visual Studio 2010 | Visual Studio 2012 | Visual Studio 2013 | Visual Studio 2015 | Visual Studio 2017 | Visual Studio 2019 | Visual Studio 2022 |
.NET Framework 4.0 | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ |
.NET Framework 4.5.2 | | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ |
.NET Framework 4.7 | | | ☑ | ☑ | ☑ | ||
.NET Framework 4.7.2 | | | | ☑ | ☑ | ||
.NET Framework 4.8 | | | | | ☑ | ☑ | |
.NET Core 3.1 | | | | | | ☑ | ☑ |
.NET 5 | | | | | | ☑ | ☑ |
.NET 6 | | | | | | | ☑ |
Upgrade Options Management
In the image above, you can see the Upgrade Options Management options. These options will be explained below.
- 1.Current Option - You can select a default profile or a custom profile previously created. The default profiles available are:
- More Automation - This profile will select the options to avoid the greatest number of errors.
- More DotNet - This profile will select the options which generate more .NET code.
- Skeletons - This profile will create the skeletons or shells of each method/function, but the code inside them will not be generated.
- Standard - This profile will select the default options for each reference and code conversion feature.
- WebMAP - This profile is used for a double-jump to Angular, using the options to offer a better conversion from C# to Angular.
- 2.New - Will let you create a new upgrade option profile based on one of the default profiles. A window will be shown, where you can choose the name and the base of the new profile.
- 1.Reset - Will reset the changes in the upgrade options to the default of the selected profile.
- 2.Load - It allows the user to load a custom profile (.option file) previously created.
- 3.Save as - It allows the user to save the changes in the current profile (.option file).
On this screen, you will start the upgrade process with the upgrade options previously chosen.
For the next step, you need to move to the Upgrade tab. In this tab, you can see the options related to the upgrade process at the top of the screen, the Process Checklist and Overall conversion Process below the options, and the Progress by Project and by Files.
Upgrade Process Tab
This section will be the easiest. To start the upgrade process you only need to click on the Upgrade Projects button at the top left of the screen. You can change the Logging Level by selecting the option in the combo box and, also, you can change the Parallel Migration option. While the projects are being upgraded you can see the Preprocess and the Upgrade processes progress.
- Preprocess: The preprocess phase will gather and save general information about each project and how its components will be upgraded. This will generate temporary information that will be used during the Upgrade phase to decide how to convert references between projects. It should not be deleted if more upgrades are going to be executed.
- Upgrade: The upgrade phase parses the VB6 and ASP files, converts them through several transformation steps, and then writes the equivalent .NET files. To properly convert references between projects, the preprocessing phase must have been executed successfully for all the involved projects.
Upgrade process started
Once the process is completed with no errors and the Overall Progress is 100%, you can see a green check mark in the Upgrade option located in the side panel, and the Next Steps tab will be shown with a Migration Summary, that summary show some details of the previous process.
Migration summary when upgrade process is completed
We will use a simple code to show you how the VBUC tool works. In the Upgrade Options step, we have chosen the option to upgrade this component to the Native .NET component.
This code uses a MSComctl reference.
Private Sub Toolbar1_ButtonClick(ByVal Button As MSComctlLib.Button)
If Button.Key = "message" Then
MsgBox "Hello World!"
ElseIf Button.Key = "text" Then
Label1.Caption = "Hello World!"
ElseIf Button.Key = "close" Then
Unload Me
End If
End Sub
private void Toolbar1_ButtonClick(Object eventSender, EventArgs eventArgs)
{
ToolStripItem Button = (ToolStripItem) eventSender;
if (Button.Name == "message")
{
MessageBox.Show("Hello World!", AssemblyHelper.GetTitle(System.Reflection.
Assembly.GetExecutingAssembly()));
}
else if (Button.Name == "text")
{
Label1.Text = "Hello World!";
}
else if (Button.Name == "close")
{
this.Close();
}
}
Private Sub Toolbar1_ButtonClick(ByVal eventSender As Object, ByVal eventArgs As EventArgs)
Handles Toolbar1_Buttons_Button1.Click, Toolbar1_Buttons_Button2.Click,
Toolbar1_Buttons_Button3.Click
Dim Button As ToolStripItem = CType(eventSender, ToolStripItem)
If Button.Name = "message" Then
MessageBox.Show("Hello World!", My.Application.Info.Title)
ElseIf Button.Name = "text" Then
Label1.Text = "Hello World!"
ElseIf Button.Name = "close" Then
Me.Close()
End If
End Sub
As you can see, the upgraded and original code are equivalent, but with their respective syntax.
All projects options
In the image above, you can see the All Projects options. The purpose of the options will be explained below.
- 1.Upgrade Projects - Starts the original project upgrade process to the .NET equivalent.
- 2.Preprocess - This is an information collection phase. In this phase, the general information about each project and how its components will be upgraded is saved. This information will be used later in the upgrade phase.
- 3.Stop upgrade - Stops the current process.
Selected Projects options
In the image above, you can see the Selected Projects options. The purpose of the options will be explained below.
- 1.Upgrade Selection - If a project is selected from the list, it will be the only project to be upgraded.
- 2.Preprocess Selection - If a project is selected from the list, the preprocess will be executed for this project only.
- 3.Generate Sln file - Generates a solution file for a specific selection of projects.
Generate Sln File window
Logging options for the upgrade process
In the image above, you can see the Logging Level option. There are four levels, which will be explained in the following table.
Level | Description |
Debug | Highly detailed tracing used by application developers (default option) |
Info | Informational messages that might make sense to end users and system managers, and highlight the progress of the application |
Warning | Potentially harmful situations of interest to end users or system managers that indicate potential problems |
Error | Error events of considerable importance that will prevent normal program execution, but might still allow the application to continue running |
Upgrade Output options for the upgrade process
In the image above, you can see the Upgrade Output options. The purpose of the options will be explained below.
- 1.Open Preprocess Path - The preprocess path will be opened in the explorer.
- 2.Open Output Path - The output path will be opened in the explorer.
- 3.Open Upgrade Report - If a project is selected, the upgrade report file will be opened. It shows the status and upgraded project products.
- 4.Open Upgrade Log - The upgrade log for the full process will be opened.
Parallel Migration option for the upgrade process
In the image above, you can see the Parallel Migration option. This option allows the upgrade process to work with multiple projects at the time, reducing the upgrade process' execution time.
Once you have finished with the upgrade process, there are a few things you can do.
Next Steps Tab with a completed process
Output options in the Next Steps Tab
In the image above, you can see the Output options. This will open the path where the generated code was saved.
Knowledge Base options in the Next Steps Tab
In the image above, you can see the Knowledge Base options. The purpose of the options will be explained below.
- 1.EWIs - Will open a link with the Error, Warning, Issues information messages.
- 2.How To - Will open a link where you will find extended technical articles with tips and tricks that will help you take full advantage of the Visual Basic Upgrade Companion.
- 3.FAQ - Will open a link where you will find the most common technical inquiries about Visual Basic Upgrade Companion.
VBUC options in the Next Steps Tab
In the image above, you can see the VBUC options. The purpose of the options will be explained below.
- 1.Quick Start - Will open a link redirecting to this guide.
- 2.VBUC - Will open a link where you will find the description in full detail of the advanced features present in Visual Basic Upgrade Companion.
Options available in Tools section
The VBUC offers tools that give you the possibility to evaluate, diagnose, and analyze migrated projects and solutions. In addition, we provide options to verify and check the details of the registered license.
Tools available in Tools section
In the image above, you can see the Knowledge Base options. The purpose of the options will be explained below.
1. Assessment - Performs an evaluation for the upgraded projects. For more information check Assessment Process.
2. Collect Support Files - Creates a .zip file containing detailed troubleshooting information about the VBUC execution. This Support information can be interpreted by Mobilize.Net specialists to diagnose and troubleshoot particular issues.
Collect Support Files in the Tools tab
3. Dependency Analyzer - Enables the user to work with the solution and project dependencies. For more information check Dependency Analyzer tool.
License Group in the Tools tab
In the image above, you can see the group that enables the user to check the license details. The purpose of the options will be explained below.
1. License Registration - Show the License Registration window.
Activate your VBUC License - License Activation Window
2. License Info - Show details of the registered license
License Info screen
Action | Key |
New | CTRL + N |
Open | CTRL + O |
Close Solution | CTRL + K |
Add an ASP Project | CTRL + A |
Add a VB6 Project | CTRL + V |
Solution Properties | CTRL + P |
Save | CTRL + S |
Save As | CTRL + ALT + S |
Upgrade | F5 |
Refresh | F6 |
Help | F1 |
Last modified 1yr ago