rc-migration-tests/vb-migration/complete-converter-guide.md

Complete Guide to ICSharpCode.CodeConverter.Cli in VS Code

Prerequisites

1. .NET SDK installed on your system
2. Visual Studio Code
3. C# extension for VS Code (optional but recommended)

Installation

Install the ICSharpCode.CodeConverter.Cli globally using the .NET CLI:

dotnet tool install -g ICSharpCode.CodeConverter.Cli

VS Code Configuration

Basic File Conversion Setup

1. Create a tasks.json file in VS Code:

   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
   • Type "Tasks: Configure Task"
   • Select "Create tasks.json file from template"
   • Choose "Others"

2. Add the following configuration to tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Convert CS to VB",
            "type": "shell",
            "command": "code-converter",
            "args": [
                "convert",
                "${file}",
                "-l",
                "CS2VB"
            ],
            "problemMatcher": []
        },
        {
            "label": "Convert VB to CS",
            "type": "shell",
            "command": "code-converter",
            "args": [
                "convert",
                "${file}",
                "-l",
                "VB2CS"
            ],
            "problemMatcher": []
        },
        {
            "label": "Convert C# Project to VB",
            "type": "shell",
            "command": "code-converter",
            "args": [
                "convert-project",
                "${workspaceFolder}/${input:projectFile}",
                "-l",
                "CS2VB",
                "-t",
                "${workspaceFolder}/Converted"
            ],
            "problemMatcher": []
        },
        {
            "label": "Convert VB Project to C#",
            "type": "shell",
            "command": "code-converter",
            "args": [
                "convert-project",
                "${workspaceFolder}/${input:projectFile}",
                "-l",
                "VB2CS",
                "-t",
                "${workspaceFolder}/Converted"
            ],
            "problemMatcher": []
        }
    ],
    "inputs": [
        {
            "id": "projectFile",
            "type": "promptString",
            "description": "Project file to convert (e.g., MyProject.csproj)"
        }
    ]
}

Usage Instructions

Single File Conversion

1. To convert a single file:

   • Open the file in VS Code
   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
   • Type "Tasks: Run Task"
   • Select either "Convert CS to VB" or "Convert VB to CS"

2. Example C# to VB.NET conversion:

Source file (test.cs):

public class Calculator
{
    public int Add(int a, int b)
    {
        return a + b;
    }
}

Converted file (test.vb):

Public Class Calculator
    Public Function Add(a As Integer, b As Integer) As Integer
        Return a + b
    End Function
End Class

Project Conversion

1. Command line syntax:

code-converter convert-project <source-project-file> [-t <target-directory>]

2. Example commands:

# C# to VB.NET
code-converter convert-project MyProject.csproj -l CS2VB -t ConvertedProject

# VB.NET to C#
code-converter convert-project MyProject.vbproj -l VB2CS -t ConvertedProject

Project File Structures

1. C# Project (.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
  </ItemGroup>
</Project>

2. VB.NET Project (.vbproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <RootNamespace>MyProject</RootNamespace>
    <OptionExplicit>On</OptionExplicit>
    <OptionCompare>Binary</OptionCompare>
    <OptionStrict>Off</OptionStrict>
    <OptionInfer>On</OptionInfer>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
  </ItemGroup>
</Project>

Project Conversion Considerations

1. Project References

• All project references are maintained
• NuGet package references are preserved
• Assembly references are carried over

2. Resource Handling

• .resx files are copied to target directory
• Resource identifiers are adjusted
• app.config and web.config files are preserved

3. Special Conversion Options

# Preserve case when converting to VB.NET
code-converter convert-project MyProject.csproj -l CS2VB -t ConvertedProject --preserve-case

# Skip resources when converting to C#
code-converter convert-project MyProject.vbproj -l VB2CS -t ConvertedProject --skip-resources

Troubleshooting

1. Command Not Found

• Verify .NET tools directory is in PATH
• Close and reopen VS Code
• Check installation with dotnet tool list -g

2. Conversion Failures

• Verify source code compiles
• Check for correct conversion direction
• Review output window for errors

3. Project Conversion Issues

• Verify all references are accessible
• Check framework versions match
• Ensure NuGet packages are restored
• Review namespace conflicts
• Check for language-specific features

4. Post-Conversion Steps

1. Build the converted project
2. Run available tests
3. Review generated code
4. Check resource file accessibility
5. Verify namespace organization

Best Practices

1. Always backup your source code before conversion
2. Test the converted code thoroughly
3. Review language-specific features that might need manual adjustment
4. Keep original and converted projects separate
5. Document any manual changes needed after conversion