This commit is contained in:
softworkz
2025-10-15 12:50:31 +02:00
parent 7b812bfae7
commit 0a0e26a9dd
16 changed files with 8495 additions and 0 deletions

View File

@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<TargetPlatformVersion>8.1</TargetPlatformVersion>
<IsCodeSharingProject>true</IsCodeSharingProject>
<DefineCommonItemSchemas>true</DefineCommonItemSchemas>
</PropertyGroup>
<PropertyGroup>
<MdIncludes>**/*.md;**/*.markdown</MdIncludes>
<ImageIncludes>**/*.png;**/*.bmp;**/*.jpg;**/*.gif;**/*.mp4</ImageIncludes>
<WebIncludes>**/*.css;**/*.js;**/*.json</WebIncludes>
</PropertyGroup>
<ItemGroup>
<Compile Remove="**/*" />
<Content Remove="**/*" />
</ItemGroup>
<ItemGroup>
<None Include="$(ImageIncludes)" />
<None Include="$(WebIncludes)" />
<None Include="$(MdIncludes)" />
</ItemGroup>
</Project>

View File

@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectCapability Include="SourceItemsFromImports;SharedImports;SharedAssetsProject"/>
<ProjectCapability Include="HandlesOwnReload"/>
<ProjectCapability Include="UserSourceItems"/>
<ProjectCapability Include="OpenProjectFile"/>
<ProjectCapability Include="UseFileGlobs"/>
<ProjectCapability Include="SingleFileGenerators"/>
</ItemGroup>
<Target Name="Compile">
</Target>
<Target Name="Build">
</Target>
<Target Name="Clean">
</Target>
<Target Name="_CheckForInvalidConfigurationAndPlatform">
</Target>
</Project>

View File

@@ -0,0 +1,63 @@
# Advanced Migration Topics
// 1. WebPort
// specifying the WebPort in the manifest is no longer supported
// from commit message:
//- Removed the 'electronWebPort' handling
// When ASP.Net is launched first, then the information which port it
// should use would be coming too late; anyway, there's no need for
// letting the port number round-trip all the way through the manifest
// file, loaded by main.js and then sent to dotnet.
//
if the asp web port needs to be specified manually, this can be by setting it via MSBuild like this:
<ItemGroup>
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
</ItemGroup>
// 2. ElectronHostHook
Users who have a custom ElectronHostHook in their project, need to do the following:
In their ElectronHostHook\package.json, they need to set typescript to 5.9.3 or later. If @types/node is presnt, it must be 22.x
"devDependencies": {
"eslint": "^9.37.0",
"@types/node": "^22.18",
"typescript": "^5.9.3"
},
"dependencies": {
"archiver-utils": "^2.1.0",
"socket.io": "^4.8.1",
"exceljs": "^1.10.0"
}
}
Next step is to edit the project file and add a reference like this
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
then the following propertygroup:
<PropertyGroup>
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
</PropertyGroup>
and this itemgroup:
<ItemGroup>
<Compile Remove="publish\**" />
<Content Remove="publish\**" />
<EmbeddedResource Remove="publish\**" />
<None Remove="publish\**" />
<TypeScriptCompile Remove="**\node_modules\**" />
</ItemGroup>

View File

@@ -0,0 +1,70 @@
# Migration Guide
// Explain migration steps:
Uninstall existing package ElectronNET.API
// Install new packages:
```ps1
PM> Install-Package ElectronNET.Core
PM> Install-Package ElectronNET.Core.AspNet
```
// add link to package type description: [text](../Releases/Package-Description.md)
// the API package is a dependency of .Core, so it's auto-incldued
// Edit Properties\electron-builder.json
// it's auto-created: In VS after nuget restore, otherwise on first build - even when that fails
// Now look at the electron-manifest.json file
// 1. Manually merge everything under the 'build' property into the
// electron-builder file (omitting the build node, only its content is to be merged)
// 2. Open the project designer in VS and enter the values from the manifest file into the fields
// 3. Delete the manifest file
//
// Check ASP.Net core startup (program.cs or statup.cs, typically)
// Find the UseElectron() extension method call
// it will have an error. it needs a 3rd parameter now: the onAppReady callback.
// set this to a callback function. this gets called just in the right moment for you
// to start things going (like accessing ElectronNET classes)
### Program.cs
```csharp
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();
}
```
// Also show an example for the other case with IWebHostBuilder and Startup class
// Next, explain that the 'watch' feature is no longer supported, now that proper debugging with hot reload is possible.
// Nodejs needs to be updated to 22.x
// Important. Explain how to (for win and linux)

127
docs/Core/What's-New.md Normal file
View File

@@ -0,0 +1,127 @@
# What's New in ElectronNET.Core
## A Complete Transformation
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.
## Complete Build System Overhaul
### From CLI Complexity to MSBuild Simplicity
The most visible change is the complete elimination of the CLI tool dependency. Where developers once needed to manage complex command-line operations and JSON configuration files, everything now flows through Visual Studio's native project system.
The old `electron.manifest.json` file is gone, replaced by clean MSBuild project properties that integrate seamlessly with Visual Studio's project designer. This provides not just a better development experience, but also eliminates entire categories of configuration errors that plagued earlier versions.
### Intelligent Package Structure
The new package architecture reflects a clearer separation of concerns:
- **ElectronNET.Core** - The main package containing build logic and project system integration
- **ElectronNET.Core.Api** - Pure API definitions for Electron integration
- **ElectronNET.Core.AspNet** - ASP.NET-specific runtime components
This modular approach allows projects to include only what they need while maintaining the flexibility to scale from simple console applications to complex web applications.
## Beyond ASP.NET: Console Application Support
### A Fundamental Shift in Accessibility
One of the most significant breakthroughs in ElectronNET.Core is the removal of the ASP.NET requirement. Developers can now build Electron applications using simple console applications, dramatically expanding the use cases and removing a major barrier to adoption.
### Flexible Content Sources
Console applications with ElectronNET.Core support multiple content scenarios:
- **File System HTML/JS**: Serve static web content directly from the file system
- **Remote Server Integration**: Connect to existing web servers or APIs
- **Lightweight Architecture**: Avoid the overhead of ASP.NET when it's not needed
- **Simplified Deployment**: Package and distribute with minimal dependencies
This capability transforms ElectronNET from a web-focused framework into a versatile platform that can integrate with any HTML/JS content source, making it accessible to a much broader range of development scenarios and team structures.
## Revolutionary Development Experience
### Debugging Reimagined
The debugging experience has been completely transformed. The new ASP.NET-first launch mode means developers can now debug their .NET code directly, with full access to familiar debugging tools and Hot Reload capabilities. No more attaching to processes or working around limited debugging scenarios—the development workflow now matches standard ASP.NET development patterns.
### Cross-Platform Development Without Compromises
One of the most significant breakthroughs is the ability to build and debug Linux applications directly from Windows Visual Studio through WSL integration. Developers can now:
- Build Linux packages while working on Windows
- Debug Linux application behavior in real-time
- Test cross-platform functionality without context switching
- Deploy to Linux targets with confidence
This capability eliminates the traditional barriers between Windows development environments and Linux deployment targets.
### Flexible Runtime Identifier Support
Runtime Identifier (RID) selection is now a first-class part of the project configuration, allowing developers to explicitly target specific platforms and architectures. The build system automatically structures output folders using standard .NET conventions (`bin\net8.0\win-x64`) instead of the ambiguous `bin\Desktop` layout, making multi-target builds clean and predictable.
## Modernized Architecture
### Process Lifecycle Revolution
The underlying process architecture has been fundamentally redesigned. Instead of Electron launching first and managing the .NET process, ElectronNET.Core puts .NET in control. The .NET application launches first and runs Electron as a child process, providing:
- Better process lifecycle management
- More reliable application termination
- Enhanced error handling and recovery
- Cleaner separation between web and native concerns
This architecture supports eight different launch scenarios, covering every combination of packaged/unpackaged deployment, console/ASP.NET hosting, and dotnet-first/electron-first initialization.
### Unpackaged Development Mode
The new unpackaged run-mode transforms development workflows by using regular .NET builds with unpackaged Electron configurations. This approach leverages .NET's incremental build capabilities for both managed and native code, dramatically reducing rebuild times and improving the development feedback loop.
## Enhanced Technical Foundation
### TypeScript Integration
TypeScript compilation is now fully integrated with ASP.NET tooling, providing consistent builds across different development environments. The updated toolchain uses modern TypeScript versions with ESLint configuration, eliminating the compatibility issues that previously affected custom ElectronHostHook implementations.
### API Enhancements
The improved splash screen handling with automatic path resolution eliminates common configuration pitfalls, while maintaining full backward compatibility with existing ElectronHostHook code.
### Performance Optimizations
Package sizes have been reduced by eliminating unnecessary dependencies, while build performance has improved through intelligent incremental compilation. The new architecture also minimizes startup times through optimized build and launch procedures.
## Seamless Migration Path
### Backward Compatibility Focus
Despite the extensive changes, ElectronNET.Core maintains complete API compatibility with existing applications. The modular package structure allows for incremental adoption, and existing ElectronHostHook implementations continue to work without modification.
### Clear Upgrade Journey
The migration path is designed to be straightforward:
1. Update package references to the new structure
2. Remove the old manifest file
3. Configure project properties through Visual Studio
4. Adopt new debugging workflows at your own pace
## Future Horizons
### Unlocked Possibilities
This modernization removes the technical debt that was limiting Electron.NET's evolution. The flexible Electron versioning, integrated build system, and cross-platform capabilities create a foundation for:
- More frequent updates and feature additions
- Enhanced community contributions
- Better tooling and IDE integration
- Expanded platform support
### Version Independence
The removal of rigid Electron version coupling means developers can now choose the Electron version that best fits their needs, with build-time validation ensuring compatibility. This approach encourages community feedback and enables faster adoption of new Electron features.
## Conclusion
ElectronNET.Core represents more than just new features—it's a complete reimagining of what .NET + Electron development can be. By eliminating friction points, removing the ASP.NET requirement to support console applications, improving debugging experiences, and enabling true cross-platform development, it transforms Electron.NET from a challenging framework to work with into a modern, efficient platform for building cross-platform desktop applications.
The changes address the core issues that were driving developers away from Electron.NET while opening new possibilities for the future. This foundation will enable more rapid innovation and better support for the growing demands of cross-platform .NET development.

25
docs/Docs.shproj Normal file
View File

@@ -0,0 +1,25 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup Label="Globals">
<ProjectGuid>06caadc7-de5b-47b4-ab2a-e9501459a2d1</ProjectGuid>
</PropertyGroup>
<ItemGroup>
<Compile Remove="About\Azure\**" />
<Compile Remove="About\BuildBot\**" />
<Compile Remove="images\AzureDevOps\**" />
<Compile Remove="images\visualization\**" />
<Compile Remove="schema_printing\**" />
<EmbeddedResource Remove="About\Azure\**" />
<EmbeddedResource Remove="About\BuildBot\**" />
<EmbeddedResource Remove="images\AzureDevOps\**" />
<EmbeddedResource Remove="images\visualization\**" />
<EmbeddedResource Remove="schema_printing\**" />
<None Remove="About\Azure\**" />
<None Remove="About\BuildBot\**" />
<None Remove="images\AzureDevOps\**" />
<None Remove="images\visualization\**" />
<None Remove="schema_printing\**" />
</ItemGroup>
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Project=".docproj\DocProj.props" />
<Import Project=".docproj\DocProj.targets" />
</Project>

View File

@@ -0,0 +1,57 @@
## 🛠 Requirements to Run
Our API uses .NET 6/8, so our
Also you should have installed:
* .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))
## 👩‍🏫 Usage with ASP.Net
- Create a new ASP.Net Core project
- Install the following two nuget packages:
```ps1
PM> Install-Package ElectronNET.Core
PM> Install-Package ElectronNET.Core.AspNet
```
### Enable Electron.NET on Startup
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
```csharp
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();
}
```

View File

@@ -0,0 +1,52 @@
// Understand this code so you can explain how to set it up with console project
namespace ElectronNET.WebApp
{
using System;
using System.Threading.Tasks;
using ElectronNET.API.Entities;
public class Program
{
public static async Task Main(string[] args)
{
var runtimeController = ElectronNetRuntime.RuntimeController;
try
{
await runtimeController.Start();
await runtimeController.WaitReadyTask;
await ElectronBootstrap();
await runtimeController.WaitStoppedTask;
}
catch (Exception ex)
{
Console.WriteLine(ex);
await runtimeController.Stop().ConfigureAwait(false);
await runtimeController.WaitStoppedTask.WaitAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
}
}
public static async Task ElectronBootstrap()
{
//AddDevelopmentTests();
var browserWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions
{
Width = 1152,
Height = 940,
Show = false,
}, "https://github.com/ElectronNET/Electron.NET");
await browserWindow.WebContents.Session.ClearCacheAsync();
browserWindow.OnReadyToShow += () => browserWindow.Show();
}
}
}

View File

@@ -0,0 +1,43 @@
# Debugging
explain the ease of debugging and everything from what you've already read.
This config enables all three possible ways for unpackaged debugging:
The first and last are working by default (newly created prject). The 2nd one needs to the added manually, if desired.
{
"profiles": {
"ASP.Net (unpackaged)": {
"commandName": "Project",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
},
"applicationUrl": "http://localhost:8001/"
},
"Electron (unpackaged)": {
"commandName": "Executable",
"executablePath": "node",
"commandLineArgs": "node_modules/electron/cli.js main.js -unpackedelectron",
"workingDirectory": "$(TargetDir).electron",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"WSL": {
"commandName": "WSL2",
"launchUrl": "http://localhost:8001/",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"ASPNETCORE_URLS": "http://localhost:8001/"
},
"distributionName": ""
}
}
}
Important: The runtime identifier needs to be changed in the project when switching between Windows and WSL.

View File

@@ -0,0 +1,88 @@
# Package Building
explain how to use VS publish to create package with electron-builder.
The folder publishing is not the same between ASP.Net and console ap.
## For ASP.Net, these are working publishing profiles:
<?xml version="1.0" encoding="utf-8"?>
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
<Project>
<PropertyGroup>
<DeleteExistingFiles>true</DeleteExistingFiles>
<ExcludeApp_Data>false</ExcludeApp_Data>
<LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<PublishProvider>FileSystem</PublishProvider>
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
<WebPublishMethod>FileSystem</WebPublishMethod>
<_TargetId>Folder</_TargetId>
<SiteUrlToLaunchAfterPublish />
<TargetFramework>net8.0</TargetFramework>
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
<ProjectGuid>6ea447d9-343f-46b8-b456-66557bddbb9f</ProjectGuid>
<SelfContained>true</SelfContained>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
</PropertyGroup>
</Project>
<?xml version="1.0" encoding="utf-8"?>
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
<Project>
<PropertyGroup>
<DeleteExistingFiles>true</DeleteExistingFiles>
<ExcludeApp_Data>false</ExcludeApp_Data>
<LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<PublishProvider>FileSystem</PublishProvider>
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
<WebPublishMethod>FileSystem</WebPublishMethod>
<_TargetId>Folder</_TargetId>
<SiteUrlToLaunchAfterPublish />
<TargetFramework>net8.0</TargetFramework>
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<ProjectGuid>6ea447d9-343f-46b8-b456-66557bddbb9f</ProjectGuid>
<SelfContained>true</SelfContained>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
</PropertyGroup>
</Project>
## For a console app, these ones are working:
<?xml version="1.0" encoding="utf-8"?>
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
<Project>
<PropertyGroup>
<Configuration>Release</Configuration>
<Platform>Any CPU</Platform>
<PublishDir>publish\Release\net8.0\linux-x64</PublishDir>
<PublishProtocol>FileSystem</PublishProtocol>
<_TargetId>Folder</_TargetId>
<TargetFramework>net8.0</TargetFramework>
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
<SelfContained>false</SelfContained>
<PublishSingleFile>false</PublishSingleFile>
</PropertyGroup>
</Project>
<?xml version="1.0" encoding="utf-8"?>
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
<Project>
<PropertyGroup>
<Configuration>Release</Configuration>
<Platform>Any CPU</Platform>
<PublishDir>publish\Release\net8.0\win-x64</PublishDir>
<PublishProtocol>FileSystem</PublishProtocol>
<_TargetId>Folder</_TargetId>
<TargetFramework>net8.0</TargetFramework>
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<SelfContained>false</SelfContained>
<PublishSingleFile>false</PublishSingleFile>
<PublishReadyToRun>false</PublishReadyToRun>
</PropertyGroup>
</Project>

View File

@@ -0,0 +1,17 @@
# Startup Methods
// Explain the different startup modes
- Support new commandline flags:
- unpackedelectron
running in debug mode, electron first, so must launch dotnet
- unpackeddotnet
running in debug mode, dotnet first, do not launch dotnet
- dotnetpacked
running from electron-builder output, dotnet first, do not launch
- {none of the above flags}
running from electron-builder output, electron first, launch dotnet
![Startup Modes](../images/startup_modes.png)

4
docs/Home.md Normal file
View File

@@ -0,0 +1,4 @@
### Electron.NET Wiki Home

2
docs/_Footer.md Normal file
View File

@@ -0,0 +1,2 @@
Want to contribute to this documentation? Please fork and create a PR! The Wiki is autogenerated from the /docs content in the repository.

27
docs/_Sidebar.md Normal file
View File

@@ -0,0 +1,27 @@
<!-- First line gets deleted -->
# Wiki
- [Home](Home.md)
# Electron.NET Core
- [What's new?](Core/What's-New.md)
- [Migration Guiide](Core/Migration-Guide.md)
- [Advcanced Migration](Core/Advanced-Migration-Topics.md)
# Getting Started
- [With ASP.Net](GettingStarted/ASP.Net.md)
- [With a Console App](GettingStarted/Console-App.md)
- [Startup-Method](GettingStarted/Startup-Methods.md)
- [Debugging](GettingStarted/Debugging.md)
- [Package Building](GettingStarted/Package-Building.md)
# Release Information
- [Package Description](RelInfo/Package-Description.md)
- [Changelog](RelInfo/Changelog.md)

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

7870
docs/md-styles.css Normal file

File diff suppressed because it is too large Load Diff