Merge branch 'main' of https://github.com/ElectronNET/Electron.NET into develop

Author: FlorianRappl

docs/Using/Custom_main.md

@@ -0,0 +1,74 @@
+# Using custom_main.js
+
+This guide explains how to include and use a `custom_main.js` file in your Electron.NET application for advanced Electron/Node.js customization.
+
+## Why use custom_main.js?
+
+- Register custom protocol handlers (e.g., `myapp://`) — protocols must be registered before the app is fully initialized
+- Integrate Node.js modules (e.g., telemetry, OS APIs)
+- Control startup logic (abort, environment checks)
+- Set up IPC messaging or preload scripts
+
+## Step-by-Step Process
+
+### 1. Create the custom_main.js file
+
+Place your custom logic in `electron/custom_main.js`:
+
+```javascript
+module.exports.onStartup = function(host) {
+    // Example: Register a global shortcut for opening dev tools
+    const { app, globalShortcut, BrowserWindow } = require('electron');
+    app.on('ready', () => {
+        const ret = globalShortcut.register('Control+Shift+I', () => {
+            BrowserWindow.getAllWindows().forEach(win => win.webContents.openDevTools());
+            console.log('Ctrl+Shift+I is pressed: DevTools opened!');
+        });
+    });
+    app.on('will-quit', () => {
+        globalShortcut.unregisterAll();
+    });
+    return true;
+};
+```
+
+### 2. Configure your .csproj to copy custom_main.js to output
+
+Add this to your `.csproj` file:
+
+```xml
+<ItemGroup>
+  <None Update="electron\custom_main.js">
+    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    <TargetPath>.electron\custom_main.js</TargetPath>
+  </None>
+</ItemGroup>
+```
+
+### 3. Build and run your app
+
+Use the standard build/run commands:
+
+```powershell
+dotnet build
+dotnet run
+```
+
+Electron.NET will automatically load and execute your `custom_main.js` before initializing the .NET backend.
+
+## Advanced Usage
+
+Use environment variables to control features:
+
+  ```javascript
+  const env = process.env.ASPNETCORE_ENVIRONMENT || 'Production';
+  if (env === 'Development') { /* enable dev features */ }
+  ```
+
+## Notes
+
+- `custom_main.js` must use CommonJS syntax (`module.exports.onStartup = ...`).
+- Place the file in your source directory and copy it to `.electron` using `.csproj`.
+- Electron.NET will abort startup if `onStartup` returns `false`.
+
+### Complete example is available here [ElectronNetSampleApp](https://github.com/niteshsinghal85/ElectronNetSampleApp)

docs/_Sidebar.md

@@ -24,6 +24,7 @@
 - [Startup-Methods](Using/Startup-Methods.md)
 - [Debugging](Using/Debugging.md)
 - [Package Building](Using/Package-Building.md)
+- [Adding a `custom_main.js`](Using/Custom_main.md)
 
 # API Reference
 

src/ElectronNET.Samples.ElectronHostHook/Controllers/HomeController.cs

@@ -0,0 +1,21 @@
+using ElectronNET.API;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ElectronNET.Samples.ElectronHostHook.Controllers
+{
+    public class HomeController : Controller
+    {
+        public async Task<IActionResult> Index()
+        {
+            string message = "Electron not active";
+            if (HybridSupport.IsElectronActive)
+            {
+                // Call the HostHook defined in ElectronHostHook/index.ts
+                var result = await Electron.HostHook.CallAsync<string>("ping", "Hello from C#");
+                message = $"Sent 'Hello from C#', Received: '{result}'";
+            }
+
+            return View("Index", message);
+        }
+    }
+}

src/ElectronNET.Samples.ElectronHostHook/ElectronHostHook/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.js
+*.js.map

src/ElectronNET.Samples.ElectronHostHook/ElectronHostHook/connector.ts

@@ -0,0 +1,21 @@
+import { Socket } from "socket.io";
+
+export class Connector {
+    constructor(private socket: Socket, public app: any) {
+    }
+
+    on(key: string, javaScriptCode: Function): void {
+        this.socket.on(key, (...args: any[]) => {
+            const id: string = args.pop();
+            try {
+                javaScriptCode(...args, (data) => {
+                    if (data) {
+                        this.socket.emit(`${key}Complete${id}`, data);
+                    }
+                });
+            } catch (error) {
+                this.socket.emit(`${key}Error${id}`, `Host Hook Exception`, error);
+            }
+        });
+    }
+}

src/ElectronNET.Samples.ElectronHostHook/ElectronHostHook/index.ts

@@ -0,0 +1,16 @@
+import { Connector } from "./connector";
+import { Socket } from "socket.io";
+
+export class HookService extends Connector {
+    constructor(socket: Socket, public app: any) {
+        super(socket, app);
+    }
+
+    onHostReady(): void {
+        // execute your own JavaScript Host logic here
+        this.on("ping", (msg, done) => {
+            console.log("Received ping from C#:", msg);
+            done("pong: " + msg);
+        });
+    }
+}

src/ElectronNET.Samples.ElectronHostHook/ElectronHostHook/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "electron-host-hook",
+  "version": "1.0.0",
+  "description": "Connector for Electron.NET projects.",
+  "main": "index.js",
+  "dependencies": {
+    "socket.io": "^4.8.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

src/ElectronNET.Samples.ElectronHostHook/ElectronHostHook/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2019",
+    "sourceMap": true,
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules"]
+}

src/ElectronNET.Samples.ElectronHostHook/ElectronNET.Samples.ElectronHostHook.csproj

@@ -0,0 +1,36 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <ElectronNetDevMode>true</ElectronNetDevMode>
+  </PropertyGroup>
+
+  <Import Project="..\ElectronNET\build\ElectronNET.Core.props" Condition="$(ElectronNetDevMode)" />
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
+    <AspNetCoreModuleName>AspNetCoreModule</AspNetCoreModuleName>
+    <IsPackable>false</IsPackable>
+    <TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
+    <TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
+    <TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
+    <TypeScriptCompileOnSaveEnabled>true</TypeScriptCompileOnSaveEnabled>
+    <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <TypeScriptCompile Remove="**\node_modules\**" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\ElectronNET.API\ElectronNET.API.csproj" Condition="$(ElectronNetDevMode)" />
+    <ProjectReference Include="..\ElectronNET.AspNet\ElectronNET.AspNet.csproj" Condition="$(ElectronNetDevMode)" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="ElectronNET.Core" Version="0.2.0" Condition="'$(ElectronNetDevMode)' != 'true'" />
+    <PackageReference Include="ElectronNET.Core.AspNet" Version="0.2.0" Condition="'$(ElectronNetDevMode)' != 'true'" />
+    <PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
+  </ItemGroup>
+
+  <Import Project="..\ElectronNET\build\ElectronNET.Core.targets" Condition="$(ElectronNetDevMode)" />
+</Project>

src/ElectronNET.Samples.ElectronHostHook/Program.cs

@@ -0,0 +1,31 @@
+using ElectronNET.API;
+
+namespace ElectronNET.Samples.ElectronHostHook
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            var builder = WebApplication.CreateBuilder(args);
+
+            builder.WebHost.UseElectron(args, async () =>
+            {
+                var window = await Electron.WindowManager.CreateWindowAsync();
+            });
+
+            builder.Services.AddElectron();
+            builder.Services.AddControllersWithViews();
+
+            var app = builder.Build();
+
+            app.UseStaticFiles();
+            app.UseRouting();
+
+            app.MapControllerRoute(
+                name: "default",
+                pattern: "{controller=Home}/{action=Index}/{id?}");
+
+            app.Run();
+        }
+    }
+}