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

Update docs after manual review

Browse Source
This commit is contained in:
softworkz
2025-10-15 16:06:09 +02:00
parent 341ebe2bb1
commit 88766adaf6
16 changed files with 516 additions and 711 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/Core/Advanced-Migration-Topics.md
View File

@@ -6,46 +6,47 @@ This guide covers advanced scenarios and edge cases that may require additional
### Port Configuration Changes
**Previous Approach:**
**Previous Approach:**
Specifying the WebPort in `electron.manifest.json` is no longer supported because the ASP.NET-first launch mode makes this timing-dependent.
**New Approach:**
**New Approach:**
Configure custom ASP.NET ports through MSBuild metadata:
```xml
<ItemGroup>
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
<AssemblyMetadata Include="AspNetHttpsPort" Value="4001" />
</ItemGroup>
```
**Usage in Code:**
```csharp
// Access configured ports at runtime
var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5000");
```
## Custom ElectronHostHook Configuration
> [!NOTE]
> These changes are only required in case you are using a custom ElectronHostHook implementation!
> If you have an ElectronHostHook folder in your project but you did not customize that code and aren't using its demo features (Excel and ZIP), you can also just remove that folder from your project.
### TypeScript and Node.js Updates
**Update package.json:**
This shows the delevant changes only: All shown versions are the new required minimum versions.
```json
{
"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"
}
}
```
**Update Project File:**
**Update Project File:**
The below modifications will allow you to use the latest TypeScript compiler in your ASP.Net project.
```xml
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
@@ -78,33 +79,9 @@ var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5
When using ElectronNET.Core in multi-project solutions:
1. **Install ElectronNET.Core.Api** in class library projects
2. **Install ElectronNET.Core** only in the startup project
2. **Install ElectronNET.Core and ElectronNET.Core.AspNet** only in the startup project
3. **Share configuration** through project references or shared files
### Custom Build Processes
For advanced build customization:
```xml
<PropertyGroup>
<ElectronNETCoreOutputPath>custom\output\path</ElectronNETCoreOutputPath>
<ElectronNETCoreNodeModulesPath>custom\node_modules</ElectronNETCoreNodeModulesPath>
</PropertyGroup>
```
### Environment-Specific Configuration
Handle different environments with conditional configuration:
```xml
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
<ElectronNETCoreEnvironment>Development</ElectronNETCoreEnvironment>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
<ElectronNETCoreEnvironment>Production</ElectronNETCoreEnvironment>
</PropertyGroup>
```
## Next Steps

120
docs/Core/Migration-Guide.md
View File

@@ -25,15 +25,15 @@ PM> Install-Package ElectronNET.Core
PM> Install-Package ElectronNET.Core.AspNet # For ASP.NET projects
```
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`. See [Package Description](../Releases/Package-Description.md) for details about the package structure.
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`. See [Package Description](../RelInfo/Package-Description.md) for details about the package structure.
### Step 2: Configure Project Settings
**Auto-generated Configuration:**
**Auto-generated Configuration:**
ElectronNET.Core automatically creates `electron-builder.json` during the first build or NuGet restore. No manual configuration is needed for basic setups.
**Migrate Existing Configuration:**
**Migrate Existing Configuration:**
If you have an existing `electron.manifest.json` file:
1. **Open the generated `electron-builder.json`** file in your project
@@ -47,14 +47,18 @@ You can also manually edit `electron-builder.json`:
```json
{
"productName": "My Electron App",
"appId": "com.mycompany.myapp",
"directories": {
"output": "release"
"linux": {
"target": [
"tar.xz"
]
},
"win": {
"target": "nsis",
"icon": "assets/app.ico"
"target": [
{
"target": "portable",
"arch": "x64"
}
]
}
}
```
@@ -71,12 +75,10 @@ After completing the migration steps:
## 🚨 Common Migration Issues
### Build Errors
- **Missing RuntimeIdentifier**: Ensure `<RuntimeIdentifier>win-x64</RuntimeIdentifier>` is set
- **Node.js version**: Verify Node.js 22.x is installed and in PATH
- **Package conflicts**: Clean NuGet cache if needed
### Runtime Errors
- **Port conflicts**: Update URLs in startup code to match your configuration
- **Missing electron-builder.json**: Trigger rebuild or manual NuGet restore
- **Process termination**: Use .NET-first startup mode for better cleanup
@@ -84,15 +86,15 @@ After completing the migration steps:
- **[What's New?](What's-New.md)** - Complete overview of ElectronNET.Core features
- **[Advanced Migration Topics](Advanced-Migration-Topics.md)** - Handle complex scenarios
- **[Getting Started](GettingStarted/ASP.Net.md)** - Learn about new development workflows
- **[Getting Started](../GettingStarted/ASP.Net.md)** - Learn about new development workflows
## 💡 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
✅ **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
@@ -104,76 +106,58 @@ After completing the migration steps:
using ElectronNET.API;
using ElectronNET.API.Entities;
var builder = WebApplication.CreateBuilder(args);
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
// Enable Electron.NET with callback
builder.WebHost.UseElectron(args, async () =>
{
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
new BrowserWindowOptions { Show = false });
builder.UseElectron(args, ElectronAppReady);
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
browserWindow.OnReadyToShow += () => browserWindow.Show();
});
var app = builder.Build();
app.Run();
}
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)
```csharp
```csharp
using ElectronNET.API;
using ElectronNET.API.Entities;
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static void Main(string[] args)
{
WebHost.CreateDefaultBuilder(args)
.UseElectron(args, ElectronAppReady)
.UseStartup<Startup>()
.Build()
.Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseElectron(args, ElectronAppReady)
.UseStartup<Startup>();
public static async Task ElectronAppReady()
{
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
new BrowserWindowOptions { Show = false });
// Electron callback
async Task ElectronAppReady()
{
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
new BrowserWindowOptions { Show = false });
await browserWindow.WebContents.LoadURLAsync("https://localhost:5001");
browserWindow.OnReadyToShow += () => browserWindow.Show();
}
browserWindow.OnReadyToShow += () => browserWindow.Show();
}
```
### Step 4: Update Development Tools
**Node.js Upgrade:**
ElectronNET.Core requires Node.js 22.x. Update your installation:
**Windows:**
1. Download from [nodejs.org](https://nodejs.org)
2. Run the installer
3. Verify: `node --version` should show v22.x.x
**Linux:**
```bash
# Using Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
# Or using package manager
sudo apt update
sudo apt install nodejs=22.*
```
See [System Requirements](../GettingStarted/System-Requirements.md).
### 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
@@ -181,4 +165,6 @@ The old 'watch' feature is no longer supported. Instead, use the new ASP.NET-fir
- **Benefits**: Faster development cycle, better debugging experience
**Update Launch Settings:**
Replace old watch configurations with new debugging profiles. See [Debugging](GettingStarted/Debugging.md) for detailed setup instructions.
Replace old watch configurations with new debugging profiles. See [Debugging](../GettingStarted/Debugging.md) for detailed setup instructions.

16
docs/Core/What's-New.md
View File

@@ -20,13 +20,14 @@ The new package architecture reflects a clearer separation of concerns:
- **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.
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.
More about the avaílable nuget packages: [Package Description](../RelInfo/Package-Description.md).
## Beyond ASP.NET: Console Application Support
### A Fundamental Shift in Accessibility
### A 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.
A major new opportunity in ElectronNET.Core is the removal of the ASP.NET requirement. Developers can now build Electron solutions using simple DotNet console applications, expanding the use cases and removing a major barrier to adoption for a number of use cases.
### Flexible Content Sources
@@ -43,7 +44,7 @@ This capability transforms ElectronNET from a web-focused framework into a versa
### 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.
The debugging experience has been completely transformed. The new DotNet-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 .NET development patterns.
### Cross-Platform Development Without Compromises
@@ -71,7 +72,8 @@ The underlying process architecture has been fundamentally redesigned. Instead o
- 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.
This architecture supports eight different launch scenarios, covering every combination of packaged/unpackaged deployment, console/ASP.NET hosting, and dotnet-first/electron-first initialization. The Electron-first launch method is still available or course.
For more details, see: [Startup Methods](../GettingStarted/Startup-Methods.md).
### Unpackaged Development Mode
@@ -103,7 +105,9 @@ 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
4. Adopt new debugging workflows at your own pace
Further reading: [Migration Guide](Migration-Guide.md).
## Future Horizons