Electron.NET/docs/API/Shell.md

Electron.Shell

Desktop integration for opening files, URLs, and accessing system paths.

Overview

The Electron.Shell API provides system integration functionality for opening files and URLs with their default applications, managing trash/recycle bin, and creating/reading shortcut links.

Methods

🧊 void Beep()

Play the beep sound.

🧊 Task<string> OpenExternalAsync(string url)

Open the given external protocol URL in the desktop's default manner (e.g., mailto: URLs in the user's default mail agent).

Parameters:

• url - Max 2081 characters on windows

Returns:

The error message corresponding to the failure if a failure occurred, otherwise empty string.

🧊 Task<string> OpenExternalAsync(string url, OpenExternalOptions options)

Open the given external protocol URL with additional options.

Parameters:

• url - Max 2081 characters on windows
• options - Controls the behavior of OpenExternal

Returns:

The error message corresponding to the failure if a failure occurred, otherwise empty string.

🧊 Task<string> OpenPathAsync(string path)

Open the given file in the desktop's default manner.

Parameters:

• path - The path to the directory or file

Returns:

The error message corresponding to the failure if a failure occurred, otherwise empty string.

🧊 Task<ShortcutDetails> ReadShortcutLinkAsync(string shortcutPath)

Resolves the shortcut link at shortcutPath. An exception will be thrown when any error happens.

Parameters:

• shortcutPath - The path to the shortcut

Returns:

ShortcutDetails of the shortcut.

🧊 Task ShowItemInFolderAsync(string fullPath)

Show the given file in a file manager. If possible, select the file.

Parameters:

• fullPath - The full path to the directory or file

🧊 Task<bool> TrashItemAsync(string fullPath)

Move the given file to trash and returns a bool status for the operation.

Parameters:

• fullPath - The full path to the directory or file

Returns:

Whether the item was successfully moved to the trash.

🧊 Task<bool> WriteShortcutLinkAsync(string shortcutPath, ShortcutLinkOperation operation, ShortcutDetails options)

Creates or updates a shortcut link at shortcutPath.

Parameters:

• shortcutPath - The path to the shortcut
• operation - Default is ShortcutLinkOperation.Create
• options - Structure of a shortcut

Returns:

Whether the shortcut was created successfully.

Usage Examples

File Operations

// Open file with default application
var error = await Electron.Shell.OpenPathAsync(filePath);
if (string.IsNullOrEmpty(error))
{
    Console.WriteLine("File opened successfully");
}
else
{
    Console.WriteLine($"Failed to open file: {error}");
}

// Show file in file manager
await Electron.Shell.ShowItemInFolderAsync(filePath);

// Move file to trash
var trashed = await Electron.Shell.TrashItemAsync(filePath);
Console.WriteLine($"File trashed: {trashed}");

URL Operations

// Open URL in default browser
var error = await Electron.Shell.OpenExternalAsync("https://electron.net");
if (!string.IsNullOrEmpty(error))
{
    Console.WriteLine($"Failed to open URL: {error}");
}

// Open email client
await Electron.Shell.OpenExternalAsync("mailto:user@example.com");

// Open with options
var error = await Electron.Shell.OpenExternalAsync("https://example.com", new OpenExternalOptions
{
    Activate = true
});

System Integration

// Play system beep
Electron.Shell.Beep();

// Create desktop shortcut
var success = await Electron.Shell.WriteShortcutLinkAsync(
    @"C:\Users\Public\Desktop\MyApp.lnk",
    ShortcutLinkOperation.Create,
    new ShortcutDetails
    {
        Target = "C:\\Program Files\\MyApp\\MyApp.exe",
        Description = "My Application",
        WorkingDirectory = "C:\\Program Files\\MyApp"
    }
);

// Read shortcut information
var details = await Electron.Shell.ReadShortcutLinkAsync(@"C:\Users\Public\Desktop\MyApp.lnk");
Console.WriteLine($"Target: {details.Target}");

Integration with Dialog API

// Use with file dialog results
var files = await Electron.Dialog.ShowOpenDialogAsync(window, options);
if (files.Length > 0)
{
    var selectedFile = files[0];

    // Open the selected file
    await Electron.Shell.OpenPathAsync(selectedFile);

    // Show in file manager
    await Electron.Shell.ShowItemInFolderAsync(selectedFile);
}

Related APIs

• Electron.Dialog - Select files to open with Shell
• Electron.App - Application lifecycle events
• Electron.Clipboard - Copy file paths for Shell operations

Additional Resources

• Electron Shell Documentation - Official Electron shell API