Add troubleshooting window#33
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive troubleshooting window feature to the BOINC WSL Distro Installer, upgrading it from version 2.1.0 to 2.2.0. The enhancement provides users with intelligent, context-aware troubleshooting guidance when installation errors occur, replacing simple error messages with detailed step-by-step solutions.
Key Changes:
- Introduced a new
TroubleshootingGuideclass that categorizes 13 types of installation errors and provides tailored advice for each - Added a
TroubleshootingDialogwindow that displays troubleshooting information with copy-to-clipboard and GitHub issue reporting functionality - Enhanced error reporting throughout
MainWindow.xaml.csto include detailed context and integrate the new troubleshooting system
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| TroubleshootingGuide.cs | Core troubleshooting logic with error categorization and detailed advice generation for 13 error categories including WSL, BOINC, network, and permission issues |
| TroubleshootingDialog.xaml | WPF window definition for displaying troubleshooting guidance with sections for description, steps, resources, and action buttons |
| TroubleshootingDialog.xaml.cs | Dialog code-behind implementing clipboard copy and GitHub issue reporting with pre-filled context |
| TROUBLESHOOTING.md | Comprehensive user documentation covering all common installation issues, solutions, and troubleshooting procedures |
| MainWindow.xaml.cs | Integration of troubleshooting system into error handling, replacing simple MessageBox prompts with contextual guidance dialogs |
| MainWindow.xaml | Window title updated to reflect version 2.2.0 |
| boinc-buda-runner-wsl-installer.csproj | Project file updated with new source files and version bump to 2.2.0 |
| app.manifest | Assembly version updated to 2.2.0.0 |
| Properties/AssemblyInfo.cs | Assembly and file version updated to 2.2.0.0 |
| DebugLogger.cs | Application version string updated to 2.2.0 in logging output |
Comments suppressed due to low confidence (1)
TroubleshootingDialog.xaml.cs:130
- Poor error handling: empty catch block.
catch { }
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <SubType>Code</SubType> | ||
| </Compile> | ||
| <Page Include="TroubleshootingDialog.xaml"> | ||
| <Generator>MSBuild:Compile</Generator> |
There was a problem hiding this comment.
The TroubleshootingDialog.xaml Page entry is missing the SubType attribute. For consistency with the other XAML pages in the project (like MainWindow.xaml which has SubType="Designer"), consider adding SubType="Designer" to this Page element.
| <Generator>MSBuild:Compile</Generator> | |
| <Generator>MSBuild:Compile</Generator> | |
| <SubType>Designer</SubType> |
| sb.AppendLine("Additional Resources:"); | ||
| foreach (var resource in advice.AdditionalResources) | ||
| { | ||
| sb.AppendLine($" � {resource}"); |
There was a problem hiding this comment.
The bullet character used here appears to be a square placeholder character (�) instead of a proper bullet point. This will not display correctly for users. Use a proper Unicode bullet character like '•' (U+2022) or a simple hyphen '-' instead.
| sb.AppendLine($" � {resource}"); | |
| sb.AppendLine($" • {resource}"); |
| 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.", |
There was a problem hiding this comment.
The URL generated here could potentially exceed browser URL length limits (typically around 2000-8000 characters depending on browser). The error context and log file path in the issueBody could make the URL very long. Consider either truncating the error context or using a POST request mechanism instead, or at minimum check the URL length and warn the user if it exceeds safe limits.
| 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.", | |
| // Limit the total URL length to 2000 characters (conservative for browser compatibility) | |
| const int maxUrlLength = 2000; | |
| string baseUrl = "https://github.com/BOINC/boinc-buda-runner-wsl-installer/issues/new?title=" + issueTitle + "&body="; | |
| string issueBodyStr = issueBody.ToString(); | |
| string encodedBody = Uri.EscapeDataString(issueBodyStr); | |
| string url = baseUrl + encodedBody; | |
| bool wasTruncated = false; | |
| if (url.Length > maxUrlLength) { | |
| // Truncate the body to fit within the limit | |
| int allowedBodyLength = maxUrlLength - baseUrl.Length; | |
| // We need to estimate how much of the unencoded body will fit after encoding | |
| // We'll iteratively reduce the body until the encoded length fits | |
| int truncateLength = issueBodyStr.Length; | |
| // Leave room for truncation notice | |
| const string truncationNotice = "\n\n---\n*The error context was truncated due to length limits. Please attach the full log file if possible.*"; | |
| while (truncateLength > 0) { | |
| string candidateBody = issueBodyStr.Substring(0, truncateLength) + truncationNotice; | |
| string candidateEncoded = Uri.EscapeDataString(candidateBody); | |
| if ((baseUrl.Length + candidateEncoded.Length) <= maxUrlLength) { | |
| encodedBody = candidateEncoded; | |
| wasTruncated = true; | |
| break; | |
| } | |
| truncateLength -= 100; // Reduce by 100 chars each iteration | |
| } | |
| if (!wasTruncated) { | |
| // As a last resort, use only the truncation notice | |
| encodedBody = Uri.EscapeDataString(truncationNotice); | |
| wasTruncated = true; | |
| } | |
| url = baseUrl + encodedBody; | |
| } | |
| Process.Start(url); | |
| string message = "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."; | |
| if (wasTruncated) { | |
| message += "\n\nNote: The error context was truncated to fit within browser URL length limits. Please attach the full log file or error details to your GitHub issue."; | |
| } | |
| MessageBox.Show( | |
| message, |
| var version = FileVersionInfo.GetVersionInfo(Process.GetCurrentProcess().MainModule.FileName).FileVersion; | ||
| issueBody.AppendLine($"- Installer Version: {version}"); | ||
| } | ||
| catch { } |
There was a problem hiding this comment.
The empty catch block silently swallows exceptions when getting the version info. While this might be intentional defensive programming, it would be better to log the exception or at least add a comment explaining why it's safe to ignore this error.
| catch { } | |
| catch (Exception ex) | |
| { | |
| // Log the exception so that failures in retrieving version info are not silently ignored. | |
| DebugLogger.Log($"Failed to get installer version: {ex}"); | |
| } |
| 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); |
There was a problem hiding this comment.
This fallback code duplicates the URL building logic that was in the original try block (lines 825-841). Consider extracting this URL building logic into a helper method to avoid duplication and make maintenance easier.
| Click="CopyButton_Click"/> | ||
| <Button x:Name="ReportIssueButton" | ||
| Content="Report Issue on GitHub" | ||
| Width="160" | ||
| Height="30" | ||
| Margin="0,0,10,0" | ||
| Click="ReportIssueButton_Click" | ||
| Visibility="Visible"/> | ||
| <Button x:Name="CloseButton" | ||
| Content="Close" | ||
| Width="80" | ||
| Height="30" | ||
| IsDefault="True" | ||
| Click="CloseButton_Click"/> |
There was a problem hiding this comment.
The buttons in this dialog lack AutomationProperties.Name attributes which are important for screen readers and accessibility tools. Add AutomationProperties.Name to help users with assistive technologies understand what each button does. For example, the ReportIssueButton could benefit from a more descriptive automation name explaining that it will open a browser to report an issue.
| Click="CopyButton_Click"/> | |
| <Button x:Name="ReportIssueButton" | |
| Content="Report Issue on GitHub" | |
| Width="160" | |
| Height="30" | |
| Margin="0,0,10,0" | |
| Click="ReportIssueButton_Click" | |
| Visibility="Visible"/> | |
| <Button x:Name="CloseButton" | |
| Content="Close" | |
| Width="80" | |
| Height="30" | |
| IsDefault="True" | |
| Click="CloseButton_Click"/> | |
| Click="CopyButton_Click" | |
| AutomationProperties.Name="Copy troubleshooting information to clipboard"/> | |
| <Button x:Name="ReportIssueButton" | |
| Content="Report Issue on GitHub" | |
| Width="160" | |
| Height="30" | |
| Margin="0,0,10,0" | |
| Click="ReportIssueButton_Click" | |
| Visibility="Visible" | |
| AutomationProperties.Name="Open browser to report an issue on GitHub"/> | |
| <Button x:Name="CloseButton" | |
| Content="Close" | |
| Width="80" | |
| Height="30" | |
| IsDefault="True" | |
| Click="CloseButton_Click" | |
| AutomationProperties.Name="Close troubleshooting dialog"/> |
| var resourcesBuilder = new StringBuilder(); | ||
| foreach (var resource in _advice.AdditionalResources) | ||
| { | ||
| resourcesBuilder.AppendLine($"� {resource}"); |
There was a problem hiding this comment.
The bullet character used here appears to be a square placeholder character (�) instead of a proper bullet point. This will not display correctly for users. Use a proper Unicode bullet character like '•' (U+2022) or a simple hyphen '-' instead.
| - ? Intelligent error categorization | ||
| - ? User-friendly troubleshooting dialogs | ||
| - ? Step-by-step solution guidance | ||
| - ? Context-specific error messages | ||
| - ? Copy troubleshooting info to clipboard | ||
| - ? Direct GitHub issue reporting | ||
| - ? Enhanced logging with detailed context | ||
| - ? Better error recovery suggestions | ||
|
|
||
| **Improved Error Messages**: | ||
| - ? Windows Features errors now show which features failed | ||
| - ? WSL errors include version and configuration details | ||
| - ? BOINC WSL Distro errors include version and download info | ||
| - ? Network errors provide connection troubleshooting | ||
| - ? Permission errors guide to run as Administrator | ||
|
|
||
| **Enhanced User Experience**: | ||
| - ? Clear, actionable error messages | ||
| - ? Multiple solution paths for each issue | ||
| - ? Links to relevant documentation | ||
| - ? Prevents issue reporting for user-fixable problems | ||
| - ? Maintains detailed logs for support |
There was a problem hiding this comment.
The checkmark character used here appears to be a square placeholder character (?) instead of a proper checkmark. This will not display correctly in the documentation. Use a proper Unicode checkmark like '✓' (U+2713) or '✔' (U+2714) instead, or simply use '- ' for markdown lists.
| - ? Intelligent error categorization | |
| - ? User-friendly troubleshooting dialogs | |
| - ? Step-by-step solution guidance | |
| - ? Context-specific error messages | |
| - ? Copy troubleshooting info to clipboard | |
| - ? Direct GitHub issue reporting | |
| - ? Enhanced logging with detailed context | |
| - ? Better error recovery suggestions | |
| **Improved Error Messages**: | |
| - ? Windows Features errors now show which features failed | |
| - ? WSL errors include version and configuration details | |
| - ? BOINC WSL Distro errors include version and download info | |
| - ? Network errors provide connection troubleshooting | |
| - ? Permission errors guide to run as Administrator | |
| **Enhanced User Experience**: | |
| - ? Clear, actionable error messages | |
| - ? Multiple solution paths for each issue | |
| - ? Links to relevant documentation | |
| - ? Prevents issue reporting for user-fixable problems | |
| - ? Maintains detailed logs for support | |
| - ✓ Intelligent error categorization | |
| - ✓ User-friendly troubleshooting dialogs | |
| - ✓ Step-by-step solution guidance | |
| - ✓ Context-specific error messages | |
| - ✓ Copy troubleshooting info to clipboard | |
| - ✓ Direct GitHub issue reporting | |
| - ✓ Enhanced logging with detailed context | |
| - ✓ Better error recovery suggestions | |
| **Improved Error Messages**: | |
| - ✓ Windows Features errors now show which features failed | |
| - ✓ WSL errors include version and configuration details | |
| - ✓ BOINC WSL Distro errors include version and download info | |
| - ✓ Network errors provide connection troubleshooting | |
| - ✓ Permission errors guide to run as Administrator | |
| **Enhanced User Experience**: | |
| - ✓ Clear, actionable error messages | |
| - ✓ Multiple solution paths for each issue | |
| - ✓ Links to relevant documentation | |
| - ✓ Prevents issue reporting for user-fixable problems | |
| - ✓ Maintains detailed logs for support |
| { | ||
| public partial class TroubleshootingDialog : Window | ||
| { | ||
| private TroubleshootingGuide.TroubleshootingAdvice _advice; |
There was a problem hiding this comment.
Field '_advice' can be 'readonly'.
| private TroubleshootingGuide.TroubleshootingAdvice _advice; | |
| private readonly TroubleshootingGuide.TroubleshootingAdvice _advice; |
| public partial class TroubleshootingDialog : Window | ||
| { | ||
| private TroubleshootingGuide.TroubleshootingAdvice _advice; | ||
| private string _errorContext; |
There was a problem hiding this comment.
Field '_errorContext' can be 'readonly'.
| private string _errorContext; | |
| private readonly string _errorContext; |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
6 issues found across 10 files
Prompt for AI agents (all 6 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="TroubleshootingDialog.xaml">
<violation number="1" location="TroubleshootingDialog.xaml:88">
P2: The CloseButton should include `IsCancel="True"` so the Escape key closes the dialog. This is standard Windows dialog behavior that users expect.</violation>
</file>
<file name="TroubleshootingGuide.cs">
<violation number="1" location="TroubleshootingGuide.cs:614">
P2: Character encoding issue: `�` is a Unicode replacement character indicating corrupted encoding. This will display incorrectly to users. Consider using a standard ASCII character like `-` or `*`, or the proper Unicode bullet `•` (U+2022) or `•`.</violation>
</file>
<file name="TroubleshootingDialog.xaml.cs">
<violation number="1" location="TroubleshootingDialog.xaml.cs:56">
P2: Character encoding issue: `�` is the Unicode replacement character (U+FFFD), indicating a corrupted character. This was likely meant to be a bullet point (`•` or `-`).</violation>
</file>
<file name="TROUBLESHOOTING.md">
<violation number="1" location="TROUBLESHOOTING.md:411">
P2: Version mismatch: The changelog states 'Version 1.x (Latest)' but the actual installer version is 2.2.0. This inconsistency could confuse users checking the documentation.</violation>
<violation number="2" location="TROUBLESHOOTING.md:414">
P2: Broken Unicode characters: The '?' symbols in the changelog appear to be corrupted emoji characters (likely checkmarks). Consider replacing them with standard ASCII characters like '-' or '*', or ensure proper UTF-8 encoding for emoji support.</violation>
<violation number="3" location="TROUBLESHOOTING.md:439">
P3: Stale date: 'Last Updated: January 2025' should likely be 'December 2025' since this document is being added now.</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
| Content="Close" | ||
| Width="80" | ||
| Height="30" | ||
| IsDefault="True" |
There was a problem hiding this comment.
P2: The CloseButton should include IsCancel="True" so the Escape key closes the dialog. This is standard Windows dialog behavior that users expect.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TroubleshootingDialog.xaml, line 88:
<comment>The CloseButton should include `IsCancel="True"` so the Escape key closes the dialog. This is standard Windows dialog behavior that users expect.</comment>
<file context>
@@ -0,0 +1,92 @@
+ Content="Close"
+ Width="80"
+ Height="30"
+ IsDefault="True"
+ Click="CloseButton_Click"/>
+ </StackPanel>
</file context>
| sb.AppendLine("Additional Resources:"); | ||
| foreach (var resource in advice.AdditionalResources) | ||
| { | ||
| sb.AppendLine($" � {resource}"); |
There was a problem hiding this comment.
P2: Character encoding issue: � is a Unicode replacement character indicating corrupted encoding. This will display incorrectly to users. Consider using a standard ASCII character like - or *, or the proper Unicode bullet • (U+2022) or •.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TroubleshootingGuide.cs, line 614:
<comment>Character encoding issue: `�` is a Unicode replacement character indicating corrupted encoding. This will display incorrectly to users. Consider using a standard ASCII character like `-` or `*`, or the proper Unicode bullet `•` (U+2022) or `•`.</comment>
<file context>
@@ -0,0 +1,697 @@
+ sb.AppendLine("Additional Resources:");
+ foreach (var resource in advice.AdditionalResources)
+ {
+ sb.AppendLine($" � {resource}");
+ }
+ }
</file context>
| var resourcesBuilder = new StringBuilder(); | ||
| foreach (var resource in _advice.AdditionalResources) | ||
| { | ||
| resourcesBuilder.AppendLine($"� {resource}"); |
There was a problem hiding this comment.
P2: Character encoding issue: � is the Unicode replacement character (U+FFFD), indicating a corrupted character. This was likely meant to be a bullet point (• or -).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TroubleshootingDialog.xaml.cs, line 56:
<comment>Character encoding issue: `�` is the Unicode replacement character (U+FFFD), indicating a corrupted character. This was likely meant to be a bullet point (`•` or `-`).</comment>
<file context>
@@ -0,0 +1,165 @@
+ var resourcesBuilder = new StringBuilder();
+ foreach (var resource in _advice.AdditionalResources)
+ {
+ resourcesBuilder.AppendLine($"� {resource}");
+ }
+ ResourcesTextBlock.Text = resourcesBuilder.ToString();
</file context>
|
|
||
| ## Changelog of Improvements | ||
|
|
||
| ### Version 1.x (Latest) |
There was a problem hiding this comment.
P2: Version mismatch: The changelog states 'Version 1.x (Latest)' but the actual installer version is 2.2.0. This inconsistency could confuse users checking the documentation.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TROUBLESHOOTING.md, line 411:
<comment>Version mismatch: The changelog states 'Version 1.x (Latest)' but the actual installer version is 2.2.0. This inconsistency could confuse users checking the documentation.</comment>
<file context>
@@ -0,0 +1,441 @@
+
+## Changelog of Improvements
+
+### Version 1.x (Latest)
+
+**New Features**:
</file context>
|
|
||
| --- | ||
|
|
||
| **Last Updated**: January 2025 |
There was a problem hiding this comment.
P3: Stale date: 'Last Updated: January 2025' should likely be 'December 2025' since this document is being added now.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TROUBLESHOOTING.md, line 439:
<comment>Stale date: 'Last Updated: January 2025' should likely be 'December 2025' since this document is being added now.</comment>
<file context>
@@ -0,0 +1,441 @@
+
+---
+
+**Last Updated**: January 2025
+**Installer Version**: See installer about box
+**For Updates**: https://github.com/BOINC/boinc-buda-runner-wsl-installer/releases
</file context>
| ### Version 1.x (Latest) | ||
|
|
||
| **New Features**: | ||
| - ? Intelligent error categorization |
There was a problem hiding this comment.
P2: Broken Unicode characters: The '?' symbols in the changelog appear to be corrupted emoji characters (likely checkmarks). Consider replacing them with standard ASCII characters like '-' or '*', or ensure proper UTF-8 encoding for emoji support.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At TROUBLESHOOTING.md, line 414:
<comment>Broken Unicode characters: The '?' symbols in the changelog appear to be corrupted emoji characters (likely checkmarks). Consider replacing them with standard ASCII characters like '-' or '*', or ensure proper UTF-8 encoding for emoji support.</comment>
<file context>
@@ -0,0 +1,441 @@
+### Version 1.x (Latest)
+
+**New Features**:
+- ? Intelligent error categorization
+- ? User-friendly troubleshooting dialogs
+- ? Step-by-step solution guidance
</file context>
Signed-off-by: Vitalii Koshura <lestat.de.lionkur@gmail.com>
AenBleidd
force-pushed
the
vko_add_troubleshooting
branch
from
521e70f to
ccd95db
Compare
Summary by cubic
Added a troubleshooting window and guide that provides step-by-step help when installer errors occur, with detailed context and optional GitHub issue reporting. Updated the installer version to 2.2.0.
Written for commit ccd95db. Summary will update automatically on new commits.