Simone
172 lines
4.7 KiB
Markdown
172 lines
4.7 KiB
Markdown
# UniversalShellExt
|
|
|
|
Generic COM Shell Extension for Windows that adds a customizable entry to the folder context menu.
|
|
|
|
## Features
|
|
|
|
- ✅ **Customizable Context Menu**:
|
|
- Context menu entry for folders (right-click on folder)
|
|
- Context menu entry for folder background (right-click on empty area)
|
|
- Text, icon and command fully configurable via registry
|
|
- ✅ **Flexible Configuration**:
|
|
- All parameters read from the Windows registry
|
|
- Support for custom arguments with `%1` placeholder
|
|
- Icon automatically extracted from the executable
|
|
- ✅ **Security and Compatibility**:
|
|
- Automatic UAC elevation support when required
|
|
- Compatible with Windows 10/11 (x64)
|
|
- Correct WOW64 registry access (64-bit)
|
|
- Thread-safe
|
|
|
|
## Project Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `UniversalShellExt.cpp` | C++ source code of the COM Shell Extension |
|
|
| `UniversalShellExt.def` | DLL export definitions |
|
|
| `UniversalShellExt.rc` | DLL resources (Version Info) |
|
|
| `build.py` | Python script for build, signing and registration |
|
|
|
|
## Configuration
|
|
|
|
The DLL reads its configuration from the Windows registry:
|
|
|
|
### Registry Keys
|
|
|
|
**Path:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt`
|
|
|
|
*(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)*
|
|
|
|
| Value | Type | Description | Example |
|
|
|-------|------|-------------|---------|
|
|
| `Command` | REG_SZ | Full path to the executable | `N:\VSCode.exe` |
|
|
| `Arguments` | REG_SZ | Arguments to pass (`%1` = selected path) | `"%1"` |
|
|
| `MenuText` | REG_SZ | Text displayed in the menu | `Open with VSCode` |
|
|
| `Icon` | REG_SZ | Icon path (exe or ico) | `N:\VSCode.exe` |
|
|
|
|
### Configuration Template
|
|
|
|
```reg
|
|
Windows Registry Editor Version 5.00
|
|
|
|
[HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt]
|
|
"Command"="N:\\VSCode.exe"
|
|
"Arguments"="\"%1\""
|
|
"MenuText"="Open with VSCode Portable"
|
|
"Icon"="N:\\VSCode.exe"
|
|
```
|
|
|
|
### Default Values
|
|
|
|
If not configured:
|
|
- `Arguments` → `"%1"` (passes the selected path)
|
|
- `MenuText` → `"Open with Application"`
|
|
- `Icon` → uses the same path as `Command`
|
|
|
|
## Identifiers
|
|
|
|
| Type | Value |
|
|
|------|-------|
|
|
| **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` |
|
|
| **COM Name** | `Universal Portable Shell Extension` |
|
|
|
|
## Build
|
|
|
|
### Prerequisites
|
|
- **Visual Studio 2022** (with "Desktop development with C++" workload)
|
|
- **Windows SDK** (for `signtool.exe` and `rc.exe`)
|
|
- **Python 3.x**
|
|
- **Signing certificate** (optional, for digital signing)
|
|
|
|
### Build Script
|
|
|
|
```powershell
|
|
# Full build (compile, copy, sign, register)
|
|
python build.py
|
|
|
|
# Clean only
|
|
python build.py --clean
|
|
|
|
# Unregister only
|
|
python build.py --unregister
|
|
|
|
# Build without signing
|
|
python build.py --no-sign
|
|
```
|
|
|
|
### Output
|
|
|
|
The compiled DLL is copied to:
|
|
```
|
|
plugins\UniversalShellExt64.dll
|
|
```
|
|
|
|
## Registration
|
|
|
|
### Recommended Method (via Launcher)
|
|
|
|
The `VSCode.exe` launcher automatically manages registration:
|
|
|
|
```powershell
|
|
N:\VSCode.exe /register # Register the shell extension
|
|
N:\VSCode.exe /unregister # Remove the shell extension
|
|
N:\VSCode.exe /register /silent # Silent mode
|
|
```
|
|
|
|
### Manual Method (regsvr32)
|
|
|
|
Run as **Administrator**:
|
|
|
|
```cmd
|
|
regsvr32 "plugins\UniversalShellExt64.dll"
|
|
```
|
|
|
|
## Registry Keys Created
|
|
|
|
During registration (`DllRegisterServer`):
|
|
|
|
| Key | Purpose |
|
|
|-----|---------|
|
|
| `HKCR\CLSID\{5D849F86-...}` | COM class registration |
|
|
| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | DLL path |
|
|
| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler for folders |
|
|
| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler for folder background |
|
|
| `HKLM\...\Shell Extensions\Approved` | Microsoft whitelist |
|
|
|
|
## How It Works
|
|
|
|
1. **Initialization**: When the user right-clicks, Explorer loads the DLL
|
|
2. **Configuration**: The DLL reads `Command`, `Arguments`, `MenuText`, `Icon` from the registry
|
|
3. **Menu**: Inserts the entry in the context menu with the configured icon
|
|
4. **Execution**: On click, replaces `%1` with the path and launches the command
|
|
5. **UAC**: If the command requires elevation, requests it automatically
|
|
|
|
## Troubleshooting
|
|
|
|
### Entry does not appear in the menu
|
|
1. Verify the DLL is registered (`regsvr32`)
|
|
2. Check that the registry keys are configured
|
|
3. Restart Explorer (`taskkill /F /IM explorer.exe && explorer.exe`)
|
|
|
|
### Registration error
|
|
- Run as Administrator
|
|
- Verify the DLL is signed (Windows may block unsigned DLLs)
|
|
|
|
### Command is not executed
|
|
- Verify the path in `Command` is correct
|
|
- Check that `Arguments` contains `%1` to receive the path
|
|
|
|
## Versions
|
|
|
|
| Version | Notes |
|
|
|---------|-------|
|
|
| **1.0.0** | First release — generic shell extension configurable via registry |
|
|
|
|
## License
|
|
|
|
Internal use — emulab.it
|
|
|
|
---
|
|
|
|
*See [README_IT.md](README_IT.md) for the Italian version.*
|