Crate win_desktop_utils

Expand description

Windows desktop helpers for Rust apps.

win-desktop-utils wraps a focused set of Windows desktop chores that many GUI, tray, installer-adjacent, and local utility apps need, while keeping raw Win32 shell, shortcut, mutex, known-folder, and elevation APIs out of the application code that uses them.

The low-level helpers stay available as small functions, and DesktopApp keeps common app startup and app-data setup in one place. On non-Windows targets, the public API still compiles and operational helpers return Error::Unsupported.

§When To Use This

Need	Start with	Feature
App identity, app-data paths, and one-instance startup	`DesktopApp`	`app`
Per-user local or roaming app-data directories	`ensure_local_app_data` or `ensure_roaming_app_data`	`paths`
Current-session single-instance behavior	`single_instance`	`instance`
Global or builder-style single-instance behavior	`single_instance_with_scope` or `SingleInstanceOptions`	`instance`
Open files, folders, URLs, Properties, or print verbs	`open_with_default`, `open_url`, or `open_with_verb`	`shell`
Select a path in Explorer	`reveal_in_explorer`	`shell`
Move files or folders to the Recycle Bin	`move_to_recycle_bin` or `move_paths_to_recycle_bin`	`recycle-bin`
Create `.lnk` or `.url` shortcuts	`create_shortcut` or `create_url_shortcut`	`shortcuts`
Check or request administrator elevation	`is_elevated`, `restart_as_admin`, or `run_as_admin`	`elevation`

This crate is Windows-first. Non-Windows builds provide stubs so cross-platform applications can depend on the crate without wrapping the dependency itself in cfg(windows).

§When Not To Use This

Use the windows crate directly when you need broad Win32 coverage, custom flags, direct COM object ownership, or APIs outside this crate’s small desktop-app scope. Use a GUI framework when you need windows, controls, rendering, menus, or native widgets.

§Quick Start

fn main() -> Result<(), win_desktop_utils::Error> {
    let app = win_desktop_utils::DesktopApp::new(format!(
        "demo-app-{}",
        std::process::id()
    ))?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("already running");
            return Ok(());
        }
    };

    let local = app.ensure_local_data_dir()?;
    assert!(local.exists());

    Ok(())
}

§Feature Flags

Default features enable the full API. Consumers can opt out and select only the modules they need:

[dependencies]
win-desktop-utils = { version = "0.5", default-features = false, features = ["paths", "instance"] }

Cross-platform applications can also keep the dependency Windows-only:

[target.'cfg(windows)'.dependencies]
win-desktop-utils = "0.5"

Available features:

app: DesktopApp facade for app-data and single-instance startup.
paths: per-user local and roaming app-data helpers.
instance: named-mutex single-instance helpers.
shell: shell opening, URL, Explorer, and shell-verb helpers.
recycle-bin: Recycle Bin move and empty helpers.
shortcuts: .lnk and .url shortcut helpers.
elevation: elevation detection and shell-based relaunch helpers.

The default feature set is intentionally broad for convenience. Feature flags control this crate’s public modules; the underlying windows dependency uses one shared set of Win32 bindings when any Windows API feature is enabled. CI checks no-default, each individual public feature, and every pairwise public feature combination.

§Common Workflows

Startup guard plus app-data directory:

let app = win_desktop_utils::DesktopApp::new(format!(
    "workflow-demo-{}",
    std::process::id()
))?;
let _guard = app.single_instance()?.expect("first instance");
let config_dir = app.ensure_local_data_dir()?;
assert!(config_dir.exists());

Create a shortcut:

let shortcut = std::env::current_dir()?.join("notepad.lnk");
let options = win_desktop_utils::ShortcutOptions::new()
    .description("Open Notepad");
win_desktop_utils::create_shortcut(&shortcut, r"C:\Windows\notepad.exe", &options)?;

Relaunch the current executable as administrator:

use std::ffi::OsString;

if !win_desktop_utils::is_elevated()? {
    win_desktop_utils::restart_as_admin(&[OsString::from("--elevated")])?;
}

§Behavior And Side Effects

open_with_default requires a non-empty existing path.
open_with_verb uses ShellExecuteW with the requested shell verb.
show_properties and print_with_default are small shell-verb wrappers.
open_url trims surrounding whitespace before delegating to the Windows shell.
reveal_in_explorer requires an existing path and launches explorer.exe.
open_containing_folder opens the existing path’s parent directory.
move_to_recycle_bin requires an absolute existing path and uses IFileOperation on a dedicated STA thread for recycle-bin behavior.
move_paths_to_recycle_bin validates all paths before starting one shell recycle-bin operation.
empty_recycle_bin permanently empties the Recycle Bin without showing shell UI.
create_shortcut uses IShellLinkW on a dedicated STA thread.
roaming_app_data and local_app_data resolve their base directories via SHGetKnownFolderPath after rejecting empty or NUL-containing app names.
single_instance uses a Local\... named mutex, so the lock is scoped to the current Windows session, and app_id cannot contain backslashes.
single_instance_with_scope can opt into either the current-session or global mutex namespace.
restart_as_admin starts a new elevated instance of the current executable, does not terminate the current process, and rejects arguments containing NUL bytes.
run_as_admin and run_with_verb launch arbitrary commands through ShellExecuteW.

§Runtime Model

The crate does not start a background runtime, async executor, telemetry, or global worker. Most helpers validate input and then delegate to Windows. The shortcut and Recycle Bin helpers use short-lived STA worker threads for COM operations that require apartment-threaded shell APIs.

§Stability

The minimum supported Rust version is 1.82. Public API compatibility is checked in CI with cargo-semver-checks, and dependency policy is checked with cargo-deny.

Re-exports§

pub use error::Error;
pub use error::Result;
pub use app::DesktopApp;
pub use elevation::is_elevated;
pub use elevation::restart_as_admin;
pub use elevation::run_as_admin;
pub use elevation::run_with_verb;
pub use instance::single_instance;
pub use instance::single_instance_with_options;
pub use instance::single_instance_with_scope;
pub use instance::InstanceGuard;
pub use instance::InstanceScope;
pub use instance::SingleInstanceOptions;
pub use paths::ensure_local_app_data;
pub use paths::ensure_roaming_app_data;
pub use paths::local_app_data;
pub use paths::roaming_app_data;
pub use shell::empty_recycle_bin;
pub use shell::empty_recycle_bin_for_root;
pub use shell::move_paths_to_recycle_bin;
pub use shell::move_to_recycle_bin;
pub use shell::open_containing_folder;
pub use shell::open_url;
pub use shell::open_with_default;
pub use shell::open_with_verb;
pub use shell::print_with_default;
pub use shell::reveal_in_explorer;
pub use shell::show_properties;
pub use shortcuts::create_shortcut;
pub use shortcuts::create_url_shortcut;
pub use shortcuts::ShortcutIcon;
pub use shortcuts::ShortcutOptions;

Modules§

app: App-startup facade for identity, app-data paths, and single-instance guards.
elevation: Elevation helpers for checking admin state and relaunching through UAC.
error: Shared error and result types for the crate.
instance: Single-instance helpers backed by named Windows mutexes.
paths: Helpers for resolving and creating per-user application data directories.
shell: Shell-facing helpers for opening files, URLs, Explorer selections, and the Recycle Bin.
shortcuts: Shortcut helpers for Windows .lnk and .url files.