You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: GUIDE.md
+85-98Lines changed: 85 additions & 98 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,106 +15,93 @@ The extension is designed following SOLID principles to ensure it is maintainabl
15
15
16
16
The project is organized into the following key directories within the `WorkspaceLauncherForVSCode` project:
17
17
18
-
-**`/`**:
19
-
-[`WorkspaceLauncherForVSCode.cs`](./WorkspaceLauncherForVSCode.cs) - The main extension implementation.
18
+
-**`WorkspaceLauncherForVSCode/`**:
19
+
-[`WorkspaceLauncherForVSCode.cs`](./WorkspaceLauncherForVSCode/WorkspaceLauncherForVSCode.cs) - The main extension implementation and Dependency Injection container setup.
20
+
-[`WorkspaceLauncherForVSCodeCommandsProvider.cs`](./WorkspaceLauncherForVSCode/WorkspaceLauncherForVSCodeCommandsProvider.cs) - The entry point for providing commands and fallback items to the Command Palette.
21
+
-[`FallbackOpenRecentVisualStudioCodeItem.cs`](./WorkspaceLauncherForVSCode/FallbackOpenRecentVisualStudioCodeItem.cs) - A fallback command item that allows searching and jumping to the extension's page.
20
22
-**`/Classes`**: Contains core data models and helper classes.
-`OpenWindows.cs`, `Window.cs`, `WindowProcess.cs` - Enumerate and manage open application windows to support window switching.
39
+
-**`/Enums`**: Defines various enumerations used throughout the app (e.g., `WorkspaceType`, `VisualStudioCodeEdition`, `SortBy`, `FilterType`).
40
+
-**`/Helpers`**: Contains utility classes.
41
+
-`IdGenerator.cs` - Utility for generating unique, stable IDs for workspaces and solutions.
42
+
-`NativeMethods.cs`, `WslPathHelper.cs`, `FileUriParser.cs` - System-level integration and path parsing utilities.
43
+
-**`/Interfaces`**: Defines service contracts (`IVisualStudioCodeService`, `IPinService`, `IVSCodeWorkspaceWatcherService`, etc.).
44
+
-**`/Listeners`**:
45
+
-[`SettingsListener.cs`](./WorkspaceLauncherForVSCode/Listeners/SettingsListener.cs) - Monitors for setting changes to trigger UI updates and re-discovery.
39
46
-**`/Pages`**: Contains UI components.
40
-
-[`VisualStudioCodePage.cs`](./Pages/VisualStudioCodePage.cs) - A dynamic list page that displays discovered workspaces and solutions.
41
-
-**`/Services`**: Contains the primary service implementations.
42
-
-[`WorkspaceLauncherForVSCodeCommandsProvider.cs`](./Services/WorkspaceLauncherForVSCodeCommandsProvider.cs) - The entry point for providing commands to the Command Palette.
43
-
-[`VisualStudioCodeService.cs`](./Services/VisualStudioCodeService.cs) - Acts as a facade, orchestrating calls to more specialized provider classes.
44
-
-[`VisualStudioCodeInstanceProvider.cs`](./Services/VisualStudioCodeInstanceProvider.cs) - Discovers all installed instances of Visual Studio Code.
45
-
-[`VisualStudioCodeWorkspaceProvider.cs`](./Services/VisualStudioCodeWorkspaceProvider.cs) - Orchestrates the process of finding recent VS Code workspaces.
46
-
-[`VisualStudioProvider.cs`](./Services/VisualStudioProvider.cs) - Orchestrates the process of finding recent Visual Studio solutions.
47
-
-[`PinService.cs`](./Services/PinService.cs) - Manages the pinned state of workspaces.
48
-
-[`VSWorkspaceWatcherService.cs`](./Services/VSWorkspaceWatcherService.cs) - Monitors Visual Studio settings files for changes to trigger auto-refresh.
49
-
-[`VSCodeWorkspaceWatcherService.cs`](./Services/VSCodeWorkspaceWatcherService.cs) - Monitors Visual Studio Code storage for changes to trigger auto-refresh.
50
-
-**`/Services/VisualStudio`**: Contains the integrated source code for discovering Visual Studio instances and their recent items.
-**`/Models`**: C# models that map to the JSON structures of Visual Studio Code's workspace storage.
53
-
-**`/Readers`**: Specialized classes for reading and parsing workspace data.
54
-
-[`VscdbWorkspaceReader.cs`](./Workspaces/Readers/VscdbWorkspaceReader.cs) - Reads workspace data from the `state.vscdb` SQLite database.
55
-
-[`StorageJsonWorkspaceReader.cs`](./Workspaces/Readers/StorageJsonWorkspaceReader.cs) - Reads workspace data from the `storage.json` file.
56
-
57
-
## Core Components
58
-
59
-
### WindowWalker Integration
60
-
61
-
The extension integrates logic from the **WindowWalker** extension to provide window-switching functionality. When a user attempts to open a Visual Studio solution, the extension first checks if that solution is already open in an existing Visual Studio instance.
62
-
63
-
- The `OpenWindows` class enumerates all open windows on the system.
64
-
- The `Window` and `WindowProcess` classes gather information about each window, including its title and process name.
65
-
- The `OpenSolutionCommand` checks the titles of open `devenv.exe` processes to see if the solution is already open. If a match is found, the extension switches to that window instead of launching a new process.
66
-
67
-
### Services and Providers
68
-
69
-
***`IVisualStudioCodeService` / `VisualStudioCodeService`**: This service acts as the primary entry point for interacting with local Visual Studio and Visual Studio Code data. It delegates the complex tasks of instance and workspace/solution discovery to specialized provider classes.
70
-
***`VisualStudioCodeInstanceProvider`**: A static provider class responsible for discovering all installed instances of Visual Studio Code (Stable, Insiders, User, System) by scanning known locations and the system's PATH environment variable.
71
-
***`VisualStudioCodeWorkspaceProvider`**: This static provider orchestrates the process of finding recently opened VS Code workspaces. It doesn't perform the reading itself but delegates the task to specialized reader classes.
72
-
***`VisualStudioProvider`**: This static provider orchestrates the process of finding recently opened Visual Studio solutions. It uses the integrated `VisualStudioService` to discover Visual Studio instances and their recent items.
73
-
74
-
### Watcher Services
75
-
76
-
***`VSWorkspaceWatcherService` & `VSCodeWorkspaceWatcherService`**: These services provide real-time updates by monitoring the underlying configuration files (`ApplicationPrivateSettings.xml` for VS, `storage.json` / `state.vscdb` for VS Code). When a change is detected (e.g., a new solution is opened), the extension automatically refreshes the list.
77
-
78
-
### Pin Service
79
-
80
-
***`PinService`**: Manages the pinning functionality, allowing users to keep frequently used workspaces at the top of the list. It persists the pinned state across sessions.
81
-
82
-
### Visual Studio Integration
83
-
84
-
The extension now includes the core logic from the `PowerToys-Run-VisualStudio` project to discover Visual Studio installations and their recent solutions. This is accomplished by:
85
-
1. Using `vswhere.exe` to find all Visual Studio installations on the system.
86
-
2. Parsing the `ApplicationPrivateSettings.xml` file for each installation to find the location of the `CodeContainers.json` file.
87
-
3. Reading and deserializing the `CodeContainers.json` file to get a list of recent solutions.
88
-
89
-
This integration provides a seamless experience, allowing users to access both Visual Studio solutions and VS Code workspaces from a single interface.
90
-
91
-
**Asynchronous Initialization**:
92
-
To prevent UI freezing, the discovery of Visual Studio instances (which involves running `vswhere.exe`) and the scanning of their settings files are performed asynchronously in the background. The `InitInstancesAsync` method ensures that the heavy lifting is done without blocking the main thread, providing a responsive user experience even during startup.
93
-
94
-
### Workspace Readers and Performance
95
-
96
-
To ensure high performance and low memory usage, the extension uses the `System.Text.Json` source generator for deserializing workspace data. This avoids runtime reflection and minimizes allocations.
97
-
98
-
***Native AOT**: The application supports Native AOT (Ahead-of-Time) compilation, which significantly reduces startup time and memory footprint (introduced in version 1.9.0.0).
99
-
***Asynchronous Loading**: All heavy I/O operations, including reading workspace databases and running external processes, are fully asynchronous to maintain UI responsiveness.
100
-
***`VscdbWorkspaceReader` & `StorageJsonWorkspaceReader`**: These static reader classes are responsible for retrieving workspace information from Visual Studio Code's two primary data sources: the `state.vscdb` SQLite database and the `storage.json` file. Each reader is optimized to read its specific source and deserialize the data efficiently using source-generated models.
101
-
102
-
### Settings
103
-
104
-
***`SettingsManager`**: Manages all user-configurable settings for the extension. It loads settings from a JSON file and provides them to the rest of the application. It raises an event when settings are changed, allowing other components to react accordingly.
105
-
106
-
### UI and Commands
107
-
108
-
***`WorkspaceLauncherForVSCodeCommandsProvider`**: The main entry point for providing commands to the Command Palette. It initializes the required services and creates the top-level command items.
109
-
***`VisualStudioCodePage`**: A dynamic list page that displays the discovered workspaces and solutions. It receives the `IVisualStudioCodeService` to fetch data asynchronously and handles user interactions like searching and scrolling.
110
-
***`OpenVisualStudioCodeCommand` & `OpenSolutionCommand`**: The primary commands responsible for launching a selected VS Code workspace or Visual Studio solution.
111
-
112
-
#### Secondary Commands
113
-
Beyond the primary action of opening a workspace or solution, the extension provides secondary commands for managing the list:
114
-
115
-
***`CopyPathCommand`**: This command allows the user to copy the full file path of a workspace, solution, or folder directly to the clipboard.
116
-
***`RemoveWorkspaceCommand`**: This command provides the functionality to remove a workspace entry from the Visual Studio Code's list of recently opened items (not applicable to Visual Studio solutions).
117
-
***`PinWorkspaceCommand`**: (Un)pins a workspace or solution.
118
-
***`OpenInTerminalCommand`**: Opens the selected workspace's folder in the configured terminal.
47
+
-[`VisualStudioCodePage.cs`](./WorkspaceLauncherForVSCode/Pages/VisualStudioCodePage.cs) - The main dynamic list page with search, filtering, and caching.
48
+
-[`FallbackWorkspaceItem.cs`](./WorkspaceLauncherForVSCode/Pages/FallbackWorkspaceItem.cs) - Individual fallback results that appear in the main Command Palette search.
49
+
-`HelpPage.cs` & `StaticHelpItems.cs` - Provides contextual help and shortcuts documentation.
50
+
-`DetailPage.cs` - Provides a detailed view for a selected workspace.
51
+
-**`/Services`**: Primary service implementations.
52
+
-[`VisualStudioCodeService.cs`](./WorkspaceLauncherForVSCode/Services/VisualStudioCodeService.cs) - Orchestrates instance and workspace discovery.
53
+
-`VisualStudioCodeInstanceProvider.cs` - Scans for editor installations (VS Code, Cursor, etc.).
54
+
-`VisualStudioCodeWorkspaceProvider.cs` - Finds recent VS Code workspaces via internal readers.
55
+
-`VisualStudioProvider.cs` - Discovers Visual Studio solutions.
-`VSWorkspaceWatcherService.cs` & `VSCodeWorkspaceWatcherService.cs` - File system watchers for real-time updates when recent project files change.
58
+
-**`/Services/VisualStudio`**: Core logic for Visual Studio version and solution discovery.
59
+
-`VisualStudioService.cs` - Primary service for interacting with Visual Studio installations.
60
+
-**`/Workspaces`**: Workspace-specific logic.
61
+
-`WorkspaceFilter.cs` - Implements searching, filtering (by type/remote), and sorting logic.
62
+
-[`WorkspaceItemFactory.cs`](./WorkspaceLauncherForVSCode/Workspaces/WorkspaceItemFactory.cs) - Constructs UI `ListItem` objects from workspace models.
63
+
-`VscdbDatabase.cs` - Handles SQLite interaction for VS Code's `state.vscdb`.
64
+
-**`/Readers`**: Parsers for editor-specific metadata (SQLite and JSON).
65
+
66
+
## Core Components and Features
67
+
68
+
### Performance and Caching
69
+
70
+
To ensure the extension remains responsive even with hundreds of projects:
71
+
-**ListItem Caching**: `VisualStudioCodePage` maintains a cache of `ListItem` objects to avoid re-constructing them during search or scroll.
72
+
-**Search Caching**: Results of the last search query are cached and reused by fallback items to prevent redundant filtering operations.
73
+
-**Asynchronous Loading**: All I/O and process execution (like `vswhere.exe`) are handled off the UI thread.
74
+
-**Native AOT**: The project is optimized for Ahead-of-Time compilation, resulting in faster startup and lower memory usage.
75
+
76
+
### Search and Fallback Integration
77
+
78
+
The extension integrates deeply with the Command Palette through **Fallback Commands**:
79
+
-**Direct Results**: A configurable number of top-matching workspaces are injected directly into the main Command Palette search list via `FallbackWorkspaceItem`. This allows users to launch their most relevant projects instantly from the global search.
80
+
-**Search-to-Page**: The `FallbackOpenRecentVisualStudioCodeItem` provides a "Search for..." command that opens the extension's dedicated page pre-filtered with the current query.
81
+
-**Advanced Filtering**: Users can filter the list by workspace type (Local, WSL, SSH, Dev Container) or editor type via the UI filters.
82
+
83
+
### Pinning and Persistence
84
+
85
+
The `PinService` and `WorkspaceStorage` work together to manage project metadata:
86
+
-**Advanced Pinning**: Supports **Pin to List**, **Pin to Home**, and **Pin to Dock**. Pinned projects are highlighted with a tag and remain easily accessible across sessions. The extension integrates with Command Palette's pinning system by providing stable identifiers.
87
+
-**Frequency Tracking**: The extension tracks how often projects are opened through it, allowing for "Usage Count" sorting.
88
+
-**External Recent Lists**: The extension can also sort items to match the internal "Open Recent" order of VS Code or Visual Studio by reading their respective metadata.
89
+
90
+
### Visual Studio & Editor Support
91
+
92
+
-**Broad Compatibility**: Supports VS Code (User/System/Insiders), Cursor, Windsurf, and Google Antigravity.
93
+
-**Visual Studio 2026**: Preliminary support for the next version of Visual Studio.
94
+
-**Helper Launcher**: An optional `VisualStudioCodeForCommandPaletteLauncher.exe` is used to ensure editors come to the foreground when launched from the background extension process.
95
+
-**Window Switching**: Uses window enumeration to detect already-open solutions and switches focus instead of opening duplicate instances.
96
+
97
+
### UI and Contextual Actions
98
+
99
+
-**Rich Details**: Workspaces provide a details panel (built via `WorkspaceItemFactory`) that provides a rich preview of the project, including its type, path, and metadata.
100
+
-**Contextual Commands**: Every item supports a suite of secondary actions:
101
+
- Open as Administrator.
102
+
- Open in Explorer / Terminal.
103
+
- Copy Path.
104
+
- Contextual Help (F1).
105
+
-**Shortcuts**: Common actions support keyboard shortcuts (e.g., Ctrl+C for Copy Path, F5 for Refresh).
119
106
120
107
This architecture ensures a clean separation of concerns, making the codebase easier to understand, extend, and debug.
0 commit comments