diff --git a/DebugLogger.cs b/DebugLogger.cs
index 3bf123c..a8a8825 100644
--- a/DebugLogger.cs
+++ b/DebugLogger.cs
@@ -87,7 +87,7 @@ private static void InitializeLogFile()
LogInfo($"Debug logging started at {DateTime.Now:yyyy-MM-dd HH:mm:ss}", "DebugLogger");
LogInfo($"Log file: {_logFilePath}", "DebugLogger");
LogInfo($"Application: BOINC WSL Distro Installer", "DebugLogger");
- LogInfo($"Application Version: 2.1.0", "DebugLogger");
+ LogInfo($"Application Version: 2.2.0", "DebugLogger");
LogInfo($"Windows Version: {Environment.OSVersion}", "DebugLogger");
LogInfo($"Is 64-bit OS: {Environment.Is64BitOperatingSystem}", "DebugLogger");
LogInfo($"Is 64-bit Process: {Environment.Is64BitProcess}", "DebugLogger");
diff --git a/MainWindow.xaml b/MainWindow.xaml
index 95e0262..252ad63 100644
--- a/MainWindow.xaml
+++ b/MainWindow.xaml
@@ -23,7 +23,7 @@ along with BOINC. If not, see .
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:local="clr-namespace:boinc_buda_runner_wsl_installer"
mc:Ignorable="d"
- Title="BOINC WSL Distro Installer - Version 2.1.0"
+ Title="BOINC WSL Distro Installer - Version 2.2.0"
Height="450"
Width="800">
diff --git a/MainWindow.xaml.cs b/MainWindow.xaml.cs
index 44d0533..1a0b22f 100644
--- a/MainWindow.xaml.cs
+++ b/MainWindow.xaml.cs
@@ -154,57 +154,88 @@ internal async Task CheckWindowsFeatures()
// Allow UI to update
await Task.Delay(100);
- // Check all required features
- var checkResult = await WindowsFeaturesCheck.CheckRequiredFeaturesAsync();
- DebugLogger.LogInfo($"Windows features check completed. All enabled: {checkResult.AllFeaturesEnabled}", "MainWindow");
-
- foreach (var feature in checkResult.FeatureResults)
+ try
{
- DebugLogger.LogConfiguration($"Feature {feature.FeatureName}", $"Status: {feature.Status}, Message: {feature.Message}", "MainWindow");
- }
+ // Check all required features
+ var checkResult = await WindowsFeaturesCheck.CheckRequiredFeaturesAsync();
+ DebugLogger.LogInfo($"Windows features check completed. All enabled: {checkResult.AllFeaturesEnabled}", "MainWindow");
- if (!checkResult.AllFeaturesEnabled)
- {
- DebugLogger.LogInfo("Some Windows features are disabled, attempting to enable them", "MainWindow");
+ foreach (var feature in checkResult.FeatureResults)
+ {
+ DebugLogger.LogConfiguration($"Feature {feature.FeatureName}", $"Status: {feature.Status}, Message: {feature.Message}", "MainWindow");
+ }
- // Update UI to show we're enabling features
- ChangeRowIconAndStatus(ID.WindowsFeatures, "YellowExclamationIcon", "Enabling missing Windows features...");
+ if (!checkResult.AllFeaturesEnabled)
+ {
+ DebugLogger.LogInfo("Some Windows features are disabled, attempting to enable them", "MainWindow");
- // Allow UI to update
- await Task.Delay(100);
+ // Update UI to show we're enabling features
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "YellowExclamationIcon", "Enabling missing Windows features...");
- // Enable missing features
- var enableResult = await WindowsFeaturesCheck.EnableRequiredFeaturesAsync();
- DebugLogger.LogInfo($"Windows features enable completed. Success: {enableResult.AllFeaturesEnabled}", "MainWindow");
+ // Allow UI to update
+ await Task.Delay(100);
- // Check if restart is required
- if (WindowsFeaturesCheck.IsRestartRequired(enableResult.FeatureResults))
- {
- LastWindowsFeaturesRestartRequired = true;
- DebugLogger.LogWarning("Restart required after enabling Windows features", "MainWindow");
- ChangeRowIconAndStatus(ID.WindowsFeatures, "YellowExclamationIcon", "Features enabled - restart required");
- if (!App.IsQuiet)
+ // Enable missing features
+ var enableResult = await WindowsFeaturesCheck.EnableRequiredFeaturesAsync();
+ DebugLogger.LogInfo($"Windows features enable completed. Success: {enableResult.AllFeaturesEnabled}", "MainWindow");
+
+ // Check if restart is required
+ if (WindowsFeaturesCheck.IsRestartRequired(enableResult.FeatureResults))
{
- MessageBox.Show(
- "Windows features have been enabled but require a restart.\n\nPlease restart your computer and run this installation again.",
- "Computer restart is required",
- MessageBoxButton.OK,
- MessageBoxImage.Warning);
+ LastWindowsFeaturesRestartRequired = true;
+ DebugLogger.LogWarning("Restart required after enabling Windows features", "MainWindow");
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "YellowExclamationIcon", "Features enabled - restart required");
+ if (!App.IsQuiet)
+ {
+ MessageBox.Show(
+ "Windows features have been enabled but require a restart.\n\nPlease restart your computer and run this installation again.",
+ "Computer restart is required",
+ MessageBoxButton.OK,
+ MessageBoxImage.Warning);
+ }
+ DebugLogger.LogMethodEnd("CheckWindowsFeatures", "false (restart required)", "MainWindow");
+ return false;
+ }
+
+ // Features were enabled successfully
+ if (enableResult.AllFeaturesEnabled)
+ {
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "GreenCheckboxIcon", "Windows features enabled successfully");
+ DebugLogger.LogMethodEnd("CheckWindowsFeatures", "true (features enabled)", "MainWindow");
+ return true;
+ }
+ else
+ {
+ // Some features failed to enable
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "RedCancelIcon", "Failed to enable some Windows features");
+ DebugLogger.LogError("Failed to enable some required Windows features", "MainWindow");
+
+ var failedFeatures = string.Join(", ", enableResult.FeatureResults
+ .Where(f => f.Status != WindowsFeaturesCheck.WindowsFeatureStatus.Enabled)
+ .Select(f => f.FeatureName));
+
+ PromptOpenIssue("Windows features enable failed",
+ $"Failed to enable required Windows features: {failedFeatures}. " +
+ $"Error details: {string.Join("; ", enableResult.FeatureResults.Select(f => f.Message))}");
+
+ DebugLogger.LogMethodEnd("CheckWindowsFeatures", "false (enable failed)", "MainWindow");
+ return false;
}
- DebugLogger.LogMethodEnd("CheckWindowsFeatures", "false (restart required)", "MainWindow");
- return false;
}
- // Features were enabled successfully
- ChangeRowIconAndStatus(ID.WindowsFeatures, "GreenCheckboxIcon", "Windows features enabled successfully");
- DebugLogger.LogMethodEnd("CheckWindowsFeatures", "true (features enabled)", "MainWindow");
+ // All features were already enabled
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "GreenCheckboxIcon", "All Windows features are already enabled");
+ DebugLogger.LogMethodEnd("CheckWindowsFeatures", "true (all features already enabled)", "MainWindow");
return true;
}
-
- // All features were already enabled
- ChangeRowIconAndStatus(ID.WindowsFeatures, "GreenCheckboxIcon", "All Windows features are already enabled");
- DebugLogger.LogMethodEnd("CheckWindowsFeatures", "true (all features already enabled)", "MainWindow");
- return true;
+ catch (Exception ex)
+ {
+ DebugLogger.LogException(ex, "Error occurred while checking Windows features", "MainWindow");
+ ChangeRowIconAndStatus(ID.WindowsFeatures, "RedCancelIcon", "Error checking Windows features");
+ PromptOpenIssue("Windows features check exception", ex.ToString());
+ DebugLogger.LogMethodEnd("CheckWindowsFeatures", "false (exception)", "MainWindow");
+ return false;
+ }
}
internal async Task CheckWsl()
@@ -250,7 +281,11 @@ internal async Task CheckWsl()
DebugLogger.LogError($"WSL check failed with status: {wslResult.Status}", "MainWindow");
ChangeRowIconAndStatus(ID.WslCheck, "RedCancelIcon", WslCheck.GetStatusDisplayMessage(wslResult));
DebugLogger.LogMethodEnd("CheckWsl", "false (WSL error)", "MainWindow");
- PromptOpenIssue("WSL check error", WslCheck.GetStatusDisplayMessage(wslResult));
+ PromptOpenIssue("WSL check error",
+ $"WSL Status: {wslResult.Status}\n" +
+ $"Message: {wslResult.Message}\n" +
+ $"Version Info: {wslResult.VersionInfo?.WslVersion ?? "N/A"}\n" +
+ $"Default Version: {wslResult.StatusInfo?.DefaultVersion.ToString() ?? "N/A"}");
return false;
}
}
@@ -259,7 +294,10 @@ internal async Task CheckWsl()
DebugLogger.LogException(ex, "Error occurred while checking WSL", "MainWindow");
ChangeRowIconAndStatus(ID.WslCheck, "RedCancelIcon", "Error occurred while checking WSL");
DebugLogger.LogMethodEnd("CheckWsl", "false (exception)", "MainWindow");
- PromptOpenIssue("WSL check exception", ex.ToString());
+ PromptOpenIssue("WSL check exception",
+ $"Exception Type: {ex.GetType().Name}\n" +
+ $"Message: {ex.Message}\n" +
+ $"Stack Trace:\n{ex.StackTrace}");
return false;
}
}
@@ -374,7 +412,13 @@ internal async Task CheckBudaRunner()
ChangeRowIconAndStatus(ID.BudaRunnerCheck, "YellowExclamationIcon", BudaRunnerCheck.GetStatusDisplayMessage(budaResult));
DebugLogger.LogMethodEnd("CheckBudaRunner", "true (error, continue anyway)", "MainWindow");
// Offer to report issue
- PromptOpenIssue("BUDA Runner check error", budaResult.ErrorMessage);
+ PromptOpenIssue("BUDA Runner check error",
+ $"Status: {budaResult.Status}\n" +
+ $"Error Message: {budaResult.ErrorMessage ?? "N/A"}\n" +
+ $"Is Installed: {budaResult.VersionInfo.IsInstalled}\n" +
+ $"Current Version: {budaResult.VersionInfo.CurrentVersion ?? "N/A"}\n" +
+ $"Latest Version: {budaResult.VersionInfo.LatestVersion ?? "N/A"}\n" +
+ $"Has Version File: {budaResult.VersionInfo.HasVersionFile}");
return true; // Continue despite error
}
}
@@ -384,7 +428,10 @@ internal async Task CheckBudaRunner()
ChangeRowIconAndStatus(ID.BudaRunnerCheck, "YellowExclamationIcon", "Error occurred while checking BOINC WSL Distro");
DebugLogger.LogMethodEnd("CheckBudaRunner", "true (exception, continue anyway)", "MainWindow");
// Offer to report issue
- PromptOpenIssue("BUDA Runner check exception", ex.ToString());
+ PromptOpenIssue("BUDA Runner check exception",
+ $"Exception Type: {ex.GetType().Name}\n" +
+ $"Message: {ex.Message}\n" +
+ $"Stack Trace:\n{ex.StackTrace}");
return true; // Continue despite error
}
}
@@ -417,8 +464,15 @@ private async Task InstallBudaRunner(BudaRunnerCheck.BudaRunnerCheckResult
DebugLogger.LogError("BUDA Runner installation failed", "MainWindow");
ChangeRowIconAndStatus(ID.BudaRunnerCheck, "RedCancelIcon", "Failed to install BOINC WSL Distro");
DebugLogger.LogMethodEnd("InstallBudaRunner", "false", "MainWindow");
- // Offer to report issue
- PromptOpenIssue("BOINC WSL Distro installation failed", "Failed to install BOINC WSL Distro");
+ // Offer to report issue with detailed context
+ PromptOpenIssue("BOINC WSL Distro installation failed",
+ $"Installation Status: Failed\n" +
+ $"Was Previously Installed: {budaResult.VersionInfo.IsInstalled}\n" +
+ $"Current Version: {budaResult.VersionInfo.CurrentVersion ?? "N/A"}\n" +
+ $"Target Version: {budaResult.VersionInfo.LatestVersion ?? "N/A"}\n" +
+ $"Download URL: {budaResult.DownloadUrl ?? "N/A"}\n" +
+ $"Update Required: {budaResult.UpdateRequired}\n" +
+ $"Check the log file for detailed error information.");
return false;
}
}
@@ -428,7 +482,12 @@ private async Task InstallBudaRunner(BudaRunnerCheck.BudaRunnerCheckResult
ChangeRowIconAndStatus(ID.BudaRunnerCheck, "RedCancelIcon", $"BOINC WSL Distro installation failed: {ex.Message}");
DebugLogger.LogMethodEnd("InstallBudaRunner", "false (exception)", "MainWindow");
// Offer to report issue
- PromptOpenIssue("BOINC WSL Distro installation exception", ex.ToString());
+ PromptOpenIssue("BOINC WSL Distro installation exception",
+ $"Exception Type: {ex.GetType().Name}\n" +
+ $"Message: {ex.Message}\n" +
+ $"Was Previously Installed: {budaResult.VersionInfo.IsInstalled}\n" +
+ $"Target Version: {budaResult.VersionInfo.LatestVersion ?? "N/A"}\n" +
+ $"Stack Trace:\n{ex.StackTrace}");
return false;
}
}
@@ -474,7 +533,9 @@ private async Task InstallWsl()
ChangeRowIconAndStatus(ID.WslCheck, "RedCancelIcon", "Failed to install WSL");
DebugLogger.LogMethodEnd("InstallWsl", "false", "MainWindow");
// Offer to report issue
- PromptOpenIssue("WSL installation failed", "Failed to install WSL");
+ PromptOpenIssue("WSL installation failed",
+ $"Download URL: {downloadUrl}\n" +
+ $"Installation failed with no specific error. Check the log file for more details.");
return false;
}
}
@@ -484,7 +545,10 @@ private async Task InstallWsl()
ChangeRowIconAndStatus(ID.WslCheck, "RedCancelIcon", "WSL installation failed");
DebugLogger.LogMethodEnd("InstallWsl", "false (exception)", "MainWindow");
// Offer to report issue
- PromptOpenIssue("WSL installation exception", ex.ToString());
+ PromptOpenIssue("WSL installation exception",
+ $"Exception Type: {ex.GetType().Name}\n" +
+ $"Message: {ex.Message}\n" +
+ $"Stack Trace:\n{ex.StackTrace}");
return false;
}
}
@@ -518,7 +582,14 @@ private async Task FixWslIssues(WslCheck.WslCheckResult wslResult)
ChangeRowIconAndStatus(ID.WslCheck, "YellowExclamationIcon", "Some WSL issues could not be fixed automatically");
DebugLogger.LogMethodEnd("FixWslIssues", "false", "MainWindow");
// Offer to report issue
- PromptOpenIssue("WSL fix issues could not be resolved", WslCheck.GetStatusDisplayMessage(wslResult));
+ PromptOpenIssue("WSL fix issues could not be resolved",
+ $"WSL Status: {wslResult.Status}\n" +
+ $"Current Version: {wslResult.VersionInfo?.WslVersion ?? "N/A"}\n" +
+ $"Latest Version: {wslResult.LatestVersion ?? "N/A"}\n" +
+ $"Default Version: {wslResult.StatusInfo?.DefaultVersion.ToString() ?? "N/A"}\n" +
+ $"Update Required: {wslResult.UpdateRequired}\n" +
+ $"Version Change Required: {wslResult.VersionChangeRequired}\n" +
+ $"Message: {wslResult.Message}");
return false;
}
}
@@ -528,7 +599,11 @@ private async Task FixWslIssues(WslCheck.WslCheckResult wslResult)
ChangeRowIconAndStatus(ID.WslCheck, "RedCancelIcon", "Failed to fix WSL configuration");
DebugLogger.LogMethodEnd("FixWslIssues", "false (exception)", "MainWindow");
// Offer to report issue
- PromptOpenIssue("WSL fix exception", ex.ToString());
+ PromptOpenIssue("WSL fix exception",
+ $"Exception Type: {ex.GetType().Name}\n" +
+ $"Message: {ex.Message}\n" +
+ $"WSL Status: {wslResult.Status}\n" +
+ $"Stack Trace:\n{ex.StackTrace}");
return false;
}
}
@@ -688,26 +763,53 @@ private void PromptOpenIssue(string title, string details)
{
try
{
- // Build a GitHub new issue URL with prefilled title/body.
- var repoNewIssueUrl = "https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new";
-
- var sb = new StringBuilder();
- sb.AppendLine("Describe the problem and steps to reproduce here.\n");
- sb.AppendLine("Error context:");
- sb.AppendLine(details ?? "(no details)");
- sb.AppendLine();
- sb.AppendLine($"App version: {FileVersionInfo.GetVersionInfo(Process.GetCurrentProcess().MainModule.FileName).FileVersion}");
- sb.AppendLine($"OS: {Environment.OSVersion}");
- sb.AppendLine($"64-bit OS: {Environment.Is64BitOperatingSystem}, 64-bit Process: {Environment.Is64BitProcess}");
- sb.AppendLine();
- if (!string.IsNullOrEmpty(DebugLogger.LogFilePath))
- {
- sb.AppendLine($"Log file path (attach this file in the issue): {DebugLogger.LogFilePath}");
- }
+ // Categorize the error to provide appropriate troubleshooting guidance
+ var errorCategory = TroubleshootingGuide.CategorizeError(title, details);
+ var advice = TroubleshootingGuide.GetAdvice(errorCategory, details);
- var url = repoNewIssueUrl + "?title=" + Uri.EscapeDataString(title ?? "Installer error")
- + "&body=" + Uri.EscapeDataString(sb.ToString());
+ if (!App.IsQuiet)
+ {
+ // Show troubleshooting dialog instead of simple message box
+ var dialog = new TroubleshootingDialog(advice, details)
+ {
+ Owner = this
+ };
+ dialog.ShowDialog();
+ }
+ else
+ {
+ // In quiet mode, log the troubleshooting information
+ var formattedAdvice = TroubleshootingGuide.FormatAdviceAsMessage(advice);
+ DebugLogger.LogInfo($"Troubleshooting guidance for '{title}':\n{formattedAdvice}", "MainWindow");
+
+ // Build a GitHub new issue URL with prefilled title/body for logging purposes
+ var repoNewIssueUrl = "https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new";
+
+ var sb = new StringBuilder();
+ sb.AppendLine("Describe the problem and steps to reproduce here.\n");
+ sb.AppendLine("Error context:");
+ sb.AppendLine(details ?? "(no details)");
+ sb.AppendLine();
+ sb.AppendLine($"App version: {FileVersionInfo.GetVersionInfo(Process.GetCurrentProcess().MainModule.FileName).FileVersion}");
+ sb.AppendLine($"OS: {Environment.OSVersion}");
+ sb.AppendLine($"64-bit OS: {Environment.Is64BitOperatingSystem}, 64-bit Process: {Environment.Is64BitProcess}");
+ sb.AppendLine();
+ if (!string.IsNullOrEmpty(DebugLogger.LogFilePath))
+ {
+ sb.AppendLine($"Log file path (attach this file in the issue): {DebugLogger.LogFilePath}");
+ }
+ var url = repoNewIssueUrl + "?title=" + Uri.EscapeDataString(title ?? "Installer error")
+ + "&body=" + Uri.EscapeDataString(sb.ToString());
+
+ DebugLogger.LogInfo($"Issue report URL (quiet mode): {url}", "MainWindow");
+ }
+ }
+ catch (Exception ex)
+ {
+ DebugLogger.LogException(ex, "Failed to show troubleshooting guidance", "MainWindow");
+
+ // Fallback to old behavior if troubleshooting dialog fails
if (!App.IsQuiet)
{
var ask = MessageBox.Show(
@@ -718,17 +820,32 @@ private void PromptOpenIssue(string title, string details)
if (ask == MessageBoxResult.Yes)
{
- Process.Start(url);
+ try
+ {
+ var repoNewIssueUrl = "https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new";
+ var sb = new StringBuilder();
+ sb.AppendLine("Describe the problem and steps to reproduce here.\n");
+ sb.AppendLine("Error context:");
+ sb.AppendLine(details ?? "(no details)");
+ sb.AppendLine();
+ sb.AppendLine($"App version: {FileVersionInfo.GetVersionInfo(Process.GetCurrentProcess().MainModule.FileName).FileVersion}");
+ sb.AppendLine($"OS: {Environment.OSVersion}");
+ sb.AppendLine($"64-bit OS: {Environment.Is64BitOperatingSystem}, 64-bit Process: {Environment.Is64BitProcess}");
+ if (!string.IsNullOrEmpty(DebugLogger.LogFilePath))
+ {
+ sb.AppendLine($"Log file path (attach this file in the issue): {DebugLogger.LogFilePath}");
+ }
+
+ var url = repoNewIssueUrl + "?title=" + Uri.EscapeDataString(title ?? "Installer error")
+ + "&body=" + Uri.EscapeDataString(sb.ToString());
+ Process.Start(url);
+ }
+ catch (Exception innerEx)
+ {
+ DebugLogger.LogException(innerEx, "Failed to open GitHub issue link", "MainWindow");
+ }
}
}
- else
- {
- DebugLogger.LogInfo($"Issue report URL (quiet mode): {url}", "MainWindow");
- }
- }
- catch (Exception ex)
- {
- DebugLogger.LogException(ex, "Failed to create/open GitHub issue link", "MainWindow");
}
}
diff --git a/Properties/AssemblyInfo.cs b/Properties/AssemblyInfo.cs
index b9493f5..fbe2975 100644
--- a/Properties/AssemblyInfo.cs
+++ b/Properties/AssemblyInfo.cs
@@ -65,6 +65,6 @@
// Build Number
// Revision
//
-[assembly: AssemblyVersion("2.1.0.0")]
-[assembly: AssemblyFileVersion("2.1.0.0")]
+[assembly: AssemblyVersion("2.2.0.0")]
+[assembly: AssemblyFileVersion("2.2.0.0")]
[assembly: NeutralResourcesLanguage("en-US")]
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..ddd8683
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,407 @@
+# BOINC BUDA Runner WSL Installer - Troubleshooting Guide
+
+This document provides comprehensive troubleshooting guidance for common issues encountered during the BOINC BUDA Runner WSL installation process.
+
+## Overview
+
+The installer has been enhanced with intelligent error detection and user-friendly troubleshooting guidance. When an error occurs, the installer will:
+
+1. Automatically categorize the error
+2. Provide step-by-step troubleshooting instructions
+3. Offer relevant resources and documentation links
+4. Allow you to report the issue on GitHub if needed
+
+## Common Installation Issues
+
+### 1. Windows Version Not Supported
+
+**Symptom**: Installer reports your Windows version is not supported.
+
+**Solution**:
+- WSL 2 requires Windows 10 version 1903 (Build 18362) or later, or Windows 11
+- Check your version: Press Win+R, type `winver`, and press Enter
+- Update Windows through Settings > Update & Security > Windows Update
+- Restart and run the installer again
+
+**Resources**:
+- [Windows 10 Update Assistant](https://www.microsoft.com/software-download/windows10)
+- [Windows 11 Upgrade](https://www.microsoft.com/software-download/windows11)
+
+### 2. Windows Features Not Enabled
+
+**Symptom**: Required Windows features are missing or disabled.
+
+**Solution**:
+- The installer will automatically enable required features
+- If automatic enablement fails, enable manually:
+ 1. Search for "Turn Windows features on or off" in Start menu
+ 2. Enable "Virtual Machine Platform"
+ 3. Enable "Windows Subsystem for Linux"
+ 4. Restart your computer
+ 5. Run the installer again
+
+**Resources**:
+- [Manual WSL Installation Guide](https://docs.microsoft.com/windows/wsl/install-manual)
+
+### 3. WSL Not Installed
+
+**Symptom**: WSL is not installed on your system.
+
+**Solution**:
+- The installer will automatically download and install WSL
+- For manual installation:
+ 1. Open PowerShell as Administrator
+ 2. Run: `wsl --install`
+ 3. Restart when prompted
+ 4. Run the installer again
+
+**Alternative**: Install WSL from Microsoft Store
+- Open Microsoft Store
+- Search for "Windows Subsystem for Linux"
+- Install and restart
+
+**Resources**:
+- [WSL Installation Guide](https://docs.microsoft.com/windows/wsl/install)
+- [WSL Microsoft Store](ms-windows-store://pdp/?ProductId=9P9TQF7MRM4R)
+
+### 4. WSL Version Issues
+
+**Symptom**: WSL version is outdated or default version is not set to 2.
+
+**Solution**:
+- The installer will automatically update WSL
+- For manual update:
+ 1. Open PowerShell as Administrator
+ 2. Run: `wsl --update`
+ 3. Run: `wsl --set-default-version 2`
+ 4. Run the installer again
+
+**Resources**:
+- [WSL Update Guide](https://docs.microsoft.com/windows/wsl/install)
+- [WSL Releases](https://github.com/microsoft/WSL/releases)
+
+### 5. WSL Installation Failed
+
+**Symptom**: Automatic WSL installation encounters an error.
+
+**Common Causes**:
+- **Error 0x80070057**: Invalid parameter - may be due to corrupted download
+- **Error 0x80070002**: Missing files - system files may be corrupted
+- **Error 0x80070005**: Permission denied - run as Administrator
+- **Error 0x800701bc**: Virtualization not enabled - enable in BIOS
+
+**Solutions**:
+
+#### Solution 1: Run as Administrator
+1. Right-click the installer
+2. Select "Run as administrator"
+3. Try again
+
+#### Solution 2: Manual WSL Installation
+1. Open PowerShell as Administrator
+2. Run: `wsl --install`
+3. If that fails, try: `wsl --install --web-download`
+4. Restart when prompted
+
+#### Solution 3: Fix System Files
+1. Open Command Prompt as Admin
+2. Run: `sfc /scannow`
+3. Wait for completion
+4. Restart and try again
+
+#### Solution 4: Enable Virtualization
+1. Restart and enter BIOS/UEFI settings
+2. Find and enable Intel VT-x or AMD-V
+3. Save and exit
+4. Run the installer again
+
+**Resources**:
+- [WSL Troubleshooting](https://docs.microsoft.com/windows/wsl/troubleshooting)
+- [WSL Manual Installation](https://docs.microsoft.com/windows/wsl/install-manual)
+
+### 6. BOINC Client is Running
+
+**Symptom**: BOINC client must be stopped before installation.
+
+**Solution**:
+
+#### Method 1: BOINC Manager
+1. Open BOINC Manager
+2. Go to File > Exit BOINC
+3. Wait a few seconds
+4. Run the installer again
+
+#### Method 2: Task Manager
+1. Open Task Manager (Ctrl+Shift+Esc)
+2. Find `boinc.exe` or `boincmgr.exe`
+3. Select and click "End task"
+4. Run the installer again
+
+#### Method 3: Services
+1. Open Services (services.msc)
+2. Find "BOINC" service
+3. Right-click and select "Stop"
+4. Run the installer again
+
+### 7. BOINC WSL Distro Installation Failed
+
+**Symptom**: Failed to install or update BOINC WSL Distro.
+
+**Common Causes**:
+- **Error 0x80070070**: Insufficient disk space (need at least 10 GB free)
+- **Error 0x80070032**: Distribution already in use
+- **Timeout**: Slow internet connection or system performance
+
+**Solutions**:
+
+#### Solution 1: Verify Prerequisites
+1. Check WSL is installed: `wsl --version`
+2. Verify at least 10 GB free disk space
+3. Check internet connection is stable
+
+#### Solution 2: Manual Installation
+1. Download latest release from [BOINC WSL Distro Releases](https://github.com/BOINC/boinc-buda-runner-wsl/releases/latest)
+2. Find the .wsl file for your architecture (x64 or ARM64)
+3. Open PowerShell as Administrator
+4. Run: `wsl --install --from-file "path\to\downloaded.wsl" --no-launch`
+5. Run the installer again to verify
+
+#### Solution 3: Clean Up and Retry
+1. Open PowerShell as Administrator
+2. Run: `wsl --list`
+3. If "boinc-buda-runner" exists: `wsl --unregister boinc-buda-runner`
+4. Run the installer again
+
+#### Solution 4: Check WSL Status
+1. Run: `wsl --status`
+2. Verify default version is 2
+3. If not: `wsl --set-default-version 2`
+4. Run the installer again
+
+**Resources**:
+- [BOINC WSL Distro Releases](https://github.com/BOINC/boinc-buda-runner-wsl/releases)
+- [WSL Import Documentation](https://docs.microsoft.com/windows/wsl/use-custom-distro)
+
+### 8. Network Connection Errors
+
+**Symptom**: Cannot download required components.
+
+**Solutions**:
+
+#### Solution 1: Check Internet Connection
+1. Verify you can access https://github.com in browser
+2. Try downloading files from other websites
+3. If internet is down, connect and try again
+
+#### Solution 2: Disable VPN/Proxy
+1. Temporarily disconnect VPN
+2. Configure proxy or connect directly
+3. Try installation again
+4. Re-enable VPN/proxy after installation
+
+#### Solution 3: Check Firewall
+1. Check if Windows Firewall is blocking installer
+2. Temporarily disable firewall (remember to re-enable)
+3. Try installation again
+
+#### Solution 4: Manual Download
+1. Manually download required files from GitHub
+2. WSL: https://github.com/microsoft/WSL/releases/latest
+3. BOINC WSL Distro: https://github.com/BOINC/boinc-buda-runner-wsl/releases/latest
+4. Follow manual installation instructions
+
+### 9. Permission Errors
+
+**Symptom**: Access denied or insufficient permissions.
+
+**Solution**:
+1. Close the installer
+2. Right-click the installer executable
+3. Select "Run as administrator"
+4. Click "Yes" on User Account Control prompt
+
+**Note**: Administrator rights are required for:
+- Installing Windows features
+- Installing WSL
+- Configuring system settings
+
+### 10. Version Check Failed
+
+**Symptom**: Cannot determine BOINC WSL Distro version.
+
+**Solutions**:
+
+#### Solution 1: Reinstall
+1. Open PowerShell as Administrator
+2. Run: `wsl --unregister boinc-buda-runner`
+3. Run the installer again
+
+#### Solution 2: Manual Version Check
+1. Open PowerShell
+2. Run: `wsl -d boinc-buda-runner cat /home/boinc/version.txt`
+3. If you see a version number, installation is OK
+4. If error, use Solution 1
+
+#### Solution 3: Verify Distribution
+1. Run: `wsl --list --verbose`
+2. Verify "boinc-buda-runner" is listed
+3. Verify status shows "Running" or "Stopped" (not "Installing")
+4. If status looks wrong, use Solution 1
+
+## Using the Installer
+
+### Features
+
+1. **Automatic Error Detection**: The installer automatically detects and categorizes errors
+2. **Troubleshooting Dialog**: User-friendly dialog shows step-by-step solutions
+3. **Copy to Clipboard**: Copy troubleshooting information for reference
+4. **Report on GitHub**: Directly report issues with pre-filled information
+5. **Log Files**: Detailed logs for debugging (access via "Open Log" button)
+
+### Installation Process
+
+The installer checks and configures the following in order:
+
+1. **Installer Update**: Checks for newer installer version
+2. **Windows Version**: Verifies Windows 10 (1903+) or Windows 11
+3. **Windows Features**: Enables Virtual Machine Platform and WSL
+4. **WSL Installation**: Installs and configures WSL 2
+5. **BOINC Process**: Verifies BOINC is not running
+6. **BOINC WSL Distro**: Installs and configures the BOINC WSL distribution
+
+### Running the Installer
+
+**Recommended**:
+1. Right-click the installer
+2. Select "Run as administrator"
+3. Follow on-screen instructions
+
+**If Installation Fails**:
+1. Note the error message
+2. Click the troubleshooting dialog that appears
+3. Follow the step-by-step solutions
+4. If problem persists, click "Report Issue on GitHub"
+5. Attach the log file from "Open Log" button
+
+## Advanced Troubleshooting
+
+### Enable Detailed Logging
+
+Detailed logging is enabled by default. Log files are saved to:
+- `%TEMP%\BOINC_WSL_Installer_YYYYMMDD_HHMMSS.log`
+
+To view logs:
+1. Click "Open Log" button in installer
+2. Or navigate to `%TEMP%` folder
+3. Look for files starting with `BOINC_WSL_Installer_`
+
+### Check Windows Features Status
+
+To manually check if Windows features are enabled:
+
+```powershell
+# Open PowerShell as Administrator
+dism.exe /online /get-featureinfo /featurename:VirtualMachinePlatform
+dism.exe /online /get-featureinfo /featurename:Microsoft-Windows-Subsystem-Linux
+```
+
+### Check WSL Status
+
+```powershell
+# Check WSL version
+wsl --version
+
+# Check installed distributions
+wsl --list --verbose
+
+# Check WSL status
+wsl --status
+```
+
+### Check BOINC WSL Distro
+
+```powershell
+# Check if distribution is installed
+wsl --list | findstr boinc-buda-runner
+
+# Check version file
+wsl -d boinc-buda-runner cat /home/boinc/version.txt
+
+# Start distribution
+wsl -d boinc-buda-runner
+```
+
+### System Requirements
+
+**Minimum Requirements**:
+- Windows 10 version 1903 (Build 18362) or later, or Windows 11
+- 64-bit processor with Second Level Address Translation (SLAT)
+- 4GB system memory
+- BIOS-level hardware virtualization support must be enabled
+- At least 10 GB free disk space
+
+**Check Your System**:
+1. Windows version: Press Win+R, type `winver`, press Enter
+2. Processor: Task Manager > Performance > CPU
+3. Memory: Task Manager > Performance > Memory
+4. Disk space: File Explorer > This PC
+
+### Virtualization Support
+
+**Check if virtualization is enabled**:
+1. Open Task Manager (Ctrl+Shift+Esc)
+2. Go to Performance tab
+3. Click CPU
+4. Look for "Virtualization: Enabled"
+
+**If Virtualization is Disabled**:
+1. Restart computer
+2. Enter BIOS/UEFI settings (usually Del, F2, F10, or Esc during boot)
+3. Find virtualization settings (Intel VT-x or AMD-V)
+4. Enable virtualization
+5. Save and exit BIOS
+6. Run the installer again
+
+## Reporting Issues
+
+If you encounter an issue not covered in this guide:
+
+1. **Use the Troubleshooting Dialog**:
+ - The installer will show a troubleshooting dialog when errors occur
+ - Review the suggested solutions
+ - Try the recommended steps
+
+2. **Gather Information**:
+ - Click "Open Log" button to view the log file
+ - Note your Windows version and system configuration
+ - Note the exact error message
+ - Note what you were doing when the error occurred
+
+3. **Report on GitHub**:
+ - Click "Report Issue on GitHub" in the troubleshooting dialog
+ - Or visit: https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new
+ - Fill in the pre-populated template
+ - Attach your log file
+ - Provide detailed description
+
+4. **Check Existing Issues**:
+ - Search existing issues: https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues
+ - Your issue may already be reported with a solution
+
+## Additional Resources
+
+### Official Documentation
+- [BOINC Project](https://boinc.berkeley.edu/)
+- [BOINC WSL Distro Repository](https://github.com/BOINC/boinc-buda-runner-wsl)
+- [WSL Documentation](https://docs.microsoft.com/windows/wsl/)
+- [WSL Troubleshooting Guide](https://docs.microsoft.com/windows/wsl/troubleshooting)
+
+### Community Support
+- [BOINC Forums](https://boinc.berkeley.edu/dev/)
+- [BOINC Reddit](https://www.reddit.com/r/BOINC/)
+- [GitHub Issues](https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues)
+
+### Microsoft Resources
+- [Windows Update](https://support.microsoft.com/windows/update-windows)
+- [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/)
+- [Virtual Machine Platform](https://docs.microsoft.com/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v)
diff --git a/TroubleshootingDialog.xaml b/TroubleshootingDialog.xaml
new file mode 100644
index 0000000..0e9fa25
--- /dev/null
+++ b/TroubleshootingDialog.xaml
@@ -0,0 +1,92 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/TroubleshootingDialog.xaml.cs b/TroubleshootingDialog.xaml.cs
new file mode 100644
index 0000000..4ce6447
--- /dev/null
+++ b/TroubleshootingDialog.xaml.cs
@@ -0,0 +1,165 @@
+// This file is part of BOINC.
+// https://boinc.berkeley.edu
+// Copyright (C) 2025 University of California
+//
+// BOINC is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License
+// as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// BOINC is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+// See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with BOINC. If not, see .
+
+using System;
+using System.Diagnostics;
+using System.Text;
+using System.Windows;
+
+namespace boinc_buda_runner_wsl_installer
+{
+ public partial class TroubleshootingDialog : Window
+ {
+ private TroubleshootingGuide.TroubleshootingAdvice _advice;
+ private string _errorContext;
+
+ public TroubleshootingDialog(TroubleshootingGuide.TroubleshootingAdvice advice, string errorContext = null)
+ {
+ InitializeComponent();
+ _advice = advice;
+ _errorContext = errorContext;
+
+ LoadAdvice();
+ }
+
+ private void LoadAdvice()
+ {
+ TitleTextBlock.Text = _advice.Title;
+ DescriptionTextBlock.Text = _advice.Description;
+
+ var stepsBuilder = new StringBuilder();
+ foreach (var step in _advice.Steps)
+ {
+ stepsBuilder.AppendLine(step);
+ }
+ StepsTextBlock.Text = stepsBuilder.ToString();
+
+ if (_advice.AdditionalResources.Count > 0)
+ {
+ var resourcesBuilder = new StringBuilder();
+ foreach (var resource in _advice.AdditionalResources)
+ {
+ resourcesBuilder.AppendLine($"� {resource}");
+ }
+ ResourcesTextBlock.Text = resourcesBuilder.ToString();
+ ResourcesExpander.Visibility = Visibility.Visible;
+ }
+ else
+ {
+ ResourcesExpander.Visibility = Visibility.Collapsed;
+ }
+
+ ReportIssueButton.Visibility = _advice.ShouldOfferIssueReport ? Visibility.Visible : Visibility.Collapsed;
+ }
+
+ private void CopyButton_Click(object sender, RoutedEventArgs e)
+ {
+ try
+ {
+ var fullText = TroubleshootingGuide.FormatAdviceAsMessage(_advice);
+
+ if (!string.IsNullOrEmpty(_errorContext))
+ {
+ fullText += "\n\nError Context:\n" + _errorContext;
+ }
+
+ Clipboard.SetText(fullText);
+ MessageBox.Show(
+ "Troubleshooting information has been copied to clipboard.",
+ "Copied",
+ MessageBoxButton.OK,
+ MessageBoxImage.Information);
+ }
+ catch (Exception ex)
+ {
+ MessageBox.Show(
+ $"Failed to copy to clipboard: {ex.Message}",
+ "Error",
+ MessageBoxButton.OK,
+ MessageBoxImage.Error);
+ }
+ }
+
+ private void ReportIssueButton_Click(object sender, RoutedEventArgs e)
+ {
+ try
+ {
+ var issueTitle = Uri.EscapeDataString(_advice.Title);
+
+ var issueBody = new StringBuilder();
+ issueBody.AppendLine("## Problem Description");
+ issueBody.AppendLine(_advice.Description);
+ issueBody.AppendLine();
+ issueBody.AppendLine("## Steps Attempted");
+ issueBody.AppendLine("(Please describe what troubleshooting steps you've tried)");
+ issueBody.AppendLine();
+
+ if (!string.IsNullOrEmpty(_errorContext))
+ {
+ issueBody.AppendLine("## Error Context");
+ issueBody.AppendLine("```");
+ issueBody.AppendLine(_errorContext);
+ issueBody.AppendLine("```");
+ issueBody.AppendLine();
+ }
+
+ issueBody.AppendLine("## System Information");
+ issueBody.AppendLine($"- OS: {Environment.OSVersion}");
+ issueBody.AppendLine($"- 64-bit OS: {Environment.Is64BitOperatingSystem}");
+ issueBody.AppendLine($"- 64-bit Process: {Environment.Is64BitProcess}");
+
+ try
+ {
+ var version = FileVersionInfo.GetVersionInfo(Process.GetCurrentProcess().MainModule.FileName).FileVersion;
+ issueBody.AppendLine($"- Installer Version: {version}");
+ }
+ catch { }
+
+ if (!string.IsNullOrEmpty(DebugLogger.LogFilePath))
+ {
+ issueBody.AppendLine();
+ issueBody.AppendLine("## Log File");
+ issueBody.AppendLine($"Log file path: `{DebugLogger.LogFilePath}`");
+ issueBody.AppendLine("(Please attach the log file to this issue)");
+ }
+
+ var url = $"https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new?title={issueTitle}&body={Uri.EscapeDataString(issueBody.ToString())}";
+
+ Process.Start(url);
+
+ MessageBox.Show(
+ "Your web browser will open to report this issue on GitHub.\n\nPlease provide as much detail as possible and attach your log file if available.",
+ "Report Issue",
+ MessageBoxButton.OK,
+ MessageBoxImage.Information);
+ }
+ catch (Exception ex)
+ {
+ MessageBox.Show(
+ $"Failed to open browser: {ex.Message}\n\nPlease manually visit:\nhttps://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new",
+ "Error",
+ MessageBoxButton.OK,
+ MessageBoxImage.Error);
+ }
+ }
+
+ private void CloseButton_Click(object sender, RoutedEventArgs e)
+ {
+ Close();
+ }
+ }
+}
diff --git a/TroubleshootingGuide.cs b/TroubleshootingGuide.cs
new file mode 100644
index 0000000..73c8ae0
--- /dev/null
+++ b/TroubleshootingGuide.cs
@@ -0,0 +1,697 @@
+// This file is part of BOINC.
+// https://boinc.berkeley.edu
+// Copyright (C) 2025 University of California
+//
+// BOINC is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License
+// as published by the Free Software Foundation,
+// either version 3 of the License, or (at your option) any later version.
+//
+// BOINC is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+// See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with BOINC. If not, see .
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Text;
+
+namespace boinc_buda_runner_wsl_installer
+{
+ ///
+ /// Provides user-friendly troubleshooting guidance for common installation issues
+ ///
+ public static class TroubleshootingGuide
+ {
+ public enum ErrorCategory
+ {
+ WindowsVersion,
+ WindowsFeatures,
+ WslNotInstalled,
+ WslVersionMismatch,
+ WslInstallationFailed,
+ WslCheckFailed,
+ BoincRunning,
+ BudaRunnerInstallFailed,
+ BudaRunnerVersionCheckFailed,
+ NetworkError,
+ PermissionError,
+ UnknownError
+ }
+
+ public class TroubleshootingAdvice
+ {
+ public string Title { get; set; }
+ public string Description { get; set; }
+ public List Steps { get; set; } = new List();
+ public List AdditionalResources { get; set; } = new List();
+ public bool ShouldOfferIssueReport { get; set; } = true;
+ }
+
+ public static TroubleshootingAdvice GetAdvice(ErrorCategory category, string errorDetails = null)
+ {
+ switch (category)
+ {
+ case ErrorCategory.WindowsVersion:
+ return GetWindowsVersionAdvice();
+
+ case ErrorCategory.WindowsFeatures:
+ return GetWindowsFeaturesAdvice();
+
+ case ErrorCategory.WslNotInstalled:
+ return GetWslNotInstalledAdvice();
+
+ case ErrorCategory.WslVersionMismatch:
+ return GetWslVersionMismatchAdvice();
+
+ case ErrorCategory.WslInstallationFailed:
+ return GetWslInstallationFailedAdvice(errorDetails);
+
+ case ErrorCategory.WslCheckFailed:
+ return GetWslCheckFailedAdvice(errorDetails);
+
+ case ErrorCategory.BoincRunning:
+ return GetBoincRunningAdvice();
+
+ case ErrorCategory.BudaRunnerInstallFailed:
+ return GetBudaRunnerInstallFailedAdvice(errorDetails);
+
+ case ErrorCategory.BudaRunnerVersionCheckFailed:
+ return GetBudaRunnerVersionCheckFailedAdvice();
+
+ case ErrorCategory.NetworkError:
+ return GetNetworkErrorAdvice();
+
+ case ErrorCategory.PermissionError:
+ return GetPermissionErrorAdvice();
+
+ default:
+ return GetUnknownErrorAdvice(errorDetails);
+ }
+ }
+
+ private static TroubleshootingAdvice GetWindowsVersionAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Windows Version Not Supported",
+ Description = "Your Windows version does not meet the minimum requirements for BOINC WSL Distro installation. WSL 2 requires Windows 10 version 1903 (Build 18362) or later, or Windows 11.",
+ Steps = new List
+ {
+ "Check your Windows version: Press Win+R, type 'winver', and press Enter",
+ "If you're running an older version of Windows 10, update to the latest version through Windows Update",
+ "Go to Settings > Update & Security > Windows Update",
+ "Click 'Check for updates' and install all available updates",
+ "After updating, restart your computer and run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "Windows 10 Update Assistant: https://www.microsoft.com/software-download/windows10",
+ "Windows 11 Upgrade: https://www.microsoft.com/software-download/windows11",
+ "WSL Requirements: https://docs.microsoft.com/windows/wsl/install"
+ },
+ ShouldOfferIssueReport = false
+ };
+ }
+
+ private static TroubleshootingAdvice GetWindowsFeaturesAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Windows Features Need to be Enabled",
+ Description = "Required Windows features for WSL are missing or not properly configured. The installer will attempt to enable them automatically, but a system restart may be required.",
+ Steps = new List
+ {
+ "The installer will automatically enable the required Windows features",
+ "If a restart is required, you will be prompted",
+ "After restarting, run this installer again to continue",
+ "",
+ "If automatic enablement fails, you can enable features manually:",
+ "1. Open 'Turn Windows features on or off' (search in Start menu)",
+ "2. Enable 'Virtual Machine Platform'",
+ "3. Enable 'Windows Subsystem for Linux'",
+ "4. Click OK and restart your computer when prompted",
+ "5. Run this installer again after restart"
+ },
+ AdditionalResources = new List
+ {
+ "Manual WSL Installation Guide: https://docs.microsoft.com/windows/wsl/install-manual"
+ },
+ ShouldOfferIssueReport = true
+ };
+ }
+
+ private static TroubleshootingAdvice GetWslNotInstalledAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "WSL Not Installed",
+ Description = "Windows Subsystem for Linux (WSL) is not installed on your system. The installer will attempt to install it automatically.",
+ Steps = new List
+ {
+ "The installer will automatically download and install WSL",
+ "This may take several minutes depending on your internet connection",
+ "If automatic installation fails, you can install WSL manually:",
+ "",
+ "Manual Installation:",
+ "1. Open PowerShell or Command Prompt as Administrator",
+ "2. Run: wsl --install",
+ "3. Restart your computer when prompted",
+ "4. Run this installer again after restart",
+ "",
+ "Alternative Method:",
+ "1. Open Microsoft Store",
+ "2. Search for 'Windows Subsystem for Linux'",
+ "3. Install the WSL app",
+ "4. Restart your computer",
+ "5. Run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "WSL Installation Guide: https://docs.microsoft.com/windows/wsl/install",
+ "WSL Microsoft Store: ms-windows-store://pdp/?ProductId=9P9TQF7MRM4R"
+ },
+ ShouldOfferIssueReport = true
+ };
+ }
+
+ private static TroubleshootingAdvice GetWslVersionMismatchAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "WSL Version Needs Update",
+ Description = "Your WSL installation needs to be updated or the default version needs to be changed to WSL 2. The installer will attempt to fix this automatically.",
+ Steps = new List
+ {
+ "The installer will automatically update WSL and set the default version to 2",
+ "If automatic update fails, you can update manually:",
+ "",
+ "Manual Update:",
+ "1. Open PowerShell or Command Prompt as Administrator",
+ "2. Run: wsl --update",
+ "3. Wait for the update to complete",
+ "4. Run: wsl --set-default-version 2",
+ "5. Run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "WSL Update Guide: https://docs.microsoft.com/windows/wsl/install",
+ "WSL Releases: https://github.com/microsoft/WSL/releases"
+ },
+ ShouldOfferIssueReport = true
+ };
+ }
+
+ private static TroubleshootingAdvice GetWslInstallationFailedAdvice(string errorDetails)
+ {
+ var advice = new TroubleshootingAdvice
+ {
+ Title = "WSL Installation Failed",
+ Description = "The automatic WSL installation encountered an error. This could be due to network issues, permission problems, or system configuration issues.",
+ Steps = new List
+ {
+ "Try the following solutions:",
+ "",
+ "Solution 1: Run as Administrator",
+ "1. Right-click the installer",
+ "2. Select 'Run as administrator'",
+ "3. Try the installation again",
+ "",
+ "Solution 2: Manual WSL Installation",
+ "1. Open PowerShell as Administrator",
+ "2. Run: wsl --install",
+ "3. If that fails, try: wsl --install --web-download",
+ "4. Restart your computer when prompted",
+ "5. Run this installer again",
+ "",
+ "Solution 3: Check Network Connection",
+ "1. Verify you have an active internet connection",
+ "2. Try disabling VPN or proxy temporarily",
+ "3. Check if your firewall is blocking the installation",
+ "4. Try the installation again"
+ },
+ AdditionalResources = new List
+ {
+ "WSL Troubleshooting: https://docs.microsoft.com/windows/wsl/troubleshooting",
+ "WSL Manual Installation: https://docs.microsoft.com/windows/wsl/install-manual"
+ }
+ };
+
+ if (!string.IsNullOrEmpty(errorDetails))
+ {
+ if (errorDetails.Contains("0x80070057") || errorDetails.Contains("parameter is incorrect"))
+ {
+ advice.Steps.Insert(1, "Error indicates invalid parameter. This may be due to corrupted download or system configuration.");
+ advice.Steps.Insert(2, "Try using: wsl --install --web-download --distribution Ubuntu");
+ advice.Steps.Insert(3, "");
+ }
+ else if (errorDetails.Contains("0x80070002") || errorDetails.Contains("cannot find"))
+ {
+ advice.Steps.Insert(1, "Error indicates missing files. System files may be corrupted.");
+ advice.Steps.Insert(2, "Run System File Checker: Open Command Prompt as Admin and run: sfc /scannow");
+ advice.Steps.Insert(3, "After completion, restart and try installation again.");
+ advice.Steps.Insert(4, "");
+ }
+ else if (errorDetails.Contains("0x80070005") || errorDetails.Contains("denied"))
+ {
+ advice.Steps.Insert(1, "Error indicates permission denied. Make sure you're running as Administrator.");
+ advice.Steps.Insert(2, "");
+ }
+ else if (errorDetails.Contains("0x800701bc") || errorDetails.Contains("virtualization"))
+ {
+ advice.Steps.Insert(1, "Error indicates virtualization issue. Enable virtualization in BIOS:");
+ advice.Steps.Insert(2, "1. Restart computer and enter BIOS/UEFI settings");
+ advice.Steps.Insert(3, "2. Find and enable Intel VT-x or AMD-V");
+ advice.Steps.Insert(4, "3. Save and exit BIOS");
+ advice.Steps.Insert(5, "4. Run this installer again");
+ advice.Steps.Insert(6, "");
+ }
+ }
+
+ return advice;
+ }
+
+ private static TroubleshootingAdvice GetWslCheckFailedAdvice(string errorDetails)
+ {
+ var advice = new TroubleshootingAdvice
+ {
+ Title = "WSL Status Check Failed",
+ Description = "Unable to verify WSL installation status. This could indicate WSL is not properly configured or there's a system issue.",
+ Steps = new List
+ {
+ "Try these troubleshooting steps:",
+ "",
+ "Step 1: Verify WSL Installation",
+ "1. Open PowerShell or Command Prompt",
+ "2. Run: wsl --version",
+ "3. If you see version info, WSL is installed",
+ "4. If you get an error, WSL needs to be installed or repaired",
+ "",
+ "Step 2: Repair WSL Installation",
+ "1. Open PowerShell as Administrator",
+ "2. Run: wsl --update",
+ "3. Run: wsl --shutdown",
+ "4. Run this installer again",
+ "",
+ "Step 3: Check Windows Features",
+ "1. Open 'Turn Windows features on or off'",
+ "2. Verify 'Virtual Machine Platform' is checked",
+ "3. Verify 'Windows Subsystem for Linux' is checked",
+ "4. If not, enable them and restart",
+ "5. Run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "WSL Troubleshooting: https://docs.microsoft.com/windows/wsl/troubleshooting",
+ "WSL GitHub Issues: https://github.com/microsoft/WSL/issues"
+ }
+ };
+
+ if (!string.IsNullOrEmpty(errorDetails))
+ {
+ if (errorDetails.Contains("0x80370102"))
+ {
+ advice.Steps.Insert(1, "Error 0x80370102: Virtualization is not enabled in BIOS.");
+ advice.Steps.Insert(2, "Enable VT-x/AMD-V in your computer's BIOS settings.");
+ advice.Steps.Insert(3, "");
+ }
+ else if (errorDetails.Contains("0x80370114"))
+ {
+ advice.Steps.Insert(1, "Error 0x80370114: Enable nested virtualization if running in a VM.");
+ advice.Steps.Insert(2, "");
+ }
+ }
+
+ return advice;
+ }
+
+ private static TroubleshootingAdvice GetBoincRunningAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "BOINC Client is Running",
+ Description = "The BOINC client is currently running and must be stopped before installation can proceed. This prevents potential conflicts during installation.",
+ Steps = new List
+ {
+ "To stop the BOINC client:",
+ "",
+ "Method 1: BOINC Manager",
+ "1. Open BOINC Manager",
+ "2. Go to File > Exit BOINC",
+ "3. Wait a few seconds for BOINC to shut down completely",
+ "4. Run this installer again",
+ "",
+ "Method 2: Task Manager",
+ "1. Open Task Manager (Ctrl+Shift+Esc)",
+ "2. Find 'boinc.exe' or 'boincmgr.exe' in the Processes tab",
+ "3. Select and click 'End task'",
+ "4. Run this installer again",
+ "",
+ "Method 3: Services (if running as service)",
+ "1. Open Services (services.msc)",
+ "2. Find 'BOINC' service",
+ "3. Right-click and select 'Stop'",
+ "4. Run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "BOINC Documentation: https://boinc.berkeley.edu/wiki/User_manual"
+ },
+ ShouldOfferIssueReport = false
+ };
+ }
+
+ private static TroubleshootingAdvice GetBudaRunnerInstallFailedAdvice(string errorDetails)
+ {
+ var advice = new TroubleshootingAdvice
+ {
+ Title = "BOINC WSL Distro Installation Failed",
+ Description = "The installation of the BOINC WSL Distro encountered an error. This could be due to network issues, insufficient disk space, or WSL configuration problems.",
+ Steps = new List
+ {
+ "Try these troubleshooting steps:",
+ "",
+ "Step 1: Verify Prerequisites",
+ "1. Make sure WSL is properly installed (run: wsl --version)",
+ "2. Verify you have at least 10 GB of free disk space",
+ "3. Check your internet connection is stable",
+ "",
+ "Step 2: Manual Installation Attempt",
+ "1. Download the latest release from:",
+ " https://github.com/BOINC/boinc-buda-runner-wsl/releases/latest",
+ "2. Find the .wsl file matching your architecture (x64 or ARM64)",
+ "3. Open PowerShell as Administrator",
+ "4. Run: wsl --install --from-file \"path\\to\\downloaded.wsl\" --no-launch",
+ "5. If successful, run this installer again to verify",
+ "",
+ "Step 3: Clean Up and Retry",
+ "1. Open PowerShell as Administrator",
+ "2. Run: wsl --list",
+ "3. If you see 'boinc-buda-runner', unregister it: wsl --unregister boinc-buda-runner",
+ "4. Run this installer again",
+ "",
+ "Step 4: Check WSL Status",
+ "1. Run: wsl --status",
+ "2. Verify default version is 2",
+ "3. If not, run: wsl --set-default-version 2",
+ "4. Run this installer again"
+ },
+ AdditionalResources = new List
+ {
+ "BOINC WSL Distro Releases: https://github.com/BOINC/boinc-buda-runner-wsl/releases",
+ "WSL Import Documentation: https://docs.microsoft.com/windows/wsl/use-custom-distro",
+ "Create GitHub Issue: https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new"
+ }
+ };
+
+ if (!string.IsNullOrEmpty(errorDetails))
+ {
+ if (errorDetails.Contains("0x80070070") || errorDetails.Contains("disk space"))
+ {
+ advice.Steps.Insert(1, "Error indicates insufficient disk space. You need at least 10 GB free.");
+ advice.Steps.Insert(2, "Free up disk space and try again.");
+ advice.Steps.Insert(3, "");
+ }
+ else if (errorDetails.Contains("timeout") || errorDetails.Contains("timed out"))
+ {
+ advice.Steps.Insert(1, "Installation timed out. This may be due to slow internet or system performance.");
+ advice.Steps.Insert(2, "Try downloading the .wsl file manually and use Method 2 above.");
+ advice.Steps.Insert(3, "");
+ }
+ else if (errorDetails.Contains("0x80070032"))
+ {
+ advice.Steps.Insert(1, "Error indicates the distribution is already in use.");
+ advice.Steps.Insert(2, "Close all WSL windows and try: wsl --shutdown");
+ advice.Steps.Insert(3, "Then run this installer again.");
+ advice.Steps.Insert(4, "");
+ }
+ }
+
+ return advice;
+ }
+
+ private static TroubleshootingAdvice GetBudaRunnerVersionCheckFailedAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Unable to Verify BOINC WSL Distro Version",
+ Description = "The installer cannot determine the version of the BOINC WSL Distro. This may indicate a corrupted installation or missing version file.",
+ Steps = new List
+ {
+ "Try these solutions:",
+ "",
+ "Solution 1: Reinstall BOINC WSL Distro",
+ "1. Open PowerShell as Administrator",
+ "2. Run: wsl --unregister boinc-buda-runner",
+ "3. Run this installer again",
+ "",
+ "Solution 2: Manual Version Check",
+ "1. Open PowerShell",
+ "2. Run: wsl -d boinc-buda-runner cat /home/boinc/version.txt",
+ "3. If you see a version number, the installation is OK",
+ "4. If you get an error, reinstall using Solution 1",
+ "",
+ "Solution 3: Verify WSL Distribution",
+ "1. Run: wsl --list --verbose",
+ "2. Verify 'boinc-buda-runner' is listed",
+ "3. Verify it shows 'Running' or 'Stopped' (not 'Installing')",
+ "4. If status looks wrong, try Solution 1"
+ },
+ AdditionalResources = new List
+ {
+ "BOINC WSL Distro Documentation: https://github.com/BOINC/boinc-buda-runner-wsl"
+ }
+ };
+ }
+
+ private static TroubleshootingAdvice GetNetworkErrorAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Network Connection Error",
+ Description = "The installer cannot connect to the internet to download required components. This could be due to network issues, firewall, or proxy settings.",
+ Steps = new List
+ {
+ "Try these solutions:",
+ "",
+ "Solution 1: Check Internet Connection",
+ "1. Verify you can access https://github.com in your browser",
+ "2. Try downloading files from other websites",
+ "3. If internet is down, connect and try again",
+ "",
+ "Solution 2: Temporarily Disable VPN/Proxy",
+ "1. If using a VPN, disconnect temporarily",
+ "2. If behind a proxy, configure it or connect directly",
+ "3. Try the installation again",
+ "4. Re-enable VPN/proxy after installation",
+ "",
+ "Solution 3: Check Firewall Settings",
+ "1. Check if Windows Firewall is blocking the installer",
+ "2. Temporarily disable firewall (remember to re-enable)",
+ "3. Try the installation again",
+ "",
+ "Solution 4: Manual Download",
+ "1. Manually download required files from GitHub",
+ "2. WSL: https://github.com/microsoft/WSL/releases/latest",
+ "3. BOINC WSL Distro: https://github.com/BOINC/boinc-buda-runner-wsl/releases/latest",
+ "4. Follow manual installation instructions in the error message"
+ },
+ AdditionalResources = new List
+ {
+ "Windows Network Troubleshooting: https://support.microsoft.com/windows/network-connection-troubleshooter"
+ }
+ };
+ }
+
+ private static TroubleshootingAdvice GetPermissionErrorAdvice()
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Insufficient Permissions",
+ Description = "The installer requires administrator privileges to install system components like WSL and Windows features.",
+ Steps = new List
+ {
+ "To run with administrator privileges:",
+ "",
+ "Method 1: Run as Administrator",
+ "1. Close this installer",
+ "2. Right-click the installer executable",
+ "3. Select 'Run as administrator'",
+ "4. Click 'Yes' on the User Account Control prompt",
+ "",
+ "Method 2: Enable Administrator Account (if needed)",
+ "1. Open Command Prompt as Administrator",
+ "2. Run: net user administrator /active:yes",
+ "3. Log out and log in as Administrator",
+ "4. Run the installer again",
+ "",
+ "Note: Some operations require administrator rights:",
+ "- Installing Windows features",
+ "- Installing WSL",
+ "- Configuring system settings"
+ },
+ AdditionalResources = new List
+ {
+ "Windows Administrator Guide: https://support.microsoft.com/windows/how-to-use-the-administrator-account"
+ },
+ ShouldOfferIssueReport = false
+ };
+ }
+
+ private static TroubleshootingAdvice GetUnknownErrorAdvice(string errorDetails)
+ {
+ return new TroubleshootingAdvice
+ {
+ Title = "Unexpected Error Occurred",
+ Description = "An unexpected error occurred during installation. This may be a new issue that needs to be reported.",
+ Steps = new List
+ {
+ "General troubleshooting steps:",
+ "",
+ "Step 1: Restart and Retry",
+ "1. Restart your computer",
+ "2. Run the installer again as Administrator",
+ "",
+ "Step 2: Check System Requirements",
+ "1. Verify you're running Windows 10 (1903+) or Windows 11",
+ "2. Verify you have at least 10 GB free disk space",
+ "3. Verify you have a stable internet connection",
+ "",
+ "Step 3: Review Log File",
+ "1. Click 'Open Log' button in the installer",
+ "2. Look for specific error messages",
+ "3. Search for the error online or in GitHub issues",
+ "",
+ "Step 4: Report the Issue",
+ "1. If the error persists, please report it on GitHub",
+ "2. Include the log file contents in your report",
+ "3. Describe what you were doing when the error occurred",
+ "4. The development team will investigate and provide a solution"
+ },
+ AdditionalResources = new List
+ {
+ "Report Issue: https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new",
+ "Existing Issues: https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues",
+ "BOINC Forums: https://boinc.berkeley.edu/dev/"
+ }
+ };
+ }
+
+ public static string FormatAdviceAsMessage(TroubleshootingAdvice advice)
+ {
+ var sb = new StringBuilder();
+ sb.AppendLine(advice.Title);
+ sb.AppendLine(new string('=', advice.Title.Length));
+ sb.AppendLine();
+ sb.AppendLine(advice.Description);
+ sb.AppendLine();
+
+ if (advice.Steps.Count > 0)
+ {
+ foreach (var step in advice.Steps)
+ {
+ if (string.IsNullOrEmpty(step))
+ {
+ sb.AppendLine();
+ }
+ else
+ {
+ sb.AppendLine(step);
+ }
+ }
+ sb.AppendLine();
+ }
+
+ if (advice.AdditionalResources.Count > 0)
+ {
+ sb.AppendLine("Additional Resources:");
+ foreach (var resource in advice.AdditionalResources)
+ {
+ sb.AppendLine($" � {resource}");
+ }
+ }
+
+ return sb.ToString();
+ }
+
+ public static ErrorCategory CategorizeError(string componentName, string errorMessage)
+ {
+ if (string.IsNullOrEmpty(errorMessage))
+ {
+ return ErrorCategory.UnknownError;
+ }
+
+ var lowerError = errorMessage.ToLowerInvariant();
+ var lowerComponent = componentName?.ToLowerInvariant() ?? string.Empty;
+
+ // Windows version issues
+ if (lowerComponent.Contains("windowsversion") || lowerError.Contains("windows version"))
+ {
+ return ErrorCategory.WindowsVersion;
+ }
+
+ // Windows features issues
+ if (lowerComponent.Contains("windowsfeatures") || lowerError.Contains("windows feature"))
+ {
+ return ErrorCategory.WindowsFeatures;
+ }
+
+ // WSL related issues
+ if (lowerComponent.Contains("wsl"))
+ {
+ if (lowerError.Contains("not installed"))
+ {
+ return ErrorCategory.WslNotInstalled;
+ }
+ if (lowerError.Contains("version") && (lowerError.Contains("mismatch") || lowerError.Contains("outdated") || lowerError.Contains("default")))
+ {
+ return ErrorCategory.WslVersionMismatch;
+ }
+ if (lowerError.Contains("failed to install") || lowerError.Contains("installation failed"))
+ {
+ return ErrorCategory.WslInstallationFailed;
+ }
+ return ErrorCategory.WslCheckFailed;
+ }
+
+ // BOINC process issues
+ if (lowerComponent.Contains("boinc") && lowerError.Contains("running"))
+ {
+ return ErrorCategory.BoincRunning;
+ }
+
+ // BUDA Runner issues
+ if (lowerComponent.Contains("buda"))
+ {
+ if (lowerError.Contains("version") && (lowerError.Contains("cannot") || lowerError.Contains("unable")))
+ {
+ return ErrorCategory.BudaRunnerVersionCheckFailed;
+ }
+ if (lowerError.Contains("failed") || lowerError.Contains("error"))
+ {
+ return ErrorCategory.BudaRunnerInstallFailed;
+ }
+ }
+
+ // Network issues
+ if (lowerError.Contains("network") || lowerError.Contains("connection") ||
+ lowerError.Contains("timeout") || lowerError.Contains("download"))
+ {
+ return ErrorCategory.NetworkError;
+ }
+
+ // Permission issues
+ if (lowerError.Contains("permission") || lowerError.Contains("access denied") ||
+ lowerError.Contains("administrator") || lowerError.Contains("0x80070005"))
+ {
+ return ErrorCategory.PermissionError;
+ }
+
+ return ErrorCategory.UnknownError;
+ }
+ }
+}
diff --git a/app.manifest b/app.manifest
index 2de0a04..99e4083 100644
--- a/app.manifest
+++ b/app.manifest
@@ -1,6 +1,6 @@
-
+
diff --git a/boinc-buda-runner-wsl-installer.csproj b/boinc-buda-runner-wsl-installer.csproj
index a2fec43..9c8b4de 100644
--- a/boinc-buda-runner-wsl-installer.csproj
+++ b/boinc-buda-runner-wsl-installer.csproj
@@ -26,7 +26,7 @@
false
true
0
- 2.1.0.%2a
+ 2.2.0.%2a
false
false
true
@@ -81,6 +81,10 @@
+
+ TroubleshootingDialog.xaml
+
+
@@ -97,6 +101,10 @@
MainWindow.xaml
Code
+
+ MSBuild:Compile
+ Designer
+
@@ -123,6 +131,7 @@
Settings.Designer.cs
+