# Get Started Ensure that all projects referenced within the migration solution are set as internal, as this significantlyAfter the VB6 AI Migrator 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. ## Create a VB6 AI Migrator Solution To get started, open the icon created by the installation wizard, which is located on your desktop. When the VB6 AI Migrator tool is executed, it will ask you for permissions. Once you have accepted the request, a splash window will appear with general information about the VB6 AI Migrator tool. ![VBUC Splash window](/files/wkEbkRY0WZp1lVlbeu5r) Once the VB6 AI Migrator tool is loaded, the first screen you will see is the solution tab. ![ VB6 AI Migrator Solution Tab](/files/-Ma-asvqrUEI9QOLQqq3) In this first screen, you can see the side panel on the left of the screen. It shows the current upgrade solution step. Additionally, at the top, you can view the available options to configure the initial steps for upgrading the original project. Click on the New button, the Upgrade Solution Properties window will be opened. ![Upgrade Solution Properties Window](/files/Rs31VZs1lUN8wks38O0H) 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. ### Configure the solution 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](/files/OO6ZrjTTwYcYf8U0Yx1p) {% hint style="info" %} By default, the source code folder will be added to the Binary references folder, but you can add as many as you need. {% endhint %} 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](/files/-MEU6AzIUzOPkee56yII) Now you can see the name of the solution created at the top of the VB6 AI Migrator 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. ![VB6 AI Migrator Solution Tab](/files/-Ma-BXrMsYetV6pfM40x) ### Other options of the Solution tab ![VB6 AI Migrator Solution Tab options](/files/-MEU6AzK8npBIu_T-TuE) 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 VB6 AI Migrator solution. 2. Open - Load a previous VB6 AI Migrator solution stored on your computer. 3. Close - Close a solution to load or create a different one. 4. Save - Save the current VB6 AI Migrator solution. 5. Save As - Save the current VB6 AI Migrator solution with a different name than the one with which it was created. 6. Solution Properties - Opens the solution properties of the current VB6 AI Migrator 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](/files/-MEU6AzL4nw9qsYy08aT) 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. ## Resolve References {% hint style="warning" %} 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. {% endhint %} 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 VB6 AI Migrator 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. {% hint style="info" %} 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. {% endhint %} ![Resolve References Tab](/files/-Ma-WfQuS13B53XVEWlr) 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). {% hint style="info" %} 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. {% endhint %} ### Resolving a reference 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](/files/yTvBYEDQj52HizuOoiqA) 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](/files/iW5jGRII06LjqMFtlN5e) 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](/files/-Ma-X4404gnlYTyFQRAh) ### Include binary reference folders 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](/files/-MILCo1ajZGgUWXAFIhE) You can optionally add directories where referenced components can be found. The VB6 AI Migrator 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](/files/-MILE3epv--xC8JfTGqS) 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. ### Other options of the Resolve References tab ![Analyze Option in the Resolve References tab](/files/-MEU6AzRXAHP-JrHIoNN) 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](/files/-MEU6AzSj2rcHoh_tWt3) 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](/files/-MEU6AzTRn5BUgcvPNR3) 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](/files/fPmyRjcg8kuuI0UY425Z) ## Upgrade Options {% hint style="warning" %} 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. {% endhint %} 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](/files/-Ma-XN_belG3UOsE20qJ) ### .NET Framework 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](/files/-Ma-Ygh1eyFUPL5qpWgI) Once you have confirmed the upgrade options, you will see a green checkmark on the side panel. ### .NET Core / .NET 5 / .NET 6 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](/vbuc/get-started.md#differences-between-net-core-and-net-framework). 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. {% hint style="warning" %} 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. {% endhint %} ![Disable options for .NET Core / .NET 5 / .NET 6](/files/xw4Xk40MS05rQfaPfldS) ### Available options for .NET Core / .NET 5 / .NET 6 and .NET Framework 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 | ### Other options of the Upgrade Options tab ![Upgrade Output options for the Upgrade Options tab](/files/-MEU6Az_3n8lviROuZWN) 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 VB6 AI Migrator 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](/files/-MEU6AzeVvoko0AuIXIP) 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. ![](/files/oNB2qqS3T2HopJ5VvLJI) 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). ## Upgrade Process 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](/files/-Ma-ZDZAkg-cl6o0D7px) ### Starting the process 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](/files/-Ma-ZQOo3T4OMNgmiyAT) 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](/files/dTxJ916zGSmKgD0bqvkf) ### Comparing results We will use a simple code to show you how the VB6 AI Migrator tool works. In the Upgrade Options step, we have chosen the option to upgrade this component to the Native .NET component. #### VB6 Original code This code uses a MSComctl reference. ```php 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 ``` #### C# Upgraded code ```csharp 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(); } } ``` #### VB.Net Upgraded code ```php 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. ### Other options of the Upgrade Process tab ![All projects options](/files/-MEU6Azkd85G_KqPXC4o) 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](/files/-MEU6AzlmBiOGUXz8i7w) 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](/files/S0zgT6dA72eca3HWLBXq) ![Logging options for the upgrade process](/files/-MEU6AznXsRAkoXCVY9U) 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](/files/-MEU6AzolgWIiZXTQZff) 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](/files/-MEU6AzpTO6VVqynnwdN) 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. ## What To Do After The Upgrade Process? Once you have finished with the upgrade process, there are a few things you can do. ![Next Steps Tab with a completed process](/files/dTxJ916zGSmKgD0bqvkf) Not all cases will need manual adjustments, but in case your project needs them, you can schedule a time to talk with an expert using this [link](https://www.gapvelocity.ai/contact). ### Other options of the Next Steps Tab ![Output options in the Next Steps Tab](/files/-MEU6Azs4xcEKiaX0SpQ) 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](/files/-MEU6Azt7g4tleq0KJV4) 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 VB6 AI Migrator. 3. FAQ - Will open a link where you will find the most common technical inquiries about VB6 AI Migrator. ![VBUC options in the Next Steps Tab](/files/-Ma-aR9ED_rb0pGsKE7_) In the image above, you can see the VB6 AI Migrator options. The purpose of the options will be explained below. 1. Quick Start - Will open a link redirecting to this guide. 2. VB6 AI Migrator - Will open a link where you will find the description in full detail of the advanced features present in VB6 AI Migrator. ## Tools ![Options available in Tools section](/files/-MILRgg-nd5xTga-5sfj) The VB6 AI Migrator 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. ### Options of the Tools bar ![Tools available in Tools section](/files/-MILRVzGwu87YrL3g8Z4) 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](/vbuc/features.md#assessment-process). 2\. Collect Support Files - Creates a .zip file containing detailed troubleshooting information about the VB6 AI Migrator execution. This Support information can be interpreted by GAPVelocity AI specialists to diagnose and troubleshoot particular issues. ![Collect Support Files in the Tools tab](/files/gBaaL55dBZNHLfE6UpRP) 3\. Dependency Analyzer - Enables the user to work with the solution and project dependencies. For more information check [Dependency Analyzer tool](/vbuc/features.md#dependency-analyzer). ![License Group in the Tools tab](/files/-MILmYfDX_v_krFSLEQ4) 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](/files/x2VmVP5I9uZAH1OpkixM) 2\. License Info - Show details of the registered license ![License Info screen](/files/DpVahIGGWx6n1kR7fqcF) ## Shortcuts | 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 | --- # Agent Instructions: 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/vbuc/get-started.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.