Include guide for the ICSharpCode.CodeConverter.Cli tool

vb-migration/complete-converter-guide.md

@@ -0,0 +1,229 @@
+# 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:
+```bash
+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:
+```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):
+```csharp
+public class Calculator
+{
+    public int Add(int a, int b)
+    {
+        return a + b;
+    }
+}
+```
+
+Converted file (test.vb):
+```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:
+```bash
+code-converter convert-project <source-project-file> [-t <target-directory>]
+```
+
+2. Example commands:
+```bash
+# 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):
+```xml
+<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):
+```xml
+<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
+```bash
+# 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