Skip to content

Commit b9eb0b5

Browse files
softworkzsoftworkz
committed
AI-written docs
1 parent ec40d03 commit b9eb0b5

8 files changed

Lines changed: 1314 additions & 194 deletions

File tree

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

Lines changed: 36 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,47 +17,48 @@ if the asp web port needs to be specified manually, this can be by setting it vi
1717
</ItemGroup>
1818

1919

20-
// 2. ElectronHostHook
20+
## Custom ElectronHostHook Configuration
2121

22+
### TypeScript and Node.js Updates
2223

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-
24+
**Update package.json:**
25+
```json
26+
{
2827
"devDependencies": {
2928
"eslint": "^9.37.0",
30-
"@types/node": "^22.18",
31-
"typescript": "^5.9.3"
29+
"@types/node": "^22.18",
30+
"typescript": "^5.9.3"
3231
},
33-
"dependencies": {
32+
"dependencies": {
3433
"archiver-utils": "^2.1.0",
3534
"socket.io": "^4.8.1",
3635
"exceljs": "^1.10.0"
37-
}
36+
}
3837
}
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-
38+
```
39+
40+
**Update Project File:**
41+
```xml
42+
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
43+
44+
<PropertyGroup>
45+
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
46+
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
47+
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
48+
</PropertyGroup>
49+
50+
<ItemGroup>
51+
<Compile Remove="publish\**" />
52+
<Content Remove="publish\**" />
53+
<EmbeddedResource Remove="publish\**" />
54+
<None Remove="publish\**" />
55+
<TypeScriptCompile Remove="**\node_modules\**" />
56+
</ItemGroup>
57+
```
58+
59+
### Integration Benefits
60+
61+
- **Modern TypeScript** - Latest language features and better type checking
62+
- **Updated Node.js Types** - Compatibility with Node.js 22.x APIs
63+
- **ESLint Integration** - Better code quality and consistency
64+
- **MSBuild Compilation** - Integrated with Visual Studio build process

‎docs/Core/Migration-Guide.md‎

Lines changed: 155 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,182 @@
11
# Migration Guide
22

3-
// Explain migration steps:
3+
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.
44

5-
Uninstall existing package ElectronNET.API
5+
## 📋 Prerequisites
66

7-
// Install new packages:
7+
Before starting the migration:
88

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

10-
```ps1
11-
PM> Install-Package ElectronNET.Core
13+
## 🚀 Migration Steps
14+
15+
### Step 1: Update NuGet Packages
16+
17+
**Uninstall old packages:**
18+
```powershell
19+
PM> Uninstall-Package ElectronNET.API
20+
```
1221

13-
PM> Install-Package ElectronNET.Core.AspNet
22+
**Install new packages:**
23+
```powershell
24+
PM> Install-Package ElectronNET.Core
25+
PM> Install-Package ElectronNET.Core.AspNet # For ASP.NET projects
1426
```
1527

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
28+
> **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.
29+
30+
31+
### Step 2: Configure Project Settings
32+
33+
**Auto-generated Configuration:**
34+
ElectronNET.Core automatically creates `electron-builder.json` during the first build or NuGet restore. No manual configuration is needed for basic setups.
35+
36+
**Migrate Existing Configuration:**
37+
If you have an existing `electron.manifest.json` file:
38+
39+
1. **Open the generated `electron-builder.json`** file in your project
40+
2. **Locate the 'build' section** in your old `electron.manifest.json`
41+
3. **Copy the contents** of the build section (not the "build" key itself) into the new `electron-builder.json`
42+
4. **Use Visual Studio Project Designer** to configure Electron settings through the UI
43+
5. **Delete the old `electron.manifest.json`** file
44+
45+
**Alternative: Manual Configuration**
46+
You can also manually edit `electron-builder.json`:
47+
48+
```json
49+
{
50+
"productName": "My Electron App",
51+
"appId": "com.mycompany.myapp",
52+
"directories": {
53+
"output": "release"
54+
},
55+
"win": {
56+
"target": "nsis",
57+
"icon": "assets/app.ico"
58+
}
59+
}
60+
## 🎯 Testing Migration
61+
62+
After completing the migration steps:
63+
64+
1. **Build your project** to ensure no compilation errors
65+
2. **Test debugging** using the new ASP.NET-first approach
66+
3. **Verify packaging** works with the new configuration
67+
4. **Check cross-platform builds** if targeting multiple platforms
68+
69+
## 🚨 Common Migration Issues
70+
71+
### Build Errors
72+
- **Missing RuntimeIdentifier**: Ensure `<RuntimeIdentifier>win-x64</RuntimeIdentifier>` is set
73+
- **Node.js version**: Verify Node.js 22.x is installed and in PATH
74+
- **Package conflicts**: Clean NuGet cache if needed
1875

76+
### Runtime Errors
77+
- **Port conflicts**: Update URLs in startup code to match your configuration
78+
- **Missing electron-builder.json**: Trigger rebuild or manual NuGet restore
79+
- **Process termination**: Use .NET-first startup mode for better cleanup
1980

20-
// Edit Properties\electron-builder.json
21-
// it's auto-created: In VS after nuget restore, otherwise on first build - even when that fails
81+
## 🚀 Next Steps
2282

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-
//
83+
- **[What's New?](What's-New.md)** - Complete overview of ElectronNET.Core features
84+
- **[Advanced Migration Topics](Advanced-Migration-Topics.md)** - Handle complex scenarios
85+
- **[Getting Started](GettingStarted/ASP.Net.md)** - Learn about new development workflows
2986

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)
87+
## 💡 Migration Benefits
3588

36-
### Program.cs
89+
✅ **Simplified Configuration** - No more CLI tools or JSON files
90+
✅ **Better Debugging** - Native Visual Studio experience with Hot Reload
91+
✅ **Modern Architecture** - .NET-first process lifecycle
92+
✅ **Cross-Platform Ready** - Build Linux apps from Windows
93+
✅ **Future-Proof** - Flexible Electron version selection
3794

38-
```csharp
95+
### Step 3: Update Startup Code
96+
97+
**Update UseElectron() calls** to include the new callback parameter. This callback executes at the right moment to initialize your Electron UI.
98+
99+
#### Modern ASP.NET Core (WebApplication)
100+
101+
```csharp
39102
using ElectronNET.API;
40103
using ElectronNET.API.Entities;
41104

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-
}
105+
var builder = WebApplication.CreateBuilder(args);
106+
107+
// Enable Electron.NET with callback
108+
builder.WebHost.UseElectron(args, async () =>
109+
{
110+
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
111+
new BrowserWindowOptions { Show = false });
112+
113+
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
114+
browserWindow.OnReadyToShow += () => browserWindow.Show();
115+
});
116+
117+
var app = builder.Build();
118+
app.Run();
58119
```
59120

121+
#### Traditional ASP.NET Core (IWebHostBuilder)
60122

61-
// Also show an example for the other case with IWebHostBuilder and Startup class
123+
```csharp
124+
using ElectronNET.API;
125+
using ElectronNET.API.Entities;
62126

127+
public static void Main(string[] args)
128+
{
129+
CreateWebHostBuilder(args).Build().Run();
130+
}
131+
132+
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
133+
WebHost.CreateDefaultBuilder(args)
134+
.UseElectron(args, ElectronAppReady)
135+
.UseStartup<Startup>();
136+
137+
// Electron callback
138+
async Task ElectronAppReady()
139+
{
140+
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
141+
new BrowserWindowOptions { Show = false });
142+
143+
await browserWindow.WebContents.LoadURLAsync("https://localhost:5001");
144+
browserWindow.OnReadyToShow += () => browserWindow.Show();
145+
}
146+
```
147+
148+
149+
### Step 4: Update Development Tools
150+
151+
**Node.js Upgrade:**
152+
ElectronNET.Core requires Node.js 22.x. Update your installation:
63153

154+
**Windows:**
155+
1. Download from [nodejs.org](https://nodejs.org)
156+
2. Run the installer
157+
3. Verify: `node --version` should show v22.x.x
158+
159+
**Linux:**
160+
```bash
161+
# Using Node Version Manager (recommended)
162+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
163+
source ~/.bashrc
164+
nvm install 22
165+
nvm use 22
166+
167+
# Or using package manager
168+
sudo apt update
169+
sudo apt install nodejs=22.*
170+
```
64171

65-
// Next, explain that the 'watch' feature is no longer supported, now that proper debugging with hot reload is possible.
172+
### Step 5: Update Debugging Setup
66173

174+
**Watch Feature Removal:**
175+
The old 'watch' feature is no longer supported. Instead, use the new ASP.NET-first debugging with Hot Reload:
67176

68-
// Nodejs needs to be updated to 22.x
69-
// Important. Explain how to (for win and linux)
177+
- **Old approach**: Manual process attachment and slow refresh
178+
- **New approach**: Native Visual Studio debugging with Hot Reload
179+
- **Benefits**: Faster development cycle, better debugging experience
70180

181+
**Update Launch Settings:**
182+
Replace old watch configurations with new debugging profiles. See [Debugging](GettingStarted/Debugging.md) for detailed setup instructions.

0 commit comments

Comments
 (0)