Simone/universal-shell-ext
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

docs: add bilingual README (EN/IT)

Browse Source
This commit is contained in:
Simone
2026-04-29 15:17:33 +02:00
parent 6ac95e43cb
commit 61f0740df6
2 changed files with 265 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+94 -94
View File
@@ -1,50 +1,50 @@
# UniversalShellExt # UniversalShellExt
Shell Extension COM generica per Windows che aggiunge una voce personalizzabile al menu contestuale di cartelle. Generic COM Shell Extension for Windows that adds a customizable entry to the folder context menu.
## Funzionalità ## Features
- ✅ **Menu Contestuale Personalizzabile**: - ✅ **Customizable Context Menu**:
- Voce nel menu contestuale per cartelle (click destro su cartella) - Context menu entry for folders (right-click on folder)
- Voce nel menu contestuale per sfondo cartella (click destro su area vuota) - Context menu entry for folder background (right-click on empty area)
- Testo, icona e comando completamente configurabili via registro - Text, icon and command fully configurable via registry
- ✅ **Configurazione Flessibile**: - ✅ **Flexible Configuration**:
- Tutti i parametri letti dal registro di Windows - All parameters read from the Windows registry
- Supporto per argomenti personalizzati con placeholder `%1` - Support for custom arguments with `%1` placeholder
- Icona estratta automaticamente dall'eseguibile - Icon automatically extracted from the executable
- ✅ **Sicurezza e Compatibilità**: - ✅ **Security and Compatibility**:
- Supporto UAC elevation automatico se necessario - Automatic UAC elevation support when required
- Compatibile con Windows 10/11 (x64) - Compatible with Windows 10/11 (x64)
- Accesso registro WOW64 corretto (64-bit) - Correct WOW64 registry access (64-bit)
- Thread-safe - Thread-safe
## File del Progetto ## Project Files
| File | Descrizione | | File | Description |
|------|-------------| |------|-------------|
| `UniversalShellExt.cpp` | Codice sorgente C++ della Shell Extension COM | | `UniversalShellExt.cpp` | C++ source code of the COM Shell Extension |
| `UniversalShellExt.def` | Definizioni esportazioni DLL | | `UniversalShellExt.def` | DLL export definitions |
| `UniversalShellExt.rc` | Risorse della DLL (Version Info) | | `UniversalShellExt.rc` | DLL resources (Version Info) |
| `build.py` | Script Python per compilazione, firma e registrazione | | `build.py` | Python script for build, signing and registration |
## Configurazione ## Configuration
La DLL legge la configurazione dal registro di Windows: The DLL reads its configuration from the Windows registry:
### Chiavi di Registro ### Registry Keys
**Percorso:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt` **Path:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt`
*(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)* *(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)*
| Valore | Tipo | Descrizione | Esempio | | Value | Type | Description | Example |
|--------|------|-------------|---------| |-------|------|-------------|---------|
| `Command` | REG_SZ | Percorso completo dell'eseguibile | `N:\VSCode.exe` | | `Command` | REG_SZ | Full path to the executable | `N:\VSCode.exe` |
| `Arguments` | REG_SZ | Argomenti da passare (`%1` = path selezionato) | `"%1"` | | `Arguments` | REG_SZ | Arguments to pass (`%1` = selected path) | `"%1"` |
| `MenuText` | REG_SZ | Testo visualizzato nel menu | `Apri con VSCode` | | `MenuText` | REG_SZ | Text displayed in the menu | `Open with VSCode` |
| `Icon` | REG_SZ | Percorso icona (exe o ico) | `N:\VSCode.exe` | | `Icon` | REG_SZ | Icon path (exe or ico) | `N:\VSCode.exe` |
### Template Configurazione ### Configuration Template
```reg ```reg
Windows Registry Editor Version 5.00 Windows Registry Editor Version 5.00
@@ -52,120 +52,120 @@ Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt] [HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt]
"Command"="N:\\VSCode.exe" "Command"="N:\\VSCode.exe"
"Arguments"="\"%1\"" "Arguments"="\"%1\""
"MenuText"="Apri con VSCode Portable" "MenuText"="Open with VSCode Portable"
"Icon"="N:\\VSCode.exe" "Icon"="N:\\VSCode.exe"
``` ```
### Valori Default ### Default Values
Se non configurati: If not configured:
- `Arguments` → `"%1"` (passa il percorso selezionato) - `Arguments` → `"%1"` (passes the selected path)
- `MenuText` → `"Open with Application"` - `MenuText` → `"Open with Application"`
- `Icon` → usa lo stesso percorso di `Command` - `Icon` → uses the same path as `Command`
## Identificatori ## Identifiers
| Tipo | Valore | | Type | Value |
|------|--------| |------|-------|
| **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` | | **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` |
| **Nome COM** | `Universal Portable Shell Extension` | | **COM Name** | `Universal Portable Shell Extension` |
## Compilazione ## Build
### Prerequisiti ### Prerequisites
- **Visual Studio 2022** (con workload "Desktop development with C++") - **Visual Studio 2022** (with "Desktop development with C++" workload)
- **Windows SDK** (per `signtool.exe` e `rc.exe`) - **Windows SDK** (for `signtool.exe` and `rc.exe`)
- **Python 3.x** - **Python 3.x**
- **Certificato di firma** (opzionale, per firma digitale) - **Signing certificate** (optional, for digital signing)
### Build Script ### Build Script
```powershell ```powershell
# Build completo (compila, copia, firma, registra) # Full build (compile, copy, sign, register)
python build.py python build.py
# Solo pulizia # Clean only
python build.py --clean python build.py --clean
# Solo deregistrazione # Unregister only
python build.py --unregister python build.py --unregister
# Build senza firma # Build without signing
python build.py --no-sign python build.py --no-sign
``` ```
### Output ### Output
La DLL compilata viene copiata in: The compiled DLL is copied to:
``` ```
plugins\UniversalShellExt64.dll plugins\UniversalShellExt64.dll
``` ```
## Registrazione ## Registration
### Metodo Consigliato (tramite Launcher) ### Recommended Method (via Launcher)
Il launcher `VSCode.exe` gestisce automaticamente la registrazione: The `VSCode.exe` launcher automatically manages registration:
```powershell ```powershell
N:\VSCode.exe /register # Registra la shell extension N:\VSCode.exe /register # Register the shell extension
N:\VSCode.exe /unregister # Rimuove la shell extension N:\VSCode.exe /unregister # Remove the shell extension
N:\VSCode.exe /register /silent # Modalità silenziosa N:\VSCode.exe /register /silent # Silent mode
``` ```
### Metodo Manuale (regsvr32) ### Manual Method (regsvr32)
Eseguire come **Amministratore**: Run as **Administrator**:
```cmd ```cmd
:: Registrazione regsvr32 "plugins\UniversalShellExt64.dll"
regsvr32 "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll"
:: Rimozione
regsvr32 /u "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll"
``` ```
## Chiavi di Registro Create ## Registry Keys Created
Durante la registrazione (`DllRegisterServer`): During registration (`DllRegisterServer`):
| Chiave | Scopo | | Key | Purpose |
|--------|-------| |-----|---------|
| `HKCR\CLSID\{5D849F86-...}` | Registrazione classe COM | | `HKCR\CLSID\{5D849F86-...}` | COM class registration |
| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | Percorso DLL | | `HKCR\CLSID\{5D849F86-...}\InprocServer32` | DLL path |
| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler per cartelle | | `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler for folders |
| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler per sfondo | | `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler for folder background |
| `HKLM\...\Shell Extensions\Approved` | Whitelist Microsoft | | `HKLM\...\Shell Extensions\Approved` | Microsoft whitelist |
## Come Funziona ## How It Works
1. **Inizializzazione**: Quando l'utente fa click destro, Explorer carica la DLL 1. **Initialization**: When the user right-clicks, Explorer loads the DLL
2. **Configurazione**: La DLL legge `Command`, `Arguments`, `MenuText`, `Icon` dal registro 2. **Configuration**: The DLL reads `Command`, `Arguments`, `MenuText`, `Icon` from the registry
3. **Menu**: Inserisce la voce nel menu contestuale con l'icona configurata 3. **Menu**: Inserts the entry in the context menu with the configured icon
4. **Esecuzione**: Al click, sostituisce `%1` con il percorso e lancia il comando 4. **Execution**: On click, replaces `%1` with the path and launches the command
5. **UAC**: Se il comando richiede elevazione, la richiede automaticamente 5. **UAC**: If the command requires elevation, requests it automatically
## Troubleshooting ## Troubleshooting
### La voce non appare nel menu ### Entry does not appear in the menu
1. Verificare che la DLL sia registrata (`regsvr32`) 1. Verify the DLL is registered (`regsvr32`)
2. Controllare che le chiavi di registro siano configurate 2. Check that the registry keys are configured
3. Riavviare Explorer (`taskkill /F /IM explorer.exe && explorer.exe`) 3. Restart Explorer (`taskkill /F /IM explorer.exe && explorer.exe`)
### Errore di registrazione ### Registration error
- Eseguire come Amministratore - Run as Administrator
- Verificare che la DLL sia firmata (Windows potrebbe bloccare DLL non firmate) - Verify the DLL is signed (Windows may block unsigned DLLs)
### Il comando non viene eseguito ### Command is not executed
- Verificare il percorso in `Command` sia corretto - Verify the path in `Command` is correct
- Controllare che `Arguments` contenga `%1` per ricevere il percorso - Check that `Arguments` contains `%1` to receive the path
## Versioni ## Versions
| Versione | Note | | Version | Notes |
|----------|------| |---------|-------|
| **1.0.0** | Prima release - Shell extension generica configurabile via registro | | **1.0.0** | First release — generic shell extension configurable via registry |
## Licenza ## License
Uso interno - emulab.it Internal use — emulab.it
---
*See [README_IT.md](README_IT.md) for the Italian version.*
README_IT.md
+171
View File
@@ -0,0 +1,171 @@
# UniversalShellExt
Shell Extension COM generica per Windows che aggiunge una voce personalizzabile al menu contestuale di cartelle.
## Funzionalità
- ✅ **Menu Contestuale Personalizzabile**:
- Voce nel menu contestuale per cartelle (click destro su cartella)
- Voce nel menu contestuale per sfondo cartella (click destro su area vuota)
- Testo, icona e comando completamente configurabili via registro
- ✅ **Configurazione Flessibile**:
- Tutti i parametri letti dal registro di Windows
- Supporto per argomenti personalizzati con placeholder `%1`
- Icona estratta automaticamente dall'eseguibile
- ✅ **Sicurezza e Compatibilità**:
- Supporto UAC elevation automatico se necessario
- Compatibile con Windows 10/11 (x64)
- Accesso registro WOW64 corretto (64-bit)
- Thread-safe
## File del Progetto
| File | Descrizione |
|------|-------------|
| `UniversalShellExt.cpp` | Codice sorgente C++ della Shell Extension COM |
| `UniversalShellExt.def` | Definizioni esportazioni DLL |
| `UniversalShellExt.rc` | Risorse della DLL (Version Info) |
| `build.py` | Script Python per compilazione, firma e registrazione |
## Configurazione
La DLL legge la configurazione dal registro di Windows:
### Chiavi di Registro
**Percorso:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt`
*(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)*
| Valore | Tipo | Descrizione | Esempio |
|--------|------|-------------|---------|
| `Command` | REG_SZ | Percorso completo dell'eseguibile | `N:\VSCode.exe` |
| `Arguments` | REG_SZ | Argomenti da passare (`%1` = path selezionato) | `"%1"` |
| `MenuText` | REG_SZ | Testo visualizzato nel menu | `Apri con VSCode` |
| `Icon` | REG_SZ | Percorso icona (exe o ico) | `N:\VSCode.exe` |
### Template Configurazione
```reg
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt]
"Command"="N:\\VSCode.exe"
"Arguments"="\"%1\""
"MenuText"="Apri con VSCode Portable"
"Icon"="N:\\VSCode.exe"
```
### Valori Default
Se non configurati:
- `Arguments` → `"%1"` (passa il percorso selezionato)
- `MenuText` → `"Open with Application"`
- `Icon` → usa lo stesso percorso di `Command`
## Identificatori
| Tipo | Valore |
|------|--------|
| **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` |
| **Nome COM** | `Universal Portable Shell Extension` |
## Compilazione
### Prerequisiti
- **Visual Studio 2022** (con workload "Desktop development with C++")
- **Windows SDK** (per `signtool.exe` e `rc.exe`)
- **Python 3.x**
- **Certificato di firma** (opzionale, per firma digitale)
### Build Script
```powershell
# Build completo (compila, copia, firma, registra)
python build.py
# Solo pulizia
python build.py --clean
# Solo deregistrazione
python build.py --unregister
# Build senza firma
python build.py --no-sign
```
### Output
La DLL compilata viene copiata in:
```
plugins\UniversalShellExt64.dll
```
## Registrazione
### Metodo Consigliato (tramite Launcher)
Il launcher `VSCode.exe` gestisce automaticamente la registrazione:
```powershell
N:\VSCode.exe /register # Registra la shell extension
N:\VSCode.exe /unregister # Rimuove la shell extension
N:\VSCode.exe /register /silent # Modalità silenziosa
```
### Metodo Manuale (regsvr32)
Eseguire come **Amministratore**:
```cmd
:: Registrazione
regsvr32 "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll"
:: Rimozione
regsvr32 /u "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll"
```
## Chiavi di Registro Create
Durante la registrazione (`DllRegisterServer`):
| Chiave | Scopo |
|--------|-------|
| `HKCR\CLSID\{5D849F86-...}` | Registrazione classe COM |
| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | Percorso DLL |
| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler per cartelle |
| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler per sfondo |
| `HKLM\...\Shell Extensions\Approved` | Whitelist Microsoft |
## Come Funziona
1. **Inizializzazione**: Quando l'utente fa click destro, Explorer carica la DLL
2. **Configurazione**: La DLL legge `Command`, `Arguments`, `MenuText`, `Icon` dal registro
3. **Menu**: Inserisce la voce nel menu contestuale con l'icona configurata
4. **Esecuzione**: Al click, sostituisce `%1` con il percorso e lancia il comando
5. **UAC**: Se il comando richiede elevazione, la richiede automaticamente
## Troubleshooting
### La voce non appare nel menu
1. Verificare che la DLL sia registrata (`regsvr32`)
2. Controllare che le chiavi di registro siano configurate
3. Riavviare Explorer (`taskkill /F /IM explorer.exe && explorer.exe`)
### Errore di registrazione
- Eseguire come Amministratore
- Verificare che la DLL sia firmata (Windows potrebbe bloccare DLL non firmate)
### Il comando non viene eseguito
- Verificare il percorso in `Command` sia corretto
- Controllare che `Arguments` contenga `%1` per ricevere il percorso
## Versioni
| Versione | Note |
|----------|------|
| **1.0.0** | Prima release - Shell extension generica configurabile via registro |
## Licenza
Uso interno - emulab.it