Update project configuration, add service installation scripts, and create README documentation
This commit is contained in:
118
README.md
Normal file
118
README.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# DevDrive
|
||||
|
||||
A lightweight virtual drive for Windows built with Dokan. DevDrive mounts a user-defined filesystem at a drive letter (default: `A:`) and exposes folders from your machine as symlinks. Configuration lives in `C:\PhysicalDrive\index.json`.
|
||||
|
||||
## Requirements
|
||||
- Windows 10/11 x64
|
||||
- .NET 8 SDK
|
||||
- Dokan Library (driver/runtime)
|
||||
- Install the latest Dokan release (driver + library) from the official site.
|
||||
https://github.com/dokan-dev/dokany
|
||||
|
||||
## Setup
|
||||
1. Install Dokan.
|
||||
2. Create the config folder and file:
|
||||
- Folder: `C:\PhysicalDrive\`
|
||||
- File: `C:\PhysicalDrive\index.json`
|
||||
3. Populate `index.json` using the schema below.
|
||||
|
||||
### About `C:\PhysicalDrive`
|
||||
- This path is a remapped physical drive root. It can point to a USB stick or a legacy floppy that you mount to the folder `C:\PhysicalDrive\`.
|
||||
- Disk Management: Right-click the device → Change Drive Letter and Paths → Add → Mount in the empty NTFS folder `C:\PhysicalDrive\`.
|
||||
|
||||
- DevDrive just watches `C:\PhysicalDrive\index.json`; the backing device can be any removable media.
|
||||
|
||||
### index.json schema
|
||||
```json
|
||||
{
|
||||
"driveName": "Dev Disk",
|
||||
"driveIcon": "%SystemRoot%\\System32\\shell32.dll,6",
|
||||
"driveTotalMB": 100,
|
||||
"driveFreeMB": 50,
|
||||
"paths": [
|
||||
{ "name": "Projects", "path": "C:\\DEV\\Projects" },
|
||||
{ "name": "Tools", "path": "C:\\Tools" }
|
||||
]
|
||||
}
|
||||
```
|
||||
- `driveName`: Label shown in Explorer.
|
||||
- `driveIcon`: Optional custom icon. Supports file paths (e.g., `C:\\Icons\\dev.ico`) or resource references (e.g., `%SystemRoot%\\System32\\shell32.dll,6`).
|
||||
- `driveTotalMB`: Total capacity reported to Explorer.
|
||||
- `driveFreeMB`: Free space reported to Explorer.
|
||||
- `paths`: Symlinks created at the root of the mounted drive. Each entry becomes a folder that points to the real location.
|
||||
|
||||
## Build
|
||||
```powershell
|
||||
Push-Location "C:\DEV\devDrive"
|
||||
dotnet build
|
||||
Pop-Location
|
||||
```
|
||||
- Output: `bin\Debug\net8.0-windows\DevDrive.dll` and `DevDrive.exe`.
|
||||
|
||||
## Run (Console)
|
||||
```powershell
|
||||
Push-Location "C:\DEV\devDrive\bin\Debug\net8.0-windows"
|
||||
./DevDrive.exe
|
||||
Pop-Location
|
||||
```
|
||||
- Defaults: Mounts at `A:\` and reads config from `C:\PhysicalDrive\index.json`.
|
||||
- Arguments: `DevDrive.exe <MountPoint> <ConfigPath>`
|
||||
- Example:
|
||||
```powershell
|
||||
./DevDrive.exe Z:\ C:\PhysicalDrive\
|
||||
```
|
||||
|
||||
## Run (Windows Service)
|
||||
DevDrive can run as a Windows service that starts automatically on boot.
|
||||
|
||||
### Install Service
|
||||
Right-click `install-service.bat` and select **Run as administrator**.
|
||||
- Creates a service named `DevDrive`.
|
||||
- Sets it to start automatically on boot.
|
||||
- Configures automatic restart on failure.
|
||||
|
||||
### Uninstall Service
|
||||
Right-click `uninstall-service.bat` and select **Run as administrator**.
|
||||
- Stops and removes the `DevDrive` service.
|
||||
|
||||
### Manual Service Commands
|
||||
```powershell
|
||||
# Start
|
||||
sc start DevDrive
|
||||
|
||||
# Stop
|
||||
sc stop DevDrive
|
||||
|
||||
# Query status
|
||||
sc query DevDrive
|
||||
```
|
||||
|
||||
### Service Notes
|
||||
- Service logs go to the Windows Event Log (Application).
|
||||
- The service mounts to `A:\` with config from `C:\PhysicalDrive\index.json` (no command-line args in service mode).
|
||||
- To change mount point or config path when running as a service, edit `DevDriveService.cs` and rebuild.
|
||||
|
||||
## Behavior
|
||||
- Mount options: Uses Mount Manager and current session; not flagged as removable.
|
||||
- Volume label: Taken from `driveName`.
|
||||
- Icon: Applied per-user via registry under `HKCU\Software\Classes\Applications\Explorer.exe\Drives`.
|
||||
- Space reporting: `driveTotalMB` and `driveFreeMB` control what Explorer shows.
|
||||
- Symlinks: Entries in `paths` are exposed as directories at the root; contents come from the target paths.
|
||||
|
||||
## Hotplug and Config Detection
|
||||
- If `ConfigPath` is a drive letter (e.g., `E:\`): WMI `Win32_LogicalDisk` events detect insert/remove.
|
||||
- If `ConfigPath` is a folder (e.g., the remapped physical `C:\PhysicalDrive\`): WMI `Win32_Volume` events are used; unplugging the backing device makes the folder inaccessible, which triggers unmount.
|
||||
|
||||
## Troubleshooting
|
||||
- Build errors due to locked executable:
|
||||
- Stop any running `DevDrive.exe` before rebuilding.
|
||||
- Mount fails or requires elevation:
|
||||
- Mounting `A:` may require admin privileges depending on system policies.
|
||||
- Icon not updating immediately:
|
||||
- The app requests a shell refresh; if the icon still doesn’t change, sign out/in or restart Explorer.
|
||||
- Dokan not installed:
|
||||
- Ensure the Dokan driver and library are installed and loaded; reboot after installation if needed.
|
||||
|
||||
## Notes
|
||||
- By default, DevDrive mounts to `A:` with a FAT-style label, but it is not a physical floppy or removable device.
|
||||
- Registry icon changes are per-user and cleaned up on unmount.
|
||||
Reference in New Issue
Block a user