Electron.NET Documentation

Electron.NET Core is a modernized framework for building cross-platform desktop applications using ASP.NET Core and Electron. It integrates deeply with the MSBuild system, eliminating the need for external CLI tools or manual JSON configuration files.

Key features include:

• Native Visual Studio Integration: Uses MSBuild instead of CLI tools.
• Console Application Support: Allows building Electron apps from simple console applications (not limited to ASP.NET).
• Cross-Platform Development: Enables building and debugging Linux applications from Windows via WSL.
• Enhanced Debugging: Supports ASP.NET-first debugging and Hot Reload.
• Flexible Architecture: Supports choosing specific Electron versions and targeting multiple platforms.

The Electron.Tray API allows you to add icons and context menus to the system's notification area (system tray). This is useful for providing quick access to functions or maintaining application presence when windows are closed.

// Simple tray icon
await Electron.Tray.Show("assets/tray-icon.png");

// Tray icon with multiple menu items
var trayMenuItems = new[] 
{
    new MenuItem { Label = "Show Window", Click = () => ShowMainWindow() },
    new MenuItem { Label = "Settings", Click = () => OpenSettings() },
    new MenuItem { Type = MenuType.Separator },
    new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
};

await Electron.Tray.Show("assets/tray-icon.png", trayMenuItems);

The publishing process for creating distributable Electron packages depends on your application type:

• ASP.NET Apps: Use folder publishing with SelfContained=true.
• Console Apps: Use folder publishing with SelfContained=false.

The WebRequest class allows you to intercept and modify the contents of a request at various stages of its lifetime. Instances are accessed via the webRequest property of a Session (e.g., session.defaultSession.webRequest).

Key Concepts

• Filtering: Methods accept an optional filter object with a urls property (an array of URL patterns) to limit interception to specific sites.
• Listeners: Methods accept a listener function. If you pass null as the listener, you unsubscribe from that event.
• Unsubscription Warning: Only the last attached listener for a specific event will be used. Subsequent attachments overwrite previous ones.
• Callbacks: For certain events (like onBeforeSendHeaders or onHeadersReceived), the listener receives a callback function that must be called with a response object to apply modifications or redirects.

When developing in an unpackaged environment, use specific command-line flags to control which process starts first. This determines whether you are debugging the Electron/Node.js side or the .NET/ASP.NET side.

• Electron-first debugging (-unpackedelectron): Use this to debug the Electron main process and Node.js code. Electron starts first and then launches the .NET process.
• .NET-first debugging (-unpackeddotnet): Use this to debug ASP.NET/C# code with Hot Reload. The .NET application starts first and then launches the Electron process.

Since keyboard conventions vary by OS, use RuntimeInformation.IsOSPlatform to register different accelerators for macOS versus Windows/Linux.

if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
{
    // macOS specific
    Electron.GlobalShortcut.Register("Command+Comma", () =>
    {
        OpenPreferences();
    });
}
else
{
    // Windows/Linux
    Electron.GlobalShortcut.Register("Ctrl+Shift+P", () =>
    {
        OpenPreferences();
    });
}

If you are using a custom ElectronHostHook implementation, you must update your package.json to meet the new minimum version requirements for Node.js types, TypeScript, and Socket.io.

{
  "devDependencies": {
    "@types/node": "^22.18",
    "typescript": "^5.9.3"
  },
  "dependencies": {
    "socket.io": "^4.8.1"
  }
}