App

Control your application's event lifecycle.

Overview

The Electron.App API provides comprehensive control over your application's lifecycle, including startup, shutdown, window management, and system integration. It handles application-level events and provides methods for managing the overall application state.

Key Methods

Application Lifecycle

Quit

Description: Try to close all windows. The BeforeQuit event will be emitted first. If all windows are successfully closed, the WillQuit event will be emitted and by default the application will terminate.

Exit

Parameters:

• exitCode (optional) - Exits immediately with exitCode. Defaults to 0.

Description: All windows will be closed immediately without asking user and the BeforeQuit and WillQuit events will not be emitted.

Relaunch

Description: Relaunches the app when current instance exits. By default the new instance will use the same working directory and command line arguments with current instance.

Relaunch(RelaunchOptions)

Parameters:

• relaunchOptions - Options for the relaunch

Description: Relaunches the app with custom options for executable path and arguments.

Window Management

Focus

Description: On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.

Focus(FocusOptions)

Parameters:

• focusOptions - Focus options

Description: Focus application with additional options like steal focus.

Hide

Description: Hides all application windows without minimizing them.

Show

Description: Shows application windows after they were hidden. Does not automatically focus them.

Application Information

GetAppPathAsync

Returns: The current application directory.

GetVersionAsync

Returns: The version of the loaded application.

GetLocaleAsync

Returns: The current application locale.

Name

Description: A string property that indicates the current application's name.

NameAsync

Returns: The current application's name as a Task.

Path Management

GetPathAsync(PathName)

Parameters:

• pathName - Special directory name

Returns: A path to a special directory or file associated with name.

SetPath(PathName, string)

Parameters:

• name - Special directory name
• path - New path to a special directory

Description: Overrides the path to a special directory or file associated with name.

SetAppLogsPath(string)

Parameters:

• path - A custom path for your logs. Must be absolute

Description: Sets or creates a directory your app's logs which can then be manipulated with GetPathAsync or SetPath.

Protocol Handling

SetAsDefaultProtocolClientAsync(string, CancellationToken)

Parameters:

• protocol - The name of your protocol, without ://
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

SetAsDefaultProtocolClientAsync(string, string, CancellationToken)

Parameters:

• protocol - The name of your protocol, without ://
• path - The path to the Electron executable. Defaults to process.execPath
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

SetAsDefaultProtocolClientAsync(string, string, string[], CancellationToken)

Parameters:

• protocol - The name of your protocol, without ://
• path - The path to the Electron executable. Defaults to process.execPath
• args - Arguments passed to the executable. Defaults to an empty array
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

IsDefaultProtocolClientAsync(string, CancellationToken)

Parameters:

• protocol - The name of your protocol, without ://
• cancellationToken (optional) - The cancellation token

Returns: Whether the current executable is the default handler for a protocol.

RemoveAsDefaultProtocolClientAsync(string, CancellationToken)

Parameters:

• protocol - The name of your protocol, without ://
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

Jump List Management (Windows)

SetUserTasksAsync(UserTask[], CancellationToken)

Parameters:

• userTasks - Array of UserTask objects
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

GetJumpListSettingsAsync(CancellationToken)

Returns: Jump List settings.

SetJumpList(JumpListCategory[])

Parameters:

• categories - Array of JumpListCategory objects

Description: Sets or removes a custom Jump List for the application.

Single Instance Management

RequestSingleInstanceLockAsync(Action<string[], string>, CancellationToken)

Parameters:

• newInstanceOpened - Callback with an array of the second instance's command line arguments
• cancellationToken (optional) - The cancellation token

Returns: Whether this process is the primary instance.

ReleaseSingleInstanceLock

Description: Releases all locks that were created by makeSingleInstance. This will allow multiple instances of the application to once again run side by side.

HasSingleInstanceLockAsync(CancellationToken)

Returns: Whether this instance of your app is currently holding the single instance lock.

Login Items (macOS/Windows)

GetLoginItemSettingsAsync(CancellationToken)

Returns: Login item settings.

GetLoginItemSettingsAsync(LoginItemSettingsOptions, CancellationToken)

Parameters:

• options - Login item settings options
• cancellationToken (optional) - The cancellation token

Returns: Login item settings.

SetLoginItemSettings(LoginSettings)

Parameters:

• loginSettings - Login settings

Description: Set the app's login item settings.

Activity Management (macOS)

SetUserActivity(string, object)

Parameters:

• type - Uniquely identifies the activity
• userInfo - App-specific state to store for use by another device

Description: Creates an NSUserActivity and sets it as the current activity.

SetUserActivity(string, object, string)

Parameters:

• type - Uniquely identifies the activity
• userInfo - App-specific state to store for use by another device
• webpageUrl - The webpage to load in a browser if no suitable app is installed

Description: Creates an NSUserActivity and sets it as the current activity.

GetCurrentActivityTypeAsync(CancellationToken)

Returns: The type of the currently running activity.

InvalidateCurrentActivity

Description: Invalidates the current Handoff user activity.

ResignCurrentActivity

Description: Marks the current Handoff user activity as inactive without invalidating it.

System Integration

SetAppUserModelId(string)

Parameters:

• id - Model Id

Description: Changes the Application User Model ID to id.

AddRecentDocument(string)

Parameters:

• path - Path to add

Description: Adds path to the recent documents list.

ClearRecentDocuments

Description: Clears the recent documents list.

SetBadgeCountAsync(int, CancellationToken)

Parameters:

• count - Counter badge
• cancellationToken (optional) - The cancellation token

Returns: Whether the call succeeded.

GetBadgeCountAsync(CancellationToken)

Returns: The current value displayed in the counter badge.

IsUnityRunningAsync(CancellationToken)

Returns: Whether the current desktop environment is Unity launcher.

Security & Certificates

ImportCertificateAsync(ImportCertificateOptions, CancellationToken)

Parameters:

• options - Import certificate options
• cancellationToken (optional) - The cancellation token

Returns: Result of import. Value of 0 indicates success.

System Information

GetAppMetricsAsync(CancellationToken)

Returns: Array of ProcessMetric objects that correspond to memory and cpu usage statistics of all the processes associated with the app.

GetGpuFeatureStatusAsync(CancellationToken)

Returns: The Graphics Feature Status from chrome://gpu/.

IsAccessibilitySupportEnabledAsync(CancellationToken)

Returns: true if Chrome's accessibility support is enabled, false otherwise.

SetAccessibilitySupportEnabled(bool)

Parameters:

• enabled - Enable or disable accessibility tree rendering

Description: Manually enables Chrome's accessibility support.

User Interface

ShowAboutPanel

Description: Show the app's about panel options.

SetAboutPanelOptions(AboutPanelOptions)

Parameters:

• options - About panel options

Description: Set the about panel options.

UserAgentFallback

Description: A string which is the user agent string Electron will use as a global fallback.

UserAgentFallbackAsync

Returns: The user agent string Electron will use as a global fallback.

Events

WindowAllClosed

Description: Emitted when all windows have been closed.

BeforeQuit

Description: Emitted before the application starts closing its windows.

WillQuit

Description: Emitted when all windows have been closed and the application will quit.

Quitting

Description: Emitted when the application is quitting.

BrowserWindowBlur

Description: Emitted when a BrowserWindow blurred.

BrowserWindowFocus

Description: Emitted when a BrowserWindow gets focused.

BrowserWindowCreated

Description: Emitted when a new BrowserWindow is created.

WebContentsCreated

Description: Emitted when a new WebContents is created.

AccessibilitySupportChanged

Description: Emitted when Chrome's accessibility support changes.

Ready

Description: Emitted when the application has finished basic startup.

OpenFile

Description: Emitted when a macOS user wants to open a file with the application.

OpenUrl

Description: Emitted when a macOS user wants to open a URL with the application.

Usage Examples

Application Lifecycle

// Handle app startup
Electron.App.Ready += () =>
{
    Console.WriteLine("App is ready!");
};

// Handle window management
Electron.App.WindowAllClosed += () =>
{
    if (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
    {
        Electron.App.Quit();
    }
};

// Prevent quit
Electron.App.BeforeQuit += async (args) =>
{
    var result = await Electron.Dialog.ShowMessageBoxAsync("Do you want to quit?");
    if (result.Response == 1) // Cancel
    {
        args.PreventDefault = true;
    }
};

Protocol Handling

// Register custom protocol
var success = await Electron.App.SetAsDefaultProtocolClientAsync("myapp");

// Check if registered
var isDefault = await Electron.App.IsDefaultProtocolClientAsync("myapp");

Jump List (Windows)

// Set user tasks
await Electron.App.SetUserTasksAsync(new[]
{
    new UserTask
    {
        Program = "myapp.exe",
        Arguments = "--new-document",
        Title = "New Document",
        Description = "Create a new document"
    }
});

Application Information

// Get app information
var appPath = await Electron.App.GetAppPathAsync();
var version = await Electron.App.GetVersionAsync();
var locale = await Electron.App.GetLocaleAsync();

// Set app name
await Electron.App.NameAsync; // Get current name
Electron.App.Name = "My Custom App Name";

Badge Count (macOS/Linux)

// Set badge count
await Electron.App.SetBadgeCountAsync(5);

// Get current badge count
var count = await Electron.App.GetBadgeCountAsync();

Related APIs

• Electron.WindowManager - Window creation and management
• Electron.Dialog - User interaction dialogs
• Electron.Menu - Application menus

Additional Resources

• Electron App Documentation - Official Electron app API
• Startup Methods - Different application startup modes