Skip to content

Commit 0c5cc3b

Browse files
softworkzsoftworkz
committed
AI-written docs
1 parent bb5779a commit 0c5cc3b

File tree

9 files changed

+1467
-194
lines changed

9 files changed

+1467
-194
lines changed

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

Lines changed: 86 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,113 @@
11
# Advanced Migration Topics
22

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-
//
3+
This guide covers advanced scenarios and edge cases that may require additional configuration when migrating to ElectronNET.Core.
124

13-
if the asp web port needs to be specified manually, this can be by setting it via MSBuild like this:
5+
## Custom ASP.NET Port Configuration
146

15-
<ItemGroup>
16-
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
17-
</ItemGroup>
7+
### Port Configuration Changes
188

9+
**Previous Approach:**
10+
Specifying the WebPort in `electron.manifest.json` is no longer supported because the ASP.NET-first launch mode makes this timing-dependent.
1911

20-
// 2. ElectronHostHook
12+
**New Approach:**
13+
Configure custom ASP.NET ports through MSBuild metadata:
2114

15+
```xml
16+
<ItemGroup>
17+
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
18+
<AssemblyMetadata Include="AspNetHttpsPort" Value="4001" />
19+
</ItemGroup>
20+
```
2221

23-
Users who have a custom ElectronHostHook in their project, need to do the following:
22+
**Usage in Code:**
23+
```csharp
24+
// Access configured ports at runtime
25+
var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5000");
26+
```
2427

28+
## Custom ElectronHostHook Configuration
2529

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
30+
### TypeScript and Node.js Updates
2731

32+
**Update package.json:**
33+
```json
34+
{
2835
"devDependencies": {
2936
"eslint": "^9.37.0",
30-
"@types/node": "^22.18",
31-
"typescript": "^5.9.3"
37+
"@types/node": "^22.18",
38+
"typescript": "^5.9.3"
3239
},
33-
"dependencies": {
40+
"dependencies": {
3441
"archiver-utils": "^2.1.0",
3542
"socket.io": "^4.8.1",
3643
"exceljs": "^1.10.0"
37-
}
44+
}
3845
}
46+
```
3947

40-
Next step is to edit the project file and add a reference like this
48+
**Update Project File:**
49+
```xml
50+
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
4151

42-
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
52+
<PropertyGroup>
53+
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
54+
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
55+
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
56+
</PropertyGroup>
4357

44-
then the following propertygroup:
58+
<ItemGroup>
59+
<Compile Remove="publish\**" />
60+
<Content Remove="publish\**" />
61+
<EmbeddedResource Remove="publish\**" />
62+
<None Remove="publish\**" />
63+
<TypeScriptCompile Remove="**\node_modules\**" />
64+
</ItemGroup>
65+
```
4566

46-
<PropertyGroup>
47-
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
48-
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
49-
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
50-
</PropertyGroup>
67+
### Integration Benefits
5168

69+
- **Modern TypeScript** - Latest language features and better type checking
70+
- **Updated Node.js Types** - Compatibility with Node.js 22.x APIs
71+
- **ESLint Integration** - Better code quality and consistency
72+
- **MSBuild Compilation** - Integrated with Visual Studio build process
5273

53-
and this itemgroup:
74+
## Troubleshooting Advanced Scenarios
5475

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>
76+
### Multi-Project Solutions
6277

78+
When using ElectronNET.Core in multi-project solutions:
6379

80+
1. **Install ElectronNET.Core.Api** in class library projects
81+
2. **Install ElectronNET.Core** only in the startup project
82+
3. **Share configuration** through project references or shared files
83+
84+
### Custom Build Processes
85+
86+
For advanced build customization:
87+
88+
```xml
89+
<PropertyGroup>
90+
<ElectronNETCoreOutputPath>custom\output\path</ElectronNETCoreOutputPath>
91+
<ElectronNETCoreNodeModulesPath>custom\node_modules</ElectronNETCoreNodeModulesPath>
92+
</PropertyGroup>
93+
```
94+
95+
### Environment-Specific Configuration
96+
97+
Handle different environments with conditional configuration:
98+
99+
```xml
100+
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
101+
<ElectronNETCoreEnvironment>Development</ElectronNETCoreEnvironment>
102+
</PropertyGroup>
103+
104+
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
105+
<ElectronNETCoreEnvironment>Production</ElectronNETCoreEnvironment>
106+
</PropertyGroup>
107+
```
108+
109+
## Next Steps
110+
111+
- **[Migration Guide](Migration-Guide.md)** - Complete migration process
112+
- **[What's New?](What's-New.md)** - Overview of all ElectronNET.Core features
113+
- **[Getting Started](../GettingStarted/ASP.Net.md)** - Development workflows

‎docs/Core/Migration-Guide.md‎

Lines changed: 156 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,184 @@
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
13+
## 🚀 Migration Steps
14+
15+
### Step 1: Update NuGet Packages
16+
17+
**Uninstall old packages:**
18+
```powershell
19+
PM> Uninstall-Package ElectronNET.API
20+
```
21+
22+
**Install new packages:**
23+
```powershell
1124
PM> Install-Package ElectronNET.Core
25+
PM> Install-Package ElectronNET.Core.AspNet # For ASP.NET projects
26+
```
27+
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
1232

13-
PM> Install-Package ElectronNET.Core.AspNet
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+
}
1460
```
1561

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
62+
## 🎯 Testing Migration
63+
64+
After completing the migration steps:
65+
66+
1. **Build your project** to ensure no compilation errors
67+
2. **Test debugging** using the new ASP.NET-first approach
68+
3. **Verify packaging** works with the new configuration
69+
4. **Check cross-platform builds** if targeting multiple platforms
70+
71+
## 🚨 Common Migration Issues
72+
73+
### Build Errors
74+
- **Missing RuntimeIdentifier**: Ensure `<RuntimeIdentifier>win-x64</RuntimeIdentifier>` is set
75+
- **Node.js version**: Verify Node.js 22.x is installed and in PATH
76+
- **Package conflicts**: Clean NuGet cache if needed
1877

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

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

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

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)
89+
## 💡 Migration Benefits
3590

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

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

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

123+
#### Traditional ASP.NET Core (IWebHostBuilder)
60124

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

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

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

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

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

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

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

0 commit comments

Comments
 (0)