Skip to content

Commit 31e8a2d

Browse files
softworkzsoftworkz
committed
Add docs
1 parent cfbba81 commit 31e8a2d

16 files changed

Lines changed: 8496 additions & 0 deletions

‎docs/.docproj/DocProj.props‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
3+
4+
<PropertyGroup>
5+
<TargetPlatformVersion>8.1</TargetPlatformVersion>
6+
<IsCodeSharingProject>true</IsCodeSharingProject>
7+
<DefineCommonItemSchemas>true</DefineCommonItemSchemas>
8+
</PropertyGroup>
9+
10+
<PropertyGroup>
11+
<MdIncludes>**/*.md;**/*.markdown</MdIncludes>
12+
<ImageIncludes>**/*.png;**/*.bmp;**/*.jpg;**/*.gif;**/*.mp4</ImageIncludes>
13+
<WebIncludes>**/*.css;**/*.js;**/*.json</WebIncludes>
14+
</PropertyGroup>
15+
16+
<ItemGroup>
17+
<Compile Remove="**/*" />
18+
<Content Remove="**/*" />
19+
</ItemGroup>
20+
21+
<ItemGroup>
22+
<None Include="$(ImageIncludes)" />
23+
<None Include="$(WebIncludes)" />
24+
<None Include="$(MdIncludes)" />
25+
</ItemGroup>
26+
27+
</Project>

‎docs/.docproj/DocProj.targets‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
3+
<ItemGroup>
4+
<ProjectCapability Include="SourceItemsFromImports;SharedImports;SharedAssetsProject"/>
5+
<ProjectCapability Include="HandlesOwnReload"/>
6+
<ProjectCapability Include="UserSourceItems"/>
7+
<ProjectCapability Include="OpenProjectFile"/>
8+
<ProjectCapability Include="UseFileGlobs"/>
9+
<ProjectCapability Include="SingleFileGenerators"/>
10+
</ItemGroup>
11+
12+
<Target Name="Compile">
13+
</Target>
14+
15+
<Target Name="Build">
16+
</Target>
17+
18+
<Target Name="Clean">
19+
</Target>
20+
21+
<Target Name="_CheckForInvalidConfigurationAndPlatform">
22+
</Target>
23+
</Project>

‎docs/Core/Advanced-Migration-Topics.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Advanced Migration Topics
2+
3+
// 1. WebPort
4+
// specifying the WebPort in the manifest is no longer supported
5+
// from commit message:
6+
//- Removed the 'electronWebPort' handling
7+
// When ASP.Net is launched first, then the information which port it
8+
// should use would be coming too late; anyway, there's no need for
9+
// letting the port number round-trip all the way through the manifest
10+
// file, loaded by main.js and then sent to dotnet.
11+
//
12+
13+
if the asp web port needs to be specified manually, this can be by setting it via MSBuild like this:
14+
15+
<ItemGroup>
16+
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
17+
</ItemGroup>
18+
19+
20+
// 2. ElectronHostHook
21+
22+
23+
Users who have a custom ElectronHostHook in their project, need to do the following:
24+
25+
26+
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
27+
28+
"devDependencies": {
29+
"eslint": "^9.37.0",
30+
"@types/node": "^22.18",
31+
"typescript": "^5.9.3"
32+
},
33+
"dependencies": {
34+
"archiver-utils": "^2.1.0",
35+
"socket.io": "^4.8.1",
36+
"exceljs": "^1.10.0"
37+
}
38+
}
39+
40+
Next step is to edit the project file and add a reference like this
41+
42+
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
43+
44+
then the following propertygroup:
45+
46+
<PropertyGroup>
47+
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
48+
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
49+
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
50+
</PropertyGroup>
51+
52+
53+
and this itemgroup:
54+
55+
<ItemGroup>
56+
<Compile Remove="publish\**" />
57+
<Content Remove="publish\**" />
58+
<EmbeddedResource Remove="publish\**" />
59+
<None Remove="publish\**" />
60+
<TypeScriptCompile Remove="**\node_modules\**" />
61+
</ItemGroup>
62+
63+

‎docs/Core/Migration-Guide.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Migration Guide
2+
3+
// Explain migration steps:
4+
5+
Uninstall existing package ElectronNET.API
6+
7+
// Install new packages:
8+
9+
10+
```ps1
11+
PM> Install-Package ElectronNET.Core
12+
13+
PM> Install-Package ElectronNET.Core.AspNet
14+
```
15+
16+
// add link to package type description: [text](../Releases/Package-Description.md)
17+
// the API package is a dependency of .Core, so it's auto-incldued
18+
19+
20+
// Edit Properties\electron-builder.json
21+
// it's auto-created: In VS after nuget restore, otherwise on first build - even when that fails
22+
23+
// Now look at the electron-manifest.json file
24+
// 1. Manually merge everything under the 'build' property into the
25+
// electron-builder file (omitting the build node, only its content is to be merged)
26+
// 2. Open the project designer in VS and enter the values from the manifest file into the fields
27+
// 3. Delete the manifest file
28+
//
29+
30+
// Check ASP.Net core startup (program.cs or statup.cs, typically)
31+
// Find the UseElectron() extension method call
32+
// it will have an error. it needs a 3rd parameter now: the onAppReady callback.
33+
// set this to a callback function. this gets called just in the right moment for you
34+
// to start things going (like accessing ElectronNET classes)
35+
36+
### Program.cs
37+
38+
```csharp
39+
using ElectronNET.API;
40+
using ElectronNET.API.Entities;
41+
42+
public static void Main(string[] args)
43+
{
44+
WebHost.CreateDefaultBuilder(args)
45+
.UseElectron(args, ElectronAppReady)
46+
.UseStartup<Startup>()
47+
.Build()
48+
.Run();
49+
}
50+
51+
public static async Task ElectronAppReady()
52+
{
53+
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
54+
new BrowserWindowOptions { Show = false });
55+
56+
browserWindow.OnReadyToShow += () => browserWindow.Show();
57+
}
58+
```
59+
60+
61+
// Also show an example for the other case with IWebHostBuilder and Startup class
62+
63+
64+
65+
// Next, explain that the 'watch' feature is no longer supported, now that proper debugging with hot reload is possible.
66+
67+
68+
// Nodejs needs to be updated to 22.x
69+
// Important. Explain how to (for win and linux)
70+

‎docs/Core/What's-New.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# What's New in ElectronNET.Core
2+
3+
## A Complete Transformation
4+
5+
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.
6+
7+
## Complete Build System Overhaul
8+
9+
### From CLI Complexity to MSBuild Simplicity
10+
11+
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.
12+
13+
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.
14+
15+
### Intelligent Package Structure
16+
17+
The new package architecture reflects a clearer separation of concerns:
18+
19+
- **ElectronNET.Core** - The main package containing build logic and project system integration
20+
- **ElectronNET.Core.Api** - Pure API definitions for Electron integration
21+
- **ElectronNET.Core.AspNet** - ASP.NET-specific runtime components
22+
23+
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.
24+
25+
## Beyond ASP.NET: Console Application Support
26+
27+
### A Fundamental Shift in Accessibility
28+
29+
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.
30+
31+
### Flexible Content Sources
32+
33+
Console applications with ElectronNET.Core support multiple content scenarios:
34+
35+
- **File System HTML/JS**: Serve static web content directly from the file system
36+
- **Remote Server Integration**: Connect to existing web servers or APIs
37+
- **Lightweight Architecture**: Avoid the overhead of ASP.NET when it's not needed
38+
- **Simplified Deployment**: Package and distribute with minimal dependencies
39+
40+
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.
41+
42+
## Revolutionary Development Experience
43+
44+
### Debugging Reimagined
45+
46+
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.
47+
48+
### Cross-Platform Development Without Compromises
49+
50+
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:
51+
52+
- Build Linux packages while working on Windows
53+
- Debug Linux application behavior in real-time
54+
- Test cross-platform functionality without context switching
55+
- Deploy to Linux targets with confidence
56+
57+
This capability eliminates the traditional barriers between Windows development environments and Linux deployment targets.
58+
59+
### Flexible Runtime Identifier Support
60+
61+
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.
62+
63+
## Modernized Architecture
64+
65+
### Process Lifecycle Revolution
66+
67+
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:
68+
69+
- Better process lifecycle management
70+
- More reliable application termination
71+
- Enhanced error handling and recovery
72+
- Cleaner separation between web and native concerns
73+
74+
This architecture supports eight different launch scenarios, covering every combination of packaged/unpackaged deployment, console/ASP.NET hosting, and dotnet-first/electron-first initialization.
75+
76+
### Unpackaged Development Mode
77+
78+
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.
79+
80+
## Enhanced Technical Foundation
81+
82+
### TypeScript Integration
83+
84+
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.
85+
86+
### API Enhancements
87+
88+
The improved splash screen handling with automatic path resolution eliminates common configuration pitfalls, while maintaining full backward compatibility with existing ElectronHostHook code.
89+
90+
### Performance Optimizations
91+
92+
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.
93+
94+
## Seamless Migration Path
95+
96+
### Backward Compatibility Focus
97+
98+
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.
99+
100+
### Clear Upgrade Journey
101+
102+
The migration path is designed to be straightforward:
103+
1. Update package references to the new structure
104+
2. Remove the old manifest file
105+
3. Configure project properties through Visual Studio
106+
4. Adopt new debugging workflows at your own pace
107+
108+
## Future Horizons
109+
110+
### Unlocked Possibilities
111+
112+
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:
113+
114+
- More frequent updates and feature additions
115+
- Enhanced community contributions
116+
- Better tooling and IDE integration
117+
- Expanded platform support
118+
119+
### Version Independence
120+
121+
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.
122+
123+
## Conclusion
124+
125+
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.
126+
127+
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.

‎docs/Docs.shproj‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup Label="Globals">
3+
<ProjectGuid>06caadc7-de5b-47b4-ab2a-e9501459a2d1</ProjectGuid>
4+
</PropertyGroup>
5+
<ItemGroup>
6+
<Compile Remove="About\Azure\**" />
7+
<Compile Remove="About\BuildBot\**" />
8+
<Compile Remove="images\AzureDevOps\**" />
9+
<Compile Remove="images\visualization\**" />
10+
<EmbeddedResource Remove="About\Azure\**" />
11+
<EmbeddedResource Remove="About\BuildBot\**" />
12+
<EmbeddedResource Remove="images\AzureDevOps\**" />
13+
<EmbeddedResource Remove="images\visualization\**" />
14+
<None Remove="About\Azure\**" />
15+
<None Remove="About\BuildBot\**" />
16+
<None Remove="images\AzureDevOps\**" />
17+
<None Remove="images\visualization\**" />
18+
</ItemGroup>
19+
<ItemGroup>
20+
<None Include="schema_printing\ffprobe_original.xsd" />
21+
</ItemGroup>
22+
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
23+
<Import Project=".docproj\DocProj.props" />
24+
<Import Project=".docproj\DocProj.targets" />
25+
</Project>

‎docs/GettingStarted/ASP.Net.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
2+
3+
## 🛠 Requirements to Run
4+
5+
Our API uses .NET 6/8, so our
6+
7+
Also you should have installed:
8+
9+
* .NET 6/8 or later
10+
* OS
11+
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).
12+
* NodeJS (at least [Version 22.x](https://nodejs.org))
13+
14+
15+
## 👩‍🏫 Usage with ASP.Net
16+
17+
- Create a new ASP.Net Core project
18+
- Install the following two nuget packages:
19+
20+
```ps1
21+
PM> Install-Package ElectronNET.Core
22+
23+
PM> Install-Package ElectronNET.Core.AspNet
24+
```
25+
26+
### Enable Electron.NET on Startup
27+
28+
To do so, use the `UseElectron` extension method on a `WebApplicationBuilder`, an `IWebHostBuilder` or any descendants.
29+
30+
> [!NOTE]
31+
> 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.
32+
33+
### Program.cs
34+
35+
```csharp
36+
using ElectronNET.API;
37+
using ElectronNET.API.Entities;
38+
39+
public static void Main(string[] args)
40+
{
41+
WebHost.CreateDefaultBuilder(args)
42+
.UseElectron(args, ElectronAppReady)
43+
.UseStartup<Startup>()
44+
.Build()
45+
.Run();
46+
}
47+
48+
public static async Task ElectronAppReady()
49+
{
50+
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
51+
new BrowserWindowOptions { Show = false });
52+
53+
browserWindow.OnReadyToShow += () => browserWindow.Show();
54+
}
55+
```
56+
57+

0 commit comments

Comments
 (0)