starred/Electron.NET
1
0
Fork 0
mirror of https://github.com/ElectronNET/Electron.NET.git synced 2026-02-04 05:34:51 +00:00
Code Issues 668 Packages Projects Releases 20 Wiki Activity
Page: Migration Guide
Pages
ASP.Net About Advanced Migration Topics App AutoUpdater Clipboard Configuration Console App Custom_main Debugging Dialog Dock GlobalShortcut Home HostHook IpcMain Menu Migration Checks Migration Guide NativeTheme Notification Overview Package Building Package Description PowerMonitor Screen Shell Startup Methods System Requirements Tray WebContents What's New WindowManager
Clone
2
Migration Guide
github-actions[bot] edited this page 2026-01-21 11:18:53 +00:00
Table of Contents

Migrating from previous versions of Electron.NET to ElectronNET.Core is straightforward but requires several important changes. This guide walks you through the process step by step.

📋 Prerequisites

Before starting the migration:

  • Backup your project - Ensure you have a working backup
  • Update development tools - Install Node.js 22.x and .NET 8.0+
  • Review current setup - Note your current Electron and ASP.NET versions

🚀 Migration Steps

Step 1: Update NuGet Packages

Uninstall old packages:

dotnet remove package  ElectronNET.API

Install new packages:

dotnet add package ElectronNET.Core
dotnet add package ElectronNET.Core.AspNet  # For ASP.NET projects

Note

: The API package is automatically included as a dependency of ElectronNET.Core. See Package Description for details about the package structure.

Step 2: Configure Project Settings

Auto-generated Configuration:
ElectronNET.Core automatically creates electron-builder.json in the Properties folder of your project during the first build or NuGet restore. No manual configuration is needed for basic setups.

Migrate Existing Configuration:
If you have an existing electron.manifest.json file:

  1. Open the generated electron-builder.json file in your project
  2. Locate the 'build' section in your old electron.manifest.json
  3. Copy the contents of the build section (not the "build" key itself) into the new electron-builder.json
  4. Use Visual Studio Project Designer to configure Electron settings through the UI
  5. Delete the old electron.manifest.json file

Alternative: Manual Configuration You can also manually edit electron-builder.json:

{
  "linux": {
    "target": [
      "tar.xz"
    ]
  },
  "win": {
    "target": [
      {
        "target": "portable",
        "arch": "x64"
      }
    ]
  }
}

Modify Launch Settings: ElectronNET.Core no longer needs a separate CLI tool (electronize.exe) for launching. You should update your launch settings to use either the ASP.NET-first or Electron-first approach. See Debugging for details.

🎯 Testing Migration

After completing the migration steps:

  1. Build your project to ensure no compilation errors
  2. Test debugging using the new ASP.NET-first approach
  3. Verify packaging works with the new configuration
  4. Check cross-platform builds if targeting multiple platforms

🚨 Common Migration Issues

Build Errors

  • Node.js version: Verify Node.js 22.x is installed and in PATH
  • Package conflicts: Clean NuGet cache if needed

Runtime Errors

  • Missing electron-builder.json: Trigger rebuild or manual NuGet restore
  • Process termination: Use .NET-first startup mode for better cleanup

🚀 Next Steps

💡 Migration Benefits

✅ Simplified Configuration - No more CLI tools or JSON files
✅ Better Debugging - Native Visual Studio experience with Hot Reload
✅ Modern Architecture - .NET-first process lifecycle
✅ Cross-Platform Ready - Build Linux apps from Windows
✅ Future-Proof - Flexible Electron version selection

Step 3: Update Startup Code

Update UseElectron() calls to include the new callback parameter. This callback executes at the right moment to initialize your Electron UI.

Modern ASP.NET Core (WebApplication)

using ElectronNET.API;
using ElectronNET.API.Entities;

    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.UseElectron(args, ElectronAppReady);

        var app = builder.Build();
        app.Run();
    }

    public static async Task ElectronAppReady()
    {
        var browserWindow = await Electron.WindowManager.CreateWindowAsync(
            new BrowserWindowOptions { Show = false });

        browserWindow.OnReadyToShow += () => browserWindow.Show();
    }

Traditional ASP.NET Core (IWebHostBuilder)

using ElectronNET.API;
using ElectronNET.API.Entities;

    public static void Main(string[] args)
    {
        WebHost.CreateDefaultBuilder(args)
            .UseElectron(args, ElectronAppReady)
            .UseStartup<Startup>()
            .Build()
            .Run();
    }

    public static async Task ElectronAppReady()
    {
        var browserWindow = await Electron.WindowManager.CreateWindowAsync(
            new BrowserWindowOptions { Show = false });

        browserWindow.OnReadyToShow += () => browserWindow.Show();
    }

Step 4: Update Development Tools

See System Requirements.

Step 5: Update Debugging Setup

Watch Feature Removal:

The old 'watch' feature is no longer supported. Instead, use the new ASP.NET-first debugging with Hot Reload:

  • Old approach: Manual process attachment and slow refresh
  • New approach: Native Visual Studio debugging with Hot Reload
  • Benefits: Faster development cycle, better debugging experience

Update Launch Settings:

Replace old watch configurations with new debugging profiles. See Debugging for detailed setup instructions.

Want to contribute to this documentation? Please fork and create a PR! The Wiki is autogenerated from the /docs content in the repository.