mirror of
https://github.com/ElectronNET/Electron.NET.git
synced 2026-09-21 14:35:16 +00:00
Update docs after manual review
This commit is contained in:
softworkz
79
docs/Using/Configuration.md
Normal file
79
docs/Using/Configuration.md
Normal file
@@ -0,0 +1,79 @@
|
||||
|
||||
# Project Configuration
|
||||
|
||||
|
||||
## 🔧 Visual Studio App Designer
|
||||
|
||||
Electron.NET provides close integration via the Visual Studio Project System and MSBuild. After adding the ElectronNET.Core package, you will see this in the project configuration page after double-click on the 'Properties' folder or right-click on the project and choosing 'Properties':
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Project File Settings
|
||||
|
||||
The same settings can be configured manually by editing the MSBuild properties in your `.csproj` file.
|
||||
These are the current default values when you don't make any changes:
|
||||
|
||||
```xml
|
||||
<PropertyGroup Label="ElectronNetCommon">
|
||||
<ElectronVersion>30.4.0</ElectronVersion>
|
||||
<ElectronBuilderVersion>26.0</ElectronBuilderVersion>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<ElectronSingleInstance>true</ElectronSingleInstance>
|
||||
<ElectronSplashScreen></ElectronSplashScreen>
|
||||
<ElectronIcon></ElectronIcon>
|
||||
<PackageId>$(MSBuildProjectName.Replace(".", "-").ToLower())</PackageId>
|
||||
<ElectronBuilderJson>electron-builder.json</ElectronBuilderJson>
|
||||
<Title>$(MSBuildProjectName)</Title>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Relation to package.json
|
||||
|
||||
ElectronNET.Core does not work with an `electron-manifest.json` file anymore.
|
||||
Since electron builder still expects a `package.json` file to exist, ElectronNET.Core is creating this under the hood automatically during build. For reference, here's the package.json template file that is being used, so you can see how the MSBuild properties are being mapped to `package.json` data:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "$(PackageId)",
|
||||
"productName": "$(ElectronTitle)",
|
||||
"build": {
|
||||
"appId": "$(PackageId)",
|
||||
"linux": {
|
||||
"desktop": {
|
||||
"entry": { "Name": "$(Title)" }
|
||||
},
|
||||
"executableName": "$(PackageId)"
|
||||
},
|
||||
"deb": {
|
||||
"desktop": {
|
||||
"entry": { "Name": "$(Title)" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "$(Description)",
|
||||
"version": "$(Version)",
|
||||
"main": "main.js",
|
||||
"author": {
|
||||
"name": "$(Company)"
|
||||
},
|
||||
"license": "$(License)",
|
||||
"executable": "$(TargetName)",
|
||||
"singleInstance": "$(ElectronSingleInstance)",
|
||||
"homepage": "$(ProjectUrl)",
|
||||
"splashscreen": {
|
||||
"imageFile": "$(ElectronSplashScreen)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Startup Methods](Startup-Methods.md)** - Understanding launch scenarios
|
||||
- **[Debugging](../Using/Debugging.md)** - Learn about ASP.NET debugging features
|
||||
- **[Package Building](Package-Building.md)** - Create distributable packages
|
||||
|
||||
236
docs/Using/Debugging.md
Normal file
236
docs/Using/Debugging.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Debugging
|
||||
|
||||
ElectronNET.Core transforms the debugging experience by providing native Visual Studio integration with multiple debugging modes. No more complex setup or manual process attachment—debugging now works as expected for .NET developers.
|
||||
|
||||
## 🎯 Debugging Modes
|
||||
|
||||
ElectronNET.Core supports three main debugging approaches, all configured through Visual Studio's launch profiles:
|
||||
|
||||
### 1. ASP.NET-First Debugging (Recommended)
|
||||
|
||||
Debug your .NET code directly with full Hot Reload support:
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"ASP.Net (unpackaged)": {
|
||||
"commandName": "Project",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
},
|
||||
"applicationUrl": "http://localhost:8001/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Full C# debugging with breakpoints
|
||||
- ✅ Hot Reload for ASP.NET code
|
||||
- ✅ Edit-and-continue functionality
|
||||
- ✅ Native Visual Studio debugging experience
|
||||
|
||||
### 2. Electron-First Debugging
|
||||
|
||||
Debug the Electron process when you need to inspect native Electron APIs:
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"Electron (unpackaged)": {
|
||||
"commandName": "Executable",
|
||||
"executablePath": "node",
|
||||
"commandLineArgs": "node_modules/electron/cli.js main.js -unpackedelectron",
|
||||
"workingDirectory": "$(TargetDir).electron",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Debug Electron main process
|
||||
- ✅ Inspect native Electron APIs
|
||||
- ✅ Node.js debugging capabilities
|
||||
|
||||
### 3. Cross-Platform WSL Debugging
|
||||
|
||||
Debug Linux builds directly from Windows Visual Studio:
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"WSL": {
|
||||
"commandName": "WSL2",
|
||||
"launchUrl": "http://localhost:8001/",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development",
|
||||
"ASPNETCORE_URLS": "http://localhost:8001/"
|
||||
},
|
||||
"distributionName": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Debug Linux applications from Windows
|
||||
- ✅ Test Linux-specific behavior
|
||||
- ✅ Validate cross-platform compatibility
|
||||
|
||||
## 🔧 Setup Instructions
|
||||
|
||||
### 1. Configure Launch Settings
|
||||
|
||||
Add the debugging profiles to `Properties/launchSettings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"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": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Switch Runtime Identifiers
|
||||
|
||||
When switching between Windows and WSL debugging:
|
||||
|
||||
1. **Right-click your project** in Solution Explorer
|
||||
2. **Select "Edit Project File"**
|
||||
3. **Update the RuntimeIdentifier**:
|
||||
|
||||
```xml
|
||||
<!-- For Windows debugging -->
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
|
||||
<!-- For WSL/Linux debugging -->
|
||||
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
|
||||
```
|
||||
|
||||
### 3. Enable WSL Debugging
|
||||
|
||||
For WSL debugging, ensure:
|
||||
|
||||
- **WSL2 is installed** and configured
|
||||
- **Linux distribution** is set in the launch profile
|
||||
- **Project targets Linux RID** for WSL debugging
|
||||
|
||||
## 🚀 Debugging Workflow
|
||||
|
||||
### ASP.NET-First Debugging (Default)
|
||||
|
||||
1. **Select "ASP.Net (unpackaged)"** profile in Visual Studio
|
||||
2. **Press F5** to start debugging
|
||||
3. **Set breakpoints** in your C# code
|
||||
4. **Use Hot Reload** to edit ASP.NET code during runtime
|
||||
5. **Stop debugging** when finished
|
||||
|
||||
### Electron Process Debugging
|
||||
|
||||
1. **Select "Electron (unpackaged)"** profile
|
||||
2. **Press F5** to start debugging
|
||||
3. **Attach to Electron process** if needed
|
||||
4. **Debug Node.js and Electron APIs**
|
||||
|
||||
### Cross-Platform Debugging
|
||||
|
||||
1. **Set RuntimeIdentifier** to `linux-x64`
|
||||
2. **Select "WSL"** profile
|
||||
3. **Press F5** to debug in WSL
|
||||
4. **Test Linux-specific behavior**
|
||||
|
||||
## 🔍 Debugging Tips
|
||||
|
||||
### Hot Reload
|
||||
|
||||
- **Works with ASP.NET-first debugging**
|
||||
- **Edit Razor views, controllers, and pages**
|
||||
- **See changes instantly** without restart
|
||||
- **Preserves application state**
|
||||
|
||||
### Breakpoint Debugging
|
||||
|
||||
```csharp
|
||||
// Set breakpoints here
|
||||
public async Task<IActionResult> Index()
|
||||
{
|
||||
var data = await GetData(); // ← Breakpoint
|
||||
return View(data);
|
||||
}
|
||||
```
|
||||
|
||||
### Process Management
|
||||
|
||||
- **ASP.NET-first mode** automatically manages Electron process lifecycle
|
||||
- **Proper cleanup** on debugging session end
|
||||
- **No manual process killing** required
|
||||
|
||||
## 🛠 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Electron process not found"**
|
||||
- Ensure Node.js 22.x is installed
|
||||
- Check that packages are restored (`dotnet restore`)
|
||||
- Verify RuntimeIdentifier matches your target platform
|
||||
|
||||
**"WSL debugging fails"**
|
||||
- Install and configure WSL2
|
||||
- Ensure Linux distribution is properly set up
|
||||
- Check that project targets correct RID
|
||||
|
||||
**"Hot Reload not working"**
|
||||
- Use ASP.NET-first debugging profile
|
||||
- Ensure ASPNETCORE_ENVIRONMENT=Development
|
||||
- Check for compilation errors
|
||||
|
||||
## 🎨 Visual Debugging
|
||||
|
||||
*Placeholder for image showing Visual Studio debugging interface with Electron.NET*
|
||||
|
||||
The debugging interface provides familiar Visual Studio tools:
|
||||
- **Locals and Watch windows** for variable inspection
|
||||
- **Call Stack** for method call tracing
|
||||
- **Immediate Window** for runtime evaluation
|
||||
- **Hot Reload** indicator for edit-and-continue
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Startup Methods](Startup-Methods.md)** - Understanding different launch scenarios
|
||||
- **[Package Building](Package-Building.md)** - Debug packaged applications
|
||||
- **[Migration Guide](../Core/Migration-Guide.md)** - Moving from old debugging workflows
|
||||
|
||||
## 💡 Benefits
|
||||
|
||||
✅ **Native Visual Studio Experience** - No complex setup or manual attachment
|
||||
✅ **Hot Reload Support** - Edit ASP.NET code during debugging
|
||||
✅ **Cross-Platform Debugging** - Debug Linux apps from Windows
|
||||
✅ **Multiple Debugging Modes** - Choose the right approach for your needs
|
||||
✅ **Process Lifecycle Management** - Automatic cleanup and proper termination
|
||||
146
docs/Using/Package-Building.md
Normal file
146
docs/Using/Package-Building.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Package Building
|
||||
|
||||
ElectronNET.Core integrates with Visual Studio's publishing system to create distributable Electron packages using electron-builder. The process leverages .NET's build system while automatically generating the necessary Electron configuration files.
|
||||
|
||||
## 🎯 Publishing Overview
|
||||
|
||||
The publishing process differs slightly between ASP.NET and console applications:
|
||||
|
||||
- **ASP.NET Apps** - Use folder publishing with SelfContained=true
|
||||
- **Console Apps** - Use folder publishing with SelfContained=false
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before publishing, ensure you have:
|
||||
|
||||
- **Node.js 22.x** installed
|
||||
- **RuntimeIdentifier** set correctly for your target platform
|
||||
- **Project configured** for Release builds
|
||||
|
||||
## 🚀 Publishing Process
|
||||
|
||||
### Step 1: Create Publish Profiles
|
||||
|
||||
Add publish profiles to `Properties/PublishProfiles/`:
|
||||
|
||||
#### ASP.NET Application Profile (Windows)
|
||||
|
||||
**win-x64.pubxml:**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
|
||||
<PublishProtocol>FileSystem</PublishProtocol>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<SelfContained>true</SelfContained>
|
||||
<PublishSingleFile>false</PublishSingleFile>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### ASP.NET Application Profile (Linux)
|
||||
|
||||
**linux-x64.pubxml:**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
|
||||
<PublishProtocol>FileSystem</PublishProtocol>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
|
||||
<SelfContained>true</SelfContained>
|
||||
<PublishSingleFile>false</PublishSingleFile>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Console Application Profile (Windows)
|
||||
|
||||
**win-x64.pubxml:**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
|
||||
<PublishProtocol>FileSystem</PublishProtocol>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<SelfContained>false</SelfContained>
|
||||
<PublishSingleFile>false</PublishSingleFile>
|
||||
<PublishReadyToRun>false</PublishReadyToRun>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Console Application Profile (Linux)
|
||||
|
||||
**linux-x64.pubxml:**
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
|
||||
<PublishProtocol>FileSystem</PublishProtocol>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
|
||||
<SelfContained>false</SelfContained>
|
||||
<PublishSingleFile>false</PublishSingleFile>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
### Step 2: Configure Electron Builder
|
||||
|
||||
ElectronNET.Core automatically adds a default `electron-builder.json` file under `Properties\electron-builder.json`.
|
||||
Please see here for details of the available configuration options: https://www.electron.build/.
|
||||
|
||||
|
||||
### Step 3: Publish from Visual Studio
|
||||
|
||||
1. **Right-click your project** in Solution Explorer
|
||||
2. **Select "Publish"**
|
||||
4. **Select your publish profile** (Windows/Linux)
|
||||
5. **Click "Publish"**
|
||||
|
||||
The publish process will:
|
||||
- Build your .NET application
|
||||
- Copy all files as needed
|
||||
- Install npm dependencies
|
||||
- Run electron-builder
|
||||
|
||||
> [!NOTE]
|
||||
> When running publish for a Linux configuration on Windows, Electron.NET will automatically use WSL for the platform-specific steps.
|
||||
|
||||
**After publishing**, build the final package, the final results will be in
|
||||
|
||||
`publish\Release\netx.0\xxx-xxx\`
|
||||
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Startup Methods](Startup-Methods.md)** - Understanding different launch modes for packaged apps
|
||||
- **[Debugging](Debugging.md)** - Debug packaged applications
|
||||
- **[Migration Guide](../Core/Migration-Guide.md)** - Update existing projects for new publishing
|
||||
|
||||
## 💡 Benefits
|
||||
|
||||
✅ **Native VS Integration** - Use familiar publish workflows
|
||||
✅ **Cross-Platform Building** - Build Linux packages from Windows
|
||||
✅ **Automatic Configuration** - No manual electron-builder setup
|
||||
✅ **Multiple Package Types** - NSIS, AppImage, DMG, etc.
|
||||
✅ **CI/CD Ready** - Easy integration with build pipelines
|
||||
246
docs/Using/Startup-Methods.md
Normal file
246
docs/Using/Startup-Methods.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# Startup Methods
|
||||
|
||||
ElectronNET.Core supports multiple startup methods to handle different development and deployment scenarios. The framework automatically detects the appropriate mode based on command-line flags and environment.
|
||||
|
||||
## 🎯 Startup Scenarios
|
||||
|
||||
The framework supports **8 different launch scenarios** covering every combination of:
|
||||
|
||||
- **Packaged vs Unpackaged** deployment
|
||||
- **Console vs ASP.NET** application types
|
||||
- **Dotnet-first vs Electron-first** initialization
|
||||
|
||||
## 🚀 Command-Line Flags
|
||||
|
||||
### Unpackaged Debugging Modes
|
||||
|
||||
#### **`-unpackedelectron`** - Electron-first debugging
|
||||
```bash
|
||||
# Launch Electron first, which then starts .NET
|
||||
node node_modules/electron/cli.js main.js -unpackedelectron
|
||||
```
|
||||
|
||||
#### **`-unpackeddotnet`** - .NET-first debugging
|
||||
```bash
|
||||
# Launch .NET first, which then starts Electron
|
||||
dotnet run -unpackeddotnet
|
||||
```
|
||||
|
||||
### Packaged Deployment Modes
|
||||
|
||||
#### **`-dotnetpacked`** - .NET-first packaged execution
|
||||
```bash
|
||||
# Run packaged app with .NET starting first
|
||||
MyApp.exe -dotnetpacked
|
||||
```
|
||||
|
||||
#### **No flags** - Electron-first packaged execution (default)
|
||||
```bash
|
||||
# Run packaged app with Electron starting first
|
||||
MyApp.exe
|
||||
```
|
||||
|
||||
## 📋 Startup Method Details
|
||||
|
||||
### 1. Unpackaged + Electron-First (Development)
|
||||
- **Use Case**: Debug Electron main process and Node.js code
|
||||
- **Command**: `-unpackedelectron` flag
|
||||
- **Process Flow**:
|
||||
1. Electron starts first
|
||||
2. Electron launches .NET process
|
||||
3. .NET connects back to Electron
|
||||
4. Application runs with Electron in control
|
||||
|
||||
### 2. Unpackaged + .NET-First (Development)
|
||||
- **Use Case**: Debug ASP.NET/C# code with Hot Reload
|
||||
- **Command**: `-unpackeddotnet` flag
|
||||
- **Process Flow**:
|
||||
1. .NET application starts first
|
||||
2. .NET launches Electron process
|
||||
3. Electron connects back to .NET
|
||||
4. Application runs with .NET in control
|
||||
|
||||
### 3. Packaged + .NET-First (Production)
|
||||
- **Use Case**: Deployed application with .NET controlling lifecycle
|
||||
- **Command**: `-dotnetpacked` flag
|
||||
- **Process Flow**:
|
||||
1. .NET executable starts first
|
||||
2. .NET launches Electron from packaged files
|
||||
3. Electron loads from app.asar or extracted files
|
||||
4. .NET maintains process control
|
||||
|
||||
### 4. Packaged + Electron-First (Production)
|
||||
- **Use Case**: Traditional Electron app behavior
|
||||
- **Command**: No special flags
|
||||
- **Process Flow**:
|
||||
1. Electron executable starts first
|
||||
2. Electron launches .NET from packaged files
|
||||
3. .NET runs from Electron's process context
|
||||
4. Electron maintains UI control
|
||||
|
||||
## 🔧 Configuration Examples
|
||||
|
||||
### ASP.NET Application Startup
|
||||
|
||||
```csharp
|
||||
// Program.cs
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
// Configure for different startup modes
|
||||
builder.WebHost.UseElectron(args, async () =>
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
await browserWindow.WebContents.LoadURLAsync("http://localhost:8001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
});
|
||||
|
||||
var app = builder.Build();
|
||||
app.Run();
|
||||
```
|
||||
|
||||
### Console Application Startup
|
||||
|
||||
```csharp
|
||||
// Program.cs
|
||||
public static async Task Main(string[] args)
|
||||
{
|
||||
var runtimeController = ElectronNetRuntime.RuntimeController;
|
||||
|
||||
await runtimeController.Start();
|
||||
await runtimeController.WaitReadyTask;
|
||||
|
||||
await InitializeApplication();
|
||||
|
||||
await runtimeController.WaitStoppedTask;
|
||||
}
|
||||
```
|
||||
|
||||
## 🎨 Visual Process Flow
|
||||
|
||||
|
||||
|
||||
|
||||
The image above illustrates how each combination of deployment type, application type, and initialization order affects the process lifecycle.
|
||||
|
||||
## 🚀 Development Workflows
|
||||
|
||||
### Debugging Workflow
|
||||
|
||||
**ASP.NET-First Debugging** (Recommended)
|
||||
```json
|
||||
// launchSettings.json
|
||||
{
|
||||
"ASP.Net (unpackaged)": {
|
||||
"commandName": "Project",
|
||||
"commandLineArgs": "-unpackeddotnet"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Electron-First Debugging**
|
||||
```json
|
||||
// launchSettings.json
|
||||
{
|
||||
"Electron (unpackaged)": {
|
||||
"commandName": "Executable",
|
||||
"executablePath": "node",
|
||||
"commandLineArgs": "node_modules/electron/cli.js main.js -unpackedelectron"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
**Dotnet-First Deployment**
|
||||
|
||||
```bash
|
||||
# Build and package
|
||||
dotnet publish -c Release -r win-x64
|
||||
cd publish\Release\net8.0\win-x64
|
||||
npm install
|
||||
npx electron-builder
|
||||
|
||||
# Run with dotnet-first
|
||||
MyApp.exe -dotnetpacked
|
||||
```
|
||||
|
||||
**Electron-First Deployment** (Default)
|
||||
|
||||
```bash
|
||||
# Run packaged application (no special flags needed)
|
||||
MyApp.exe
|
||||
```
|
||||
|
||||
## 🔍 Process Lifecycle Management
|
||||
|
||||
### Automatic Cleanup
|
||||
|
||||
ElectronNET.Core automatically manages process lifecycle:
|
||||
|
||||
- **Graceful shutdown** when main window is closed
|
||||
- **Proper cleanup** of child processes
|
||||
- **Error handling** for process failures
|
||||
- **Cross-platform compatibility** for process management
|
||||
|
||||
### Manual Control
|
||||
|
||||
Access runtime controller for advanced scenarios:
|
||||
|
||||
```csharp
|
||||
var runtime = ElectronNetRuntime.RuntimeController;
|
||||
|
||||
// Wait for Electron to be ready
|
||||
await runtime.WaitReadyTask;
|
||||
|
||||
// Stop Electron runtime
|
||||
await runtime.Stop();
|
||||
await runtime.WaitStoppedTask;
|
||||
```
|
||||
|
||||
## 🛠 Troubleshooting
|
||||
|
||||
### Common Startup Issues
|
||||
|
||||
**"Electron process not found"**
|
||||
- Ensure Node.js 22.x is installed
|
||||
- Check that .NET build succeeded
|
||||
- Verify RuntimeIdentifier is set correctly
|
||||
|
||||
**"Port conflicts"**
|
||||
- Use different ports for different startup modes
|
||||
- Check that no other instances are running
|
||||
- Verify firewall settings
|
||||
|
||||
**"Process won't terminate"**
|
||||
- Use dotnet-first mode for better cleanup
|
||||
- Check for unhandled exceptions
|
||||
- Verify all windows are properly closed
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Choose the Right Mode
|
||||
|
||||
- **Development**: Use .NET-first for C# debugging, Electron-first for Node.js debugging
|
||||
- **Production**: Use .NET-first for better process control, Electron-first for traditional behavior
|
||||
- **Cross-platform**: Use .NET-first for consistent behavior across platforms
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
```xml
|
||||
<!-- .csproj -->
|
||||
<PropertyGroup>
|
||||
<ElectronNETCoreEnvironment>Production</ElectronNETCoreEnvironment>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Debugging](Debugging.md)** - Debug different startup modes
|
||||
- **[Package Building](Package-Building.md)** - Package for different deployment scenarios
|
||||
- **[Migration Guide](../Core/Migration-Guide.md)** - Update existing apps for new startup methods
|
||||
|
||||
## 🎯 Summary
|
||||
|
||||
The flexible startup system ensures ElectronNET.Core works optimally in every scenario while providing the control and debugging experience .NET developers expect. Choose the appropriate mode based on your development workflow and deployment requirements.
|
||||
Reference in New Issue
Block a user