Add extension management documentation and utilities

- Add EXTENSION_MANAGEMENT.md with detailed instructions for: - Manual installation steps - Uninstalling previous versions - Troubleshooting common issues - Finding extension installation paths - Using PowerShell script for cleanup - Add cleanup-and-reinstall.ps1 PowerShell script for: - Automated cleanup of extension directories - Restarting devenv /updateconfiguration - Rebuilding and reinstalling extension - Simplifies development workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-26 23:51:46 -04:00
parent 1cbfba3893
commit 89a349ae72
2 changed files with 628 additions and 0 deletions
--- a/RoslynBridge/EXTENSION_MANAGEMENT.md
+++ b/RoslynBridge/EXTENSION_MANAGEMENT.md
@@ -0,0 +1,291 @@
+# RoslynBridge Extension Management Guide
+
+Quick reference for managing the RoslynBridge Visual Studio extension.
+
+## Common Issues
+
+### "Extension Already Installed" but Not Visible
+
+This happens when Visual Studio's extension cache is out of sync. Use the cleanup script:
+
+```powershell
+cd C:\Users\AJ\Desktop\RoslynBridge\RoslynBridge
+.\cleanup-and-reinstall.ps1
+```
+
+## Scripts
+
+### cleanup-and-reinstall.ps1
+
+Automates extension cleanup and reinstallation.
+
+**Basic Usage:**
+
+```powershell
+# Clean and reinstall everything (default)
+.\cleanup-and-reinstall.ps1
+
+# Only clean (remove extension and cache)
+.\cleanup-and-reinstall.ps1 -Action Clean
+
+# Only reinstall (skip cleanup)
+.\cleanup-and-reinstall.ps1 -Action Reinstall
+
+# Reinstall without rebuilding (use existing VSIX)
+.\cleanup-and-reinstall.ps1 -Action Reinstall -SkipBuild
+```
+
+**What it does:**
+
+1. **Closes Visual Studio** - Ensures no file locks
+2. **Cleans Cache** - Removes extension metadata cache
+3. **Removes Extension** - Deletes installed extension files
+4. **Rebuilds** - Compiles the extension in Release mode
+5. **Reinstalls** - Installs the new VSIX
+6. **Verifies** - Checks installation succeeded
+
+## Manual Management
+
+### Check if Extension is Installed
+
+```powershell
+# Check extension folder
+Test-Path "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ulxnn4r3.rql"
+
+# View extension files
+ls "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ulxnn4r3.rql"
+```
+
+### Manual Cleanup
+
+```powershell
+# Close Visual Studio first!
+
+# Remove cache files
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadataCache.sqlite" -Force
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadata.mpack" -Force
+
+# Remove extension
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ulxnn4r3.rql" -Recurse -Force
+
+# Remove component cache (optional, full reset)
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\ComponentModelCache" -Recurse -Force
+```
+
+### Manual Build
+
+```powershell
+cd C:\Users\AJ\Desktop\RoslynBridge\RoslynBridge
+
+# Build using MSBuild
+& "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" `
+    RoslynBridge.csproj `
+    /t:Rebuild `
+    /p:Configuration=Release `
+    /v:minimal
+```
+
+### Manual Install
+
+```powershell
+# Find the VSIX
+$vsixPath = (Get-ChildItem -Path . -Filter "*.vsix" -Recurse | Where-Object {
+    $_.FullName -like "*\bin\Release\*"
+} | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName
+
+# Install using VSIXInstaller
+& "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\VSIXInstaller.exe" `
+    /quiet `
+    /admin `
+    $vsixPath
+```
+
+## Testing the Extension
+
+### 1. Check Visual Studio Extensions UI
+
+1. Open Visual Studio
+2. Go to **Extensions → Manage Extensions**
+3. Click **Installed** tab
+4. Look for "Roslyn Bridge"
+
+### 2. Test HTTP Endpoint
+
+```powershell
+# Health check
+curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"
+
+# Get projects
+curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d '{"queryType":"getprojects"}'
+```
+
+### 3. Check Output Window
+
+In Visual Studio:
+1. Open **View → Output**
+2. Select "RoslynBridge" from the dropdown
+3. Should see startup messages when opening a solution
+
+### 4. Check Event Viewer (if issues)
+
+1. Open Event Viewer
+2. Navigate to: **Windows Logs → Application**
+3. Filter by Source: "VSPackage"
+4. Look for RoslynBridge-related messages
+
+## Debugging
+
+### Extension Won't Load
+
+**Symptoms:**
+- Extension shows in "Installed" but HTTP endpoint doesn't work
+- No output in RoslynBridge Output window
+
+**Solutions:**
+
+1. **Check Extension Loading:**
+   ```powershell
+   # In Visual Studio, open Developer PowerShell
+   Get-VSPackage | Where-Object { $_.Name -like "*Roslyn*" }
+   ```
+
+2. **Enable Diagnostic Logging:**
+   - Run Visual Studio with: `devenv.exe /log`
+   - Check log at: `%APPDATA%\Microsoft\VisualStudio\17.0_XXXXX\ActivityLog.xml`
+
+3. **Reset Visual Studio:**
+   ```cmd
+   devenv.exe /ResetSettings
+   ```
+
+### Port 59123 Already in Use
+
+```powershell
+# Check what's using the port
+netstat -ano | findstr :59123
+
+# Kill the process if needed
+taskkill /PID <PID> /F
+```
+
+### Extension Loads But Crashes
+
+Check the ActivityLog:
+```powershell
+# Open ActivityLog with formatting
+code "$env:APPDATA\Microsoft\VisualStudio\17.0_875bdf7a\ActivityLog.xml"
+```
+
+Look for entries with:
+- `Type="Error"`
+- `Source="RoslynBridge"`
+
+## Development Workflow
+
+### Quick Iteration During Development
+
+```powershell
+# 1. Make code changes
+
+# 2. Quick reinstall (no need to close VS manually)
+.\cleanup-and-reinstall.ps1
+
+# 3. Open Visual Studio and test
+```
+
+### Debugging the Extension
+
+1. Open the RoslynBridge solution in Visual Studio
+2. Set breakpoints in your code
+3. Press **F5** (or Debug → Start Debugging)
+4. This launches a new "Experimental Instance" of VS
+5. Open a solution in the experimental instance
+6. Breakpoints will hit in the original VS instance
+
+### Testing in Production VS (Not Experimental)
+
+```powershell
+# Install in production VS
+.\cleanup-and-reinstall.ps1
+
+# Attach debugger from another VS instance
+# 1. Open a second Visual Studio
+# 2. Debug → Attach to Process
+# 3. Select "devenv.exe" (the first VS)
+# 4. Set breakpoints in the RoslynBridge code
+```
+
+## Uninstalling
+
+### Complete Removal
+
+```powershell
+# Use the cleanup script
+.\cleanup-and-reinstall.ps1 -Action Clean
+
+# OR manually remove via Extensions Manager
+# 1. Open Visual Studio
+# 2. Extensions → Manage Extensions
+# 3. Find "Roslyn Bridge"
+# 4. Click "Uninstall"
+# 5. Restart Visual Studio
+```
+
+### Remove All Traces
+
+```powershell
+# Remove extension
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ulxnn4r3.rql" -Recurse -Force
+
+# Remove all VS caches (nuclear option)
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\ComponentModelCache" -Recurse -Force
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadataCache.sqlite" -Force
+Remove-Item "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadata.mpack" -Force
+
+# Reset Visual Studio
+devenv.exe /ResetSettings
+```
+
+## Troubleshooting Quick Reference
+
+| Issue | Solution |
+|-------|----------|
+| Extension not visible in UI | `.\cleanup-and-reinstall.ps1` |
+| "Already installed" error | `.\cleanup-and-reinstall.ps1 -Action Clean` then reinstall |
+| Port 59123 not responding | Check extension loaded in Output window |
+| VS won't close | Use Task Manager to end `devenv.exe` |
+| Build fails | Check MSBuild output, ensure .NET SDK installed |
+| Install fails | Run as Administrator, check VSIXInstaller.exe exists |
+| Extension crashes on load | Check ActivityLog.xml for errors |
+
+## File Locations Reference
+
+```
+Extension Installation:
+C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ulxnn4r3.rql\
+
+Cache Files:
+C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadataCache.sqlite
+C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\Extensions\ExtensionMetadata.mpack
+C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a\ComponentModelCache\
+
+Activity Log:
+C:\Users\AJ\AppData\Roaming\Microsoft\VisualStudio\17.0_875bdf7a\ActivityLog.xml
+
+Build Output:
+C:\Users\AJ\Desktop\RoslynBridge\RoslynBridge\bin\Release\
+
+VSIX File:
+C:\Users\AJ\Desktop\RoslynBridge\RoslynBridge\bin\Release\RoslynBridge.vsix
+```
+
+## Getting Help
+
+If issues persist:
+
+1. Check the ActivityLog.xml for detailed error messages
+2. Run Visual Studio with logging: `devenv.exe /log`
+3. Check Windows Event Viewer for crashes
+4. Try the "nuclear option": Complete removal + reinstall
+5. Check that .NET Framework 4.8 is installed
+6. Ensure Visual Studio 2022 Community/Pro/Enterprise (17.0+)
--- a/RoslynBridge/cleanup-and-reinstall.ps1
+++ b/RoslynBridge/cleanup-and-reinstall.ps1
@@ -0,0 +1,337 @@
+#Requires -Version 5.0
+
+<#
+.SYNOPSIS
+    Cleanup and reinstall the RoslynBridge Visual Studio extension
+
+.DESCRIPTION
+    This script automates the process of:
+    1. Closing Visual Studio
+    2. Removing the extension cache
+    3. Deleting the installed extension
+    4. Rebuilding and reinstalling the extension
+
+.PARAMETER Action
+    The action to perform: Clean, Reinstall, or Both (default)
+
+.PARAMETER SkipBuild
+    Skip the build step when reinstalling
+
+.EXAMPLE
+    .\cleanup-and-reinstall.ps1
+    Cleans and reinstalls the extension
+
+.EXAMPLE
+    .\cleanup-and-reinstall.ps1 -Action Clean
+    Only removes the extension and cache
+
+.EXAMPLE
+    .\cleanup-and-reinstall.ps1 -Action Reinstall -SkipBuild
+    Reinstalls without rebuilding (uses existing VSIX)
+#>
+
+param(
+    [Parameter(Mandatory=$false)]
+    [ValidateSet("Clean", "Reinstall", "Both")]
+    [string]$Action = "Both",
+
+    [Parameter(Mandatory=$false)]
+    [switch]$SkipBuild
+)
+
+$ErrorActionPreference = "Stop"
+
+# Colors for output
+function Write-ColorOutput {
+    param(
+        [string]$Message,
+        [string]$Color = "White"
+    )
+    Write-Host $Message -ForegroundColor $Color
+}
+
+function Write-Step {
+    param([string]$Message)
+    Write-ColorOutput "`n>>> $Message" "Cyan"
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-ColorOutput "    ✓ $Message" "Green"
+}
+
+function Write-Warning {
+    param([string]$Message)
+    Write-ColorOutput "    ⚠ $Message" "Yellow"
+}
+
+function Write-ErrorMsg {
+    param([string]$Message)
+    Write-ColorOutput "    ✗ $Message" "Red"
+}
+
+# Configuration
+$VSInstancePath = "C:\Users\AJ\AppData\Local\Microsoft\VisualStudio\17.0_875bdf7a"
+$ExtensionsPath = Join-Path $VSInstancePath "Extensions"
+$ExtensionFolder = "ulxnn4r3.rql"
+$ExtensionFullPath = Join-Path $ExtensionsPath $ExtensionFolder
+$ProjectPath = $PSScriptRoot
+$SolutionFile = Join-Path $ProjectPath "RoslynBridge.csproj"
+
+Write-ColorOutput "`n========================================" "Cyan"
+Write-ColorOutput "  RoslynBridge Extension Manager" "Cyan"
+Write-ColorOutput "========================================`n" "Cyan"
+
+# Step 1: Close Visual Studio
+function Stop-VisualStudio {
+    Write-Step "Closing Visual Studio..."
+
+    $vsProcesses = Get-Process | Where-Object { $_.Name -like "devenv*" }
+
+    if ($vsProcesses) {
+        Write-ColorOutput "    Found $($vsProcesses.Count) Visual Studio instance(s) running" "Gray"
+
+        foreach ($proc in $vsProcesses) {
+            try {
+                Write-ColorOutput "    Closing Visual Studio (PID: $($proc.Id))..." "Gray"
+                $proc.CloseMainWindow() | Out-Null
+                Start-Sleep -Seconds 2
+
+                if (!$proc.HasExited) {
+                    Write-ColorOutput "    Force closing..." "Gray"
+                    $proc.Kill()
+                    Start-Sleep -Seconds 1
+                }
+
+                Write-Success "Visual Studio closed"
+            }
+            catch {
+                Write-Warning "Failed to close Visual Studio: $_"
+            }
+        }
+
+        # Wait for processes to fully terminate
+        Start-Sleep -Seconds 3
+    }
+    else {
+        Write-Success "Visual Studio is not running"
+    }
+}
+
+# Step 2: Clean extension and cache
+function Clear-ExtensionCache {
+    Write-Step "Cleaning extension cache..."
+
+    $filesToDelete = @(
+        (Join-Path $ExtensionsPath "ExtensionMetadataCache.sqlite"),
+        (Join-Path $ExtensionsPath "ExtensionMetadata.mpack"),
+        (Join-Path $VSInstancePath "ComponentModelCache")
+    )
+
+    foreach ($file in $filesToDelete) {
+        if (Test-Path $file) {
+            try {
+                Remove-Item $file -Recurse -Force -ErrorAction Stop
+                Write-Success "Deleted: $(Split-Path $file -Leaf)"
+            }
+            catch {
+                Write-Warning "Could not delete $file: $_"
+            }
+        }
+        else {
+            Write-ColorOutput "    Skipped (not found): $(Split-Path $file -Leaf)" "Gray"
+        }
+    }
+}
+
+function Remove-InstalledExtension {
+    Write-Step "Removing installed extension..."
+
+    if (Test-Path $ExtensionFullPath) {
+        try {
+            Remove-Item $ExtensionFullPath -Recurse -Force -ErrorAction Stop
+            Write-Success "Extension removed: $ExtensionFolder"
+        }
+        catch {
+            Write-ErrorMsg "Failed to remove extension: $_"
+            return $false
+        }
+    }
+    else {
+        Write-Success "Extension not installed"
+    }
+
+    return $true
+}
+
+# Step 3: Build the extension
+function Build-Extension {
+    Write-Step "Building RoslynBridge extension..."
+
+    if (!(Test-Path $SolutionFile)) {
+        Write-ErrorMsg "Solution file not found: $SolutionFile"
+        return $false
+    }
+
+    Write-ColorOutput "    Building in Release mode..." "Gray"
+
+    try {
+        # Use MSBuild to build the project
+        $msbuildPath = "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
+
+        if (!(Test-Path $msbuildPath)) {
+            Write-ErrorMsg "MSBuild not found at: $msbuildPath"
+            return $false
+        }
+
+        $buildOutput = & $msbuildPath $SolutionFile /t:Rebuild /p:Configuration=Release /v:minimal 2>&1
+
+        if ($LASTEXITCODE -eq 0) {
+            Write-Success "Build completed successfully"
+            return $true
+        }
+        else {
+            Write-ErrorMsg "Build failed with exit code: $LASTEXITCODE"
+            Write-ColorOutput "Build output:" "Gray"
+            $buildOutput | ForEach-Object { Write-ColorOutput "    $_" "Gray" }
+            return $false
+        }
+    }
+    catch {
+        Write-ErrorMsg "Build error: $_"
+        return $false
+    }
+}
+
+# Step 4: Install the extension
+function Install-Extension {
+    Write-Step "Installing extension..."
+
+    # Find the VSIX file
+    $vsixFiles = Get-ChildItem -Path $ProjectPath -Filter "*.vsix" -Recurse | Where-Object {
+        $_.FullName -like "*\bin\Release\*" -or $_.FullName -like "*\bin\Debug\*"
+    } | Sort-Object LastWriteTime -Descending
+
+    if (!$vsixFiles) {
+        Write-ErrorMsg "No VSIX file found. Please build the project first."
+        return $false
+    }
+
+    $vsixFile = $vsixFiles[0].FullName
+    Write-ColorOutput "    Found VSIX: $vsixFile" "Gray"
+
+    # Use VSIXInstaller to install
+    $vsixInstallerPath = "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\VSIXInstaller.exe"
+
+    if (!(Test-Path $vsixInstallerPath)) {
+        Write-ErrorMsg "VSIXInstaller not found at: $vsixInstallerPath"
+        return $false
+    }
+
+    Write-ColorOutput "    Installing extension..." "Gray"
+
+    try {
+        $installArgs = @("/quiet", "/admin", $vsixFile)
+        $installOutput = & $vsixInstallerPath $installArgs 2>&1
+
+        if ($LASTEXITCODE -eq 0 -or $LASTEXITCODE -eq 1001) {
+            # 1001 = already installed (which is fine, we're reinstalling)
+            Write-Success "Extension installed successfully"
+            return $true
+        }
+        else {
+            Write-ErrorMsg "Installation failed with exit code: $LASTEXITCODE"
+            $installOutput | ForEach-Object { Write-ColorOutput "    $_" "Gray" }
+            return $false
+        }
+    }
+    catch {
+        Write-ErrorMsg "Installation error: $_"
+        return $false
+    }
+}
+
+# Step 5: Verify installation
+function Test-ExtensionInstalled {
+    Write-Step "Verifying installation..."
+
+    if (Test-Path $ExtensionFullPath) {
+        $dllPath = Join-Path $ExtensionFullPath "RoslynBridge.dll"
+        if (Test-Path $dllPath) {
+            Write-Success "Extension files found at: $ExtensionFolder"
+
+            # Check file version
+            try {
+                $dllInfo = Get-Item $dllPath
+                $version = $dllInfo.VersionInfo.FileVersion
+                Write-ColorOutput "    Version: $version" "Gray"
+            }
+            catch {
+                Write-ColorOutput "    Version: Unable to determine" "Gray"
+            }
+
+            return $true
+        }
+    }
+
+    Write-Warning "Extension files not found"
+    return $false
+}
+
+# Main execution
+try {
+    $startTime = Get-Date
+
+    if ($Action -eq "Clean" -or $Action -eq "Both") {
+        Stop-VisualStudio
+        Clear-ExtensionCache
+        $cleanSuccess = Remove-InstalledExtension
+
+        if (!$cleanSuccess) {
+            Write-ErrorMsg "`nCleanup failed!"
+            exit 1
+        }
+    }
+
+    if ($Action -eq "Reinstall" -or $Action -eq "Both") {
+        if (!$SkipBuild) {
+            $buildSuccess = Build-Extension
+            if (!$buildSuccess) {
+                Write-ErrorMsg "`nBuild failed! Cannot reinstall."
+                exit 1
+            }
+        }
+        else {
+            Write-Warning "Skipping build as requested"
+        }
+
+        $installSuccess = Install-Extension
+        if (!$installSuccess) {
+            Write-ErrorMsg "`nInstallation failed!"
+            exit 1
+        }
+
+        Test-ExtensionInstalled | Out-Null
+    }
+
+    $elapsed = (Get-Date) - $startTime
+
+    Write-ColorOutput "`n========================================" "Cyan"
+    Write-ColorOutput "  ✓ Completed in $($elapsed.TotalSeconds.ToString('F1')) seconds" "Green"
+    Write-ColorOutput "========================================`n" "Cyan"
+
+    if ($Action -eq "Reinstall" -or $Action -eq "Both") {
+        Write-ColorOutput "Next steps:" "Yellow"
+        Write-ColorOutput "  1. Open Visual Studio" "White"
+        Write-ColorOutput "  2. Go to Extensions → Manage Extensions" "White"
+        Write-ColorOutput "  3. Check 'Installed' tab for 'Roslyn Bridge'" "White"
+        Write-ColorOutput "  4. Open a solution and verify the extension loads" "White"
+        Write-ColorOutput "  5. Test: curl -X POST http://localhost:59123/health -H 'Content-Type: application/json' -d '{}'" "White"
+        Write-ColorOutput ""
+    }
+}
+catch {
+    Write-ErrorMsg "`nUnexpected error: $_"
+    Write-ColorOutput $_.ScriptStackTrace "Gray"
+    exit 1
+}