From c914bb8f142dda637281de218f1b2f332d7688bf Mon Sep 17 00:00:00 2001 From: softworkz Date: Tue, 14 Oct 2025 06:22:42 +0200 Subject: [PATCH] Draft for a ReadMe update --- README.md | 258 ++++++++++++------------------------------------------ 1 file changed, 55 insertions(+), 203 deletions(-) diff --git a/README.md b/README.md index c145a0d..d60b56d 100644 --- a/README.md +++ b/README.md @@ -2,47 +2,56 @@ [![donate](https://img.shields.io/badge/Donate-Donorbox-green.svg)](https://donorbox.org/electron-net) [![Gitter](https://badges.gitter.im/ElectronNET/community.svg)](https://gitter.im/ElectronNET/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Build status](https://github.com/ElectronNET/Electron.NET/actions/workflows/ci.yml/badge.svg)](https://github.com/ElectronNET/Electron.NET/actions/workflows/ci.yml) -Build cross platform desktop apps with .NET 8 and Blazor, ASP.NET Core (Razor Pages, MVC). +# Electron.Net Core is here! -Electron.NET is a __wrapper__ around a native Electron application with an embedded ASP.NET Core application. Via our Electron.NET IPC bridge we can invoke Electron APIs from .NET. +## A Complete Transformation -The CLI extensions hosts our toolset to build and start Electron.NET applications. +ElectronNET.Core represents a fundamental modernization of Electron.NET, addressing years of accumulated pain points while preserving full API compatibility. This isn't just an updateβ€”it's a complete rethinking of how .NET developers build and debug cross-platform desktop applications with Electron. -## Wait - you host a .NET Core app inside Electron? Why? +Read more: [**What's New in ElectronNET.Core**](WHATS_NEW.md) -Well... there are lots of different approaches how to get a X-plat desktop app running. We thought it would be nice for .NET devs to use the ASP.NET Core environment and just embed it inside a pretty robust X-plat enviroment called Electron. Porting Electron to .NET is not a goal of this project, at least we don't have any clue how to do it. We just combine ASP.NET Core & Electron. + +Build cross platform desktop applications with .NET 6/8 - from console apps to ASP.Net Core (Razor Pages, MVC) to Blazor + + +## Wait - how does that work exactly? + +Well... there are lots of different approaches how to get a X-plat desktop app running. Electron.NET provides a range of ways to build .NET based solutions using Electron at the side of presentation. While the classic Electron.Net setup, using an ASP.Net host ran by the Electron side is still the primary way, there's more flexibility now: both, dotnet and Electron are now able to launch the other for better lifetime management, and when you don't need a local web server - like when running content from files or remote servers, you can drop the ASP.Net stack altogether and got with a lightweight console app instead. ## πŸ“¦ NuGet -[![NuGet](https://img.shields.io/nuget/v/ElectronNET.API.svg?style=flat-square) ElectronNET.API ](https://www.nuget.org/packages/ElectronNET.API/) | [![NuGet](https://img.shields.io/nuget/v/ElectronNET.CLI.svg?style=flat-square) ElectronNET.CLI](https://www.nuget.org/packages/ElectronNET.CLI/) +[![NuGet](https://img.shields.io/nuget/v/ElectronNET.Core.svg?style=flat-square) ElectronNET.Core ](https://www.nuget.org/packages/ElectronNET.Core.API/) | [![NuGet](https://img.shields.io/nuget/v/ElectronNET.Core.API.svg?style=flat-square) ElectronNET.Core.API ](https://www.nuget.org/packages/ElectronNET.Core.API/) | [![NuGet](https://img.shields.io/nuget/v/ElectronNET.Core.AspNet.svg?style=flat-square) ElectronNET.Core.AspNet ](https://www.nuget.org/packages/ElectronNET.Core.AspNet/) + ## πŸ›  Requirements to Run -The current Electron.NET CLI builds Windows/macOS/Linux binaries. Our API uses .NET 8, so our minimum base OS is the same as [.NET 8](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md). + Our API uses .NET 6/8, so our Also you should have installed: -* npm [contained in nodejs (at least Version 16.17.1)](https://nodejs.org) +* .NET 6/8 or later +* OS + minimum base OS is the same as [.NET 6](https://github.com/dotnet/core/blob/main/release-notes/6.0/supported-os.md) / [.NET 8](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md). +* NodeJS (at least [Version 22.x](https://nodejs.org)) -## πŸ’¬ Community -[![Gitter](https://badges.gitter.im/ElectronNET/community.svg)](https://gitter.im/ElectronNET/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +## πŸ‘©β€πŸ« Usage with ASP.Net -Besides the chat on Gitter and the issues [discussed here](https://github.com/ElectronNET/Electron.NET/issues) you can also use [StackOverflow](https://stackoverflow.com/questions/tagged/electron.net) with the tag `electron.net`. - -If you want to sponsor the further maintenance and development of this project [see the donate section](#πŸ™-donate). - -## πŸ‘©β€πŸ« Usage - -To activate and communicate with the "native" (sort of native...) Electron API include the [ElectronNET.API NuGet package](https://www.nuget.org/packages/ElectronNET.API/) in your ASP.NET Core app. +- Create a new ASP.Net Core project +- Install the following two nuget packages: ```ps1 -PM> Install-Package ElectronNET.API +PM> Install-Package ElectronNET.Core + +PM> Install-Package ElectronNET.Core.AspNet ``` -## Setup Using Minimal-API +### Enable Electron.NET on Startup -You start Electron.NET up with an `UseElectron` WebHostBuilder-Extension and open the Electron Window: +To do so, use the `UseElectron` extension method on a `WebApplicationBuilder`, an `IWebHostBuilder` or any descendants. + +> [!NOTE] +> New in Electron.NET Core is that you provide a callback method as an argument to `UseElectron()`, which ensures that you get to know the right moment to set up your application UI. ### Program.cs @@ -50,93 +59,29 @@ You start Electron.NET up with an `UseElectron` WebHostBuilder-Extension and ope using ElectronNET.API; using ElectronNET.API.Entities; -var builder = WebApplication.CreateBuilder(args); -builder.WebHost.UseElectron(args); + public static void Main(string[] args) + { + WebHost.CreateDefaultBuilder(args) + .UseElectron(args, ElectronAppReady) + .UseStartup() + .Build() + .Run(); + } -// Is optional, but you can use the Electron.NET API-Classes directly with DI (relevant if you want more encoupled code) -builder.Services.AddElectron(); + public static async Task ElectronAppReady() + { + var browserWindow = await Electron.WindowManager.CreateWindowAsync( + new BrowserWindowOptions { Show = false }); -var app = builder.Build(); - -... - -await app.StartAsync(); - -// Open the Electron-Window here -await Electron.WindowManager.CreateWindowAsync(); - -app.WaitForShutdown(); + browserWindow.OnReadyToShow += () => browserWindow.Show(); + } ``` -## Setup using Normal-API -### Program.cs +## πŸš€ Starting and Debugging the Application -You start Electron.NET up with an `UseElectron` WebHostBuilder-Extension. +Just press F5 in Visual Studio or use dotnet for debugging. -```csharp -public static IHostBuilder CreateHostBuilder(string[] args) => - Host.CreateDefaultBuilder(args) - .ConfigureWebHostDefaults(webBuilder => - { - webBuilder.UseElectron(args); - webBuilder.UseStartup(); - }); -``` - -### Startup.cs - -Open the Electron Window in the *Startup.cs* file: - -```csharp -public void Configure(IApplicationBuilder app, IWebHostEnvironment env) -{ - //... - - Electron.WindowManager.CreateWindowAsync(); -} -``` - -## πŸš€ Starting the Application - -To start the application make sure you have installed the "[ElectronNET.CLI](https://www.nuget.org/packages/ElectronNET.CLI/)" packages as global tool: - -```sh -dotnet tool install ElectronNET.CLI -g -``` - -At the first time, you need an Electron.NET project initialization. Type the following command in your ASP.NET Core folder: - -```sh -electronize init -``` - -* Now a electronnet.manifest.json should appear in your ASP.NET Core project -* Now run the following: - -```sh -electronize start -``` - -### Note - -> Only the first `electronize start` is slow. The next will go on faster. - -## πŸ”­ Develop Electron.NET apps using a file watcher - -The file watcher is included with version 8.31.1 of Electron.NET. For example, a file change can trigger compilation, test execution, or deployment. The Electron.NET window will automatically refresh and new code changes will be visible more quickly. The following Electron.NET CLI command is required: - -```sh -electronize start /watch -``` - -### Note - -> Only the first `electronize start` is slow. The next will go on faster. - -## 🐞 Debugging the Application - -Start your Electron.NET application with the Electron.NET CLI command. In Visual Studio attach to your running application instance. Go in the __Debug__ Menu and click on __Attach to Process...__. Sort by your projectname on the right and select it on the list. ## πŸ“” Usage of the Electron API @@ -145,48 +90,17 @@ A complete documentation will follow. Until then take a look in the source code In this YouTube video, we show you how you can create a new project, use the Electron.NET API, debug a application and build an executable desktop app for Windows: [Electron.NET - Getting Started](https://www.youtube.com/watch?v=nuM6AojRFHk) -## ⛏ Building Release Artifacts - -Here you need the Electron.NET CLI as well. Type the following command in your ASP.NET Core folder: - -```sh -electronize build /target win -``` - -There are additional platforms available: - -```sh -electronize build /target win -electronize build /target osx -electronize build /target linux -``` - -Those three "default" targets will produce x64 packages for those platforms. - -For certain NuGet packages or certain scenarios you may want to build a pure x86 application. To support those things you can define the desired [.NET Core runtime](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog), the [electron platform](https://github.com/electron-userland/electron-packager/blob/master/docs/api.md#platform) and [electron architecture](https://github.com/electron-userland/electron-packager/blob/master/docs/api.md#arch) like this: - -```sh -electronize build /target custom "win7-x86;win32" /electron-arch ia32 -``` - -The end result should be an electron app under your __/bin/desktop__ folder. ### Note > macOS builds can't be created on Windows machines because they require symlinks that aren't supported on Windows (per [this Electron issue](https://github.com/electron-userland/electron-packager/issues/71)). macOS builds can be produced on either Linux or macOS machines. - -## πŸ”„ Update -After an update to the latest Electron.API package, an update to the latest Electron.CLI is always required. In addition, always update the CLI via NuGet: - -```sh -dotnet tool update ElectronNET.CLI -g -``` ## πŸ‘¨β€πŸ’» Authors * **[Gregor Biswanger](https://github.com/GregorBiswanger)** - (Microsoft MVP, Intel Black Belt and Intel Software Innovator) is a freelance lecturer, consultant, trainer, author and speaker. He is a consultant for large and medium-sized companies, organizations and agencies for software architecture, web- and cross-platform development. You can find Gregor often on the road attending or speaking at international conferences. - [Cross-Platform-Blog](http://www.cross-platform-blog.com) - Twitter [@BFreakout](https://www.twitter.com/BFreakout) * **[Dr. Florian Rappl](https://github.com/FlorianRappl)** - Software Developer - from Munich, Germany. Microsoft MVP & Web Geek. - [The Art of Micro Frontends](https://microfrontends.art) - [Homepage](https://florian-rappl.de) - Twitter [@florianrappl](https://twitter.com/florianrappl) +* [**softworkz**](https://github.com/softworkz) - full range developer - likes to start where others gave up - MS MVP alumni and Munich citizen as well * **[Robert Muehsig](https://github.com/robertmuehsig)** - Software Developer - from Dresden, Germany, now living & working in Switzerland. Microsoft MVP & Web Geek. - [codeinside Blog](https://blog.codeinside.eu) - Twitter [@robert0muehsig](https://twitter.com/robert0muehsig) See also the list of [contributors](https://github.com/ElectronNET/Electron.NET/graphs/contributors) who participated in this project. @@ -225,78 +139,7 @@ MIT-licensed. See [LICENSE](./LICENSE) for details. **Enjoy!** -## πŸ“ Important notes -### ElectronNET.API & ElectronNET.CLI Version 9.31.2 - -Make sure you also have the new Electron.NET API & CLI 9.31.2 version. - -```sh -dotnet tool update ElectronNET.CLI -g -``` - -This now uses [electron-builder](https://www.electron.build/configuration/configuration) and the necessary configuration to build is made in the **electron.manifest.json** file (on the build part). In addition, own Electron.NET configurations are stored (on the root). - -Please make sure that your **electron.manifest.json** file has the following new structure: - -```json -{ - "executable": "{{executable}}", - "splashscreen": { - "imageFile": "" - }, - "name": "{{executable}}", - "author": "", - "singleInstance": false, - "build": { - "appId": "com.{{executable}}.app", - "productName": "{{executable}}", - "copyright": "Copyright Β© 2020", - "buildVersion": "1.0.0", - "compression": "maximum", - "directories": { - "output": "../../../bin/Desktop" - }, - "extraResources": [ - { - "from": "./bin", - "to": "bin", - "filter": ["**/*"] - } - ], - "files": [ - { - "from": "./ElectronHostHook/node_modules", - "to": "ElectronHostHook/node_modules", - "filter": ["**/*"] - }, - "**/*" - ] - } -} -``` - -### ElectronNET.CLI Version 0.0.9 - -In the Version 0.0.9 the CLI was not a global tool and needed to be registered like this in the *.csproj*: - -```xml - - - -``` - -After you edited the *.csproj* file, you need to restore your NuGet packages within your Project. Run the following command in your ASP.NET Core folder: - -```sh -dotnet restore -``` - -If you still use this version you will need to invoke it like this: - -```sh -electronize ... -``` ### Node.js Integration @@ -324,3 +167,12 @@ public void ConfigureServices(IServiceCollection services) services.AddElectron(); } ``` + +## πŸ’¬ Community + +[![Gitter](https://badges.gitter.im/ElectronNET/community.svg)](https://gitter.im/ElectronNET/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) + +Besides the chat on Gitter and the issues [discussed here](https://github.com/ElectronNET/Electron.NET/issues) you can also use [StackOverflow](https://stackoverflow.com/questions/tagged/electron.net) with the tag `electron.net`. + +If you want to sponsor the further maintenance and development of this project [see the donate section](#πŸ™-donate). +