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.

Key Methods

File Operations

ShowItemInFolderAsync(string)

Parameters:

• fullPath - The full path to the directory or file

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

OpenPathAsync(string)

Parameters:

• path - The path to the directory or file

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

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

TrashItemAsync(string)

Parameters:

• fullPath - The full path to the directory or file

Returns: Whether the item was successfully moved to the trash.

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

URL Operations

OpenExternalAsync(string)

Parameters:

• url - Max 2081 characters on windows

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

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

OpenExternalAsync(string, OpenExternalOptions)

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.

Description: Open the given external protocol URL with additional options.

System Operations

Beep

Description: Play the beep sound.

Shortcut Management

WriteShortcutLinkAsync(string, ShortcutLinkOperation, ShortcutDetails)

Parameters:

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

Returns: Whether the shortcut was created successfully.

Description: Creates or updates a shortcut link at shortcutPath.

ReadShortcutLinkAsync(string)

Parameters:

• shortcutPath - The path to the shortcut

Returns: ShortcutDetails of the shortcut.

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

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:[email protected]");

// 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