mirror of
https://github.com/ElectronNET/Electron.NET.git
synced 2026-02-04 05:34:51 +00:00
AI-written docs
This commit is contained in:
softworkz
@@ -1,63 +1,113 @@
|
||||
# Advanced Migration Topics
|
||||
|
||||
// 1. WebPort
|
||||
// specifying the WebPort in the manifest is no longer supported
|
||||
// from commit message:
|
||||
//- Removed the 'electronWebPort' handling
|
||||
// When ASP.Net is launched first, then the information which port it
|
||||
// should use would be coming too late; anyway, there's no need for
|
||||
// letting the port number round-trip all the way through the manifest
|
||||
// file, loaded by main.js and then sent to dotnet.
|
||||
//
|
||||
This guide covers advanced scenarios and edge cases that may require additional configuration when migrating to ElectronNET.Core.
|
||||
|
||||
if the asp web port needs to be specified manually, this can be by setting it via MSBuild like this:
|
||||
## Custom ASP.NET Port Configuration
|
||||
|
||||
<ItemGroup>
|
||||
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
|
||||
</ItemGroup>
|
||||
### Port Configuration Changes
|
||||
|
||||
**Previous Approach:**
|
||||
Specifying the WebPort in `electron.manifest.json` is no longer supported because the ASP.NET-first launch mode makes this timing-dependent.
|
||||
|
||||
// 2. ElectronHostHook
|
||||
**New Approach:**
|
||||
Configure custom ASP.NET ports through MSBuild metadata:
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
|
||||
<AssemblyMetadata Include="AspNetHttpsPort" Value="4001" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
Users who have a custom ElectronHostHook in their project, need to do the following:
|
||||
**Usage in Code:**
|
||||
```csharp
|
||||
// Access configured ports at runtime
|
||||
var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5000");
|
||||
```
|
||||
|
||||
## Custom ElectronHostHook Configuration
|
||||
|
||||
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
|
||||
### TypeScript and Node.js Updates
|
||||
|
||||
**Update package.json:**
|
||||
```json
|
||||
{
|
||||
"devDependencies": {
|
||||
"eslint": "^9.37.0",
|
||||
"@types/node": "^22.18",
|
||||
"typescript": "^5.9.3"
|
||||
"@types/node": "^22.18",
|
||||
"typescript": "^5.9.3"
|
||||
},
|
||||
"dependencies": {
|
||||
"dependencies": {
|
||||
"archiver-utils": "^2.1.0",
|
||||
"socket.io": "^4.8.1",
|
||||
"exceljs": "^1.10.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Next step is to edit the project file and add a reference like this
|
||||
**Update Project File:**
|
||||
```xml
|
||||
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
|
||||
|
||||
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
|
||||
<PropertyGroup>
|
||||
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
|
||||
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
|
||||
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
|
||||
</PropertyGroup>
|
||||
|
||||
then the following propertygroup:
|
||||
<ItemGroup>
|
||||
<Compile Remove="publish\**" />
|
||||
<Content Remove="publish\**" />
|
||||
<EmbeddedResource Remove="publish\**" />
|
||||
<None Remove="publish\**" />
|
||||
<TypeScriptCompile Remove="**\node_modules\**" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
<PropertyGroup>
|
||||
<TypeScriptModuleKind>commonjs</TypeScriptModuleKind>
|
||||
<TypeScriptUseNodeJS>true</TypeScriptUseNodeJS>
|
||||
<TypeScriptTSConfig>ElectronHostHook/tsconfig.json</TypeScriptTSConfig>
|
||||
</PropertyGroup>
|
||||
### Integration Benefits
|
||||
|
||||
- **Modern TypeScript** - Latest language features and better type checking
|
||||
- **Updated Node.js Types** - Compatibility with Node.js 22.x APIs
|
||||
- **ESLint Integration** - Better code quality and consistency
|
||||
- **MSBuild Compilation** - Integrated with Visual Studio build process
|
||||
|
||||
and this itemgroup:
|
||||
## Troubleshooting Advanced Scenarios
|
||||
|
||||
<ItemGroup>
|
||||
<Compile Remove="publish\**" />
|
||||
<Content Remove="publish\**" />
|
||||
<EmbeddedResource Remove="publish\**" />
|
||||
<None Remove="publish\**" />
|
||||
<TypeScriptCompile Remove="**\node_modules\**" />
|
||||
</ItemGroup>
|
||||
### Multi-Project Solutions
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
- **[Migration Guide](Migration-Guide.md)** - Complete migration process
|
||||
- **[What's New?](What's-New.md)** - Overview of all ElectronNET.Core features
|
||||
- **[Getting Started](../GettingStarted/ASP.Net.md)** - Development workflows
|
||||
|
||||
@@ -1,70 +1,184 @@
|
||||
# Migration Guide
|
||||
|
||||
// Explain migration steps:
|
||||
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.
|
||||
|
||||
Uninstall existing package ElectronNET.API
|
||||
## 📋 Prerequisites
|
||||
|
||||
// Install new packages:
|
||||
Before starting the migration:
|
||||
|
||||
- **Backup your project** - Ensure you have a working backup
|
||||
- **Update development tools** - Install Node.js 22.x and .NET 8.0+
|
||||
- **Review current setup** - Note your current Electron and ASP.NET versions
|
||||
|
||||
```ps1
|
||||
PM> Install-Package ElectronNET.Core
|
||||
## 🚀 Migration Steps
|
||||
|
||||
PM> Install-Package ElectronNET.Core.AspNet
|
||||
### Step 1: Update NuGet Packages
|
||||
|
||||
**Uninstall old packages:**
|
||||
```powershell
|
||||
PM> Uninstall-Package ElectronNET.API
|
||||
```
|
||||
|
||||
// add link to package type description: [text](../Releases/Package-Description.md)
|
||||
// the API package is a dependency of .Core, so it's auto-incldued
|
||||
**Install new packages:**
|
||||
```powershell
|
||||
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.
|
||||
|
||||
|
||||
// Edit Properties\electron-builder.json
|
||||
// it's auto-created: In VS after nuget restore, otherwise on first build - even when that fails
|
||||
### Step 2: Configure Project Settings
|
||||
|
||||
// Now look at the electron-manifest.json file
|
||||
// 1. Manually merge everything under the 'build' property into the
|
||||
// electron-builder file (omitting the build node, only its content is to be merged)
|
||||
// 2. Open the project designer in VS and enter the values from the manifest file into the fields
|
||||
// 3. Delete the manifest file
|
||||
//
|
||||
**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.
|
||||
|
||||
// Check ASP.Net core startup (program.cs or statup.cs, typically)
|
||||
// Find the UseElectron() extension method call
|
||||
// it will have an error. it needs a 3rd parameter now: the onAppReady callback.
|
||||
// set this to a callback function. this gets called just in the right moment for you
|
||||
// to start things going (like accessing ElectronNET classes)
|
||||
**Migrate Existing Configuration:**
|
||||
If you have an existing `electron.manifest.json` file:
|
||||
|
||||
### Program.cs
|
||||
1. **Open the generated `electron-builder.json`** file in your project
|
||||
2. **Locate the 'build' section** in your old `electron.manifest.json`
|
||||
3. **Copy the contents** of the build section (not the "build" key itself) into the new `electron-builder.json`
|
||||
4. **Use Visual Studio Project Designer** to configure Electron settings through the UI
|
||||
5. **Delete the old `electron.manifest.json`** file
|
||||
|
||||
```csharp
|
||||
**Alternative: Manual Configuration**
|
||||
You can also manually edit `electron-builder.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "My Electron App",
|
||||
"appId": "com.mycompany.myapp",
|
||||
"directories": {
|
||||
"output": "release"
|
||||
},
|
||||
"win": {
|
||||
"target": "nsis",
|
||||
"icon": "assets/app.ico"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Testing Migration
|
||||
|
||||
After completing the migration steps:
|
||||
|
||||
1. **Build your project** to ensure no compilation errors
|
||||
2. **Test debugging** using the new ASP.NET-first approach
|
||||
3. **Verify packaging** works with the new configuration
|
||||
4. **Check cross-platform builds** if targeting multiple platforms
|
||||
|
||||
## 🚨 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
|
||||
|
||||
## 🚀 Next 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
|
||||
|
||||
## 💡 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
|
||||
|
||||
### Step 3: Update Startup Code
|
||||
|
||||
**Update UseElectron() calls** to include the new callback parameter. This callback executes at the right moment to initialize your Electron UI.
|
||||
|
||||
#### Modern ASP.NET Core (WebApplication)
|
||||
|
||||
```csharp
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>()
|
||||
.Build()
|
||||
.Run();
|
||||
}
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
public static async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
// Enable Electron.NET with callback
|
||||
builder.WebHost.UseElectron(args, async () =>
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
});
|
||||
|
||||
var app = builder.Build();
|
||||
app.Run();
|
||||
```
|
||||
|
||||
#### Traditional ASP.NET Core (IWebHostBuilder)
|
||||
|
||||
```csharp
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
CreateWebHostBuilder(args).Build().Run();
|
||||
}
|
||||
|
||||
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>();
|
||||
|
||||
// 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();
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
// Also show an example for the other case with IWebHostBuilder and Startup class
|
||||
### 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
|
||||
|
||||
// Next, explain that the 'watch' feature is no longer supported, now that proper debugging with hot reload is possible.
|
||||
**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.*
|
||||
```
|
||||
|
||||
// Nodejs needs to be updated to 22.x
|
||||
// Important. Explain how to (for win and linux)
|
||||
### 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
|
||||
- **New approach**: Native Visual Studio debugging with Hot Reload
|
||||
- **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.
|
||||
|
||||
@@ -1,57 +1,190 @@
|
||||
|
||||
|
||||
## 🛠 Requirements to Run
|
||||
# ASP.NET Core Setup
|
||||
|
||||
Our API uses .NET 6/8, so our
|
||||
ASP.NET Core remains the recommended approach for complex web applications with ElectronNET.Core, providing all the benefits of the ASP.NET ecosystem along with enhanced Electron integration.
|
||||
|
||||
Also you should have installed:
|
||||
## 🛠 System Requirements
|
||||
|
||||
* .NET 6/8 or later
|
||||
* OS
|
||||
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).
|
||||
* NodeJS (at least [Version 22.x](https://nodejs.org))
|
||||
### Required Software
|
||||
- **.NET 8.0** or later
|
||||
- **Node.js 22.x** or later ([Download here](https://nodejs.org))
|
||||
- **Visual Studio 2022** (recommended) or other .NET IDE
|
||||
|
||||
### Supported Operating Systems
|
||||
- **Windows 10/11** (x64, ARM64)
|
||||
- **macOS 11+** (Intel, Apple Silicon)
|
||||
- **Linux** (most distributions with glibc 2.31+)
|
||||
|
||||
## 👩🏫 Usage with ASP.Net
|
||||
> **Note**: For Linux development on Windows, install [WSL2](https://docs.microsoft.com/windows/wsl/install) to build and debug Linux packages.
|
||||
|
||||
- Create a new ASP.Net Core project
|
||||
- Install the following two nuget packages:
|
||||
## 🚀 Quick Start
|
||||
|
||||
```ps1
|
||||
### 1. Create ASP.NET Core Project
|
||||
|
||||
Create a new ASP.NET Core Web App in Visual Studio:
|
||||
|
||||
```bash
|
||||
dotnet new webapp -n MyElectronWebApp
|
||||
cd MyElectronWebApp
|
||||
```
|
||||
|
||||
### 2. Install NuGet Packages
|
||||
|
||||
```powershell
|
||||
PM> Install-Package ElectronNET.Core
|
||||
|
||||
PM> Install-Package ElectronNET.Core.AspNet
|
||||
```
|
||||
|
||||
### Enable Electron.NET on Startup
|
||||
> **Note**: `ElectronNET.Core.AspNet` provides ASP.NET-specific runtime components and should be used alongside `ElectronNET.Core`.
|
||||
|
||||
To do so, use the `UseElectron` extension method on a `WebApplicationBuilder`, an `IWebHostBuilder` or any descendants.
|
||||
### 3. Configure Program.cs
|
||||
|
||||
> [!NOTE]
|
||||
> 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.
|
||||
Update your `Program.cs` to enable Electron.NET:
|
||||
|
||||
### Program.cs
|
||||
|
||||
```csharp
|
||||
```csharp
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>()
|
||||
.Build()
|
||||
.Run();
|
||||
}
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
public static async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
// Enable Electron.NET with callback for UI setup
|
||||
builder.WebHost.UseElectron(args, ElectronAppReady);
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
// Add services to the container
|
||||
builder.Services.AddControllersWithViews();
|
||||
|
||||
var app = builder.Build();
|
||||
|
||||
// Configure the HTTP request pipeline
|
||||
if (!app.Environment.IsDevelopment())
|
||||
{
|
||||
app.UseExceptionHandler("/Home/Error");
|
||||
app.UseHsts();
|
||||
}
|
||||
|
||||
app.UseHttpsRedirection();
|
||||
app.UseStaticFiles();
|
||||
app.UseRouting();
|
||||
app.UseAuthorization();
|
||||
|
||||
app.MapControllerRoute(
|
||||
name: "default",
|
||||
pattern: "{controller=Home}/{action=Index}/{id?}");
|
||||
|
||||
app.Run();
|
||||
|
||||
// Electron initialization callback
|
||||
async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Show = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
|
||||
// Load your ASP.NET application
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Alternative: IWebHostBuilder Setup
|
||||
|
||||
For projects using the traditional `Startup.cs` pattern:
|
||||
|
||||
```csharp
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
CreateWebHostBuilder(args).Build().Run();
|
||||
}
|
||||
|
||||
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>();
|
||||
|
||||
// Electron callback (same as above)
|
||||
async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:5001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Project File Settings
|
||||
|
||||
Configure Electron.NET through MSBuild properties in your `.csproj`:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<ElectronNETCoreDescription>My ASP.NET Electron App</ElectronNETCoreDescription>
|
||||
<ElectronNETCoreDisplayName>MyApp</ElectronNETCoreDisplayName>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### Window Configuration
|
||||
|
||||
Customize the main window appearance:
|
||||
|
||||
```csharp
|
||||
var options = new BrowserWindowOptions
|
||||
{
|
||||
Width = 1400,
|
||||
Height = 900,
|
||||
MinWidth = 800,
|
||||
MinHeight = 600,
|
||||
Frame = true,
|
||||
TitleBarStyle = TitleBarStyle.Default,
|
||||
Icon = "wwwroot/favicon.ico"
|
||||
};
|
||||
```
|
||||
|
||||
### Multiple Windows
|
||||
|
||||
Create additional windows for different parts of your application:
|
||||
|
||||
```csharp
|
||||
var settingsWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
{
|
||||
Width = 600,
|
||||
Height = 400,
|
||||
Parent = browserWindow,
|
||||
Modal = true
|
||||
},
|
||||
"https://localhost:7001/settings");
|
||||
```
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Debugging](Debugging.md)** - Learn about ASP.NET debugging features
|
||||
- **[Package Building](Package-Building.md)** - Create distributable packages
|
||||
- **[Startup Methods](Startup-Methods.md)** - Understanding launch scenarios
|
||||
|
||||
## 💡 Benefits of ASP.NET + Electron
|
||||
|
||||
✅ **Full Web Stack** - Use MVC, Razor Pages, Blazor, and all ASP.NET features
|
||||
✅ **Hot Reload** - Edit ASP.NET code and see changes instantly
|
||||
✅ **Rich Ecosystem** - Access to thousands of ASP.NET packages
|
||||
✅ **Modern Development** - Latest C# features and ASP.NET patterns
|
||||
✅ **Scalable Architecture** - Build complex, maintainable applications
|
||||
|
||||
@@ -1,13 +1,72 @@
|
||||
|
||||
|
||||
// Understand this code so you can explain how to set it up with console project
|
||||
# Console Application Setup
|
||||
|
||||
namespace ElectronNET.WebApp
|
||||
One of the most significant breakthroughs in ElectronNET.Core is the ability to build Electron applications using simple console applications instead of requiring ASP.NET Core. This removes a major barrier and enables many more use cases.
|
||||
|
||||
## 🎯 What You Can Build
|
||||
|
||||
Console applications with ElectronNET.Core support multiple content scenarios:
|
||||
|
||||
- **File System HTML/JS** - Serve static web content directly from the file system
|
||||
- **Remote Server Integration** - Connect to existing web servers or APIs
|
||||
- **Lightweight Architecture** - Avoid ASP.NET overhead when not needed
|
||||
- **Simplified Deployment** - Package and distribute with minimal dependencies
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
- **.NET 8.0** or later
|
||||
- **Node.js 22.x** or later
|
||||
- **Visual Studio 2022** (recommended) or Visual Studio Code
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Create Console Application
|
||||
|
||||
Create a new Console Application project in Visual Studio:
|
||||
|
||||
```bash
|
||||
dotnet new console -n MyElectronApp
|
||||
cd MyElectronApp
|
||||
```
|
||||
|
||||
### 2. Install NuGet Packages
|
||||
|
||||
```powershell
|
||||
PM> Install-Package ElectronNET.Core
|
||||
```
|
||||
|
||||
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`.
|
||||
|
||||
### 3. Configure Project File
|
||||
|
||||
Add the Electron.NET configuration to your `.csproj` file:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<OutputType>Exe</OutputType>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core" Version="1.0.0" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
### 4. Implement Basic Structure
|
||||
|
||||
Here's a complete console application example:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
using System.Threading.Tasks;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
namespace MyElectronApp
|
||||
{
|
||||
using System;
|
||||
using System.Threading.Tasks;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
public class Program
|
||||
{
|
||||
public static async Task Main(string[] args)
|
||||
@@ -16,37 +75,143 @@ namespace ElectronNET.WebApp
|
||||
|
||||
try
|
||||
{
|
||||
// Start Electron runtime
|
||||
await runtimeController.Start();
|
||||
|
||||
await runtimeController.WaitReadyTask;
|
||||
|
||||
await ElectronBootstrap();
|
||||
// Initialize your Electron app
|
||||
await InitializeApp();
|
||||
|
||||
// Wait for shutdown
|
||||
await runtimeController.WaitStoppedTask;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine(ex);
|
||||
await runtimeController.Stop().ConfigureAwait(false);
|
||||
|
||||
await runtimeController.WaitStoppedTask.WaitAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
|
||||
Console.WriteLine($"Error: {ex.Message}");
|
||||
await runtimeController.Stop();
|
||||
await runtimeController.WaitStoppedTask.WaitAsync(TimeSpan.FromSeconds(2));
|
||||
}
|
||||
}
|
||||
|
||||
public static async Task ElectronBootstrap()
|
||||
private static async Task InitializeApp()
|
||||
{
|
||||
//AddDevelopmentTests();
|
||||
// Create main window
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Show = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions
|
||||
{
|
||||
Width = 1152,
|
||||
Height = 940,
|
||||
Show = false,
|
||||
}, "https://github.com/ElectronNET/Electron.NET");
|
||||
|
||||
await browserWindow.WebContents.Session.ClearCacheAsync();
|
||||
// Load your content (file system, remote URL, etc.)
|
||||
await browserWindow.WebContents.LoadURLAsync("https://example.com");
|
||||
|
||||
// Show window when ready
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📁 Content Sources
|
||||
|
||||
### File System Content
|
||||
|
||||
Serve HTML/JS files from your project:
|
||||
|
||||
```csharp
|
||||
// In your project root, create wwwroot/index.html
|
||||
await browserWindow.WebContents.LoadFileAsync("wwwroot/index.html");
|
||||
```
|
||||
|
||||
### Remote Content
|
||||
|
||||
Load content from any web server:
|
||||
|
||||
```csharp
|
||||
await browserWindow.WebContents.LoadURLAsync("https://your-server.com/app");
|
||||
```
|
||||
|
||||
### Development Server
|
||||
|
||||
For development, you can run a simple HTTP server:
|
||||
|
||||
```csharp
|
||||
// Add this for development
|
||||
if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development")
|
||||
{
|
||||
await browserWindow.WebContents.LoadURLAsync("http://localhost:3000");
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Configuration Options
|
||||
|
||||
### Project Configuration
|
||||
|
||||
Configure Electron settings through MSBuild properties in your `.csproj`:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<ElectronNETCoreDescription>My Electron App</ElectronNETCoreDescription>
|
||||
<ElectronNETCoreDisplayName>MyApp</ElectronNETCoreDisplayName>
|
||||
<ElectronNETCoreAuthorName>Your Name</ElectronNETCoreAuthorName>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Runtime Configuration
|
||||
|
||||
Access configuration at runtime:
|
||||
|
||||
```csharp
|
||||
var app = await Electron.App.GetAppAsync();
|
||||
Console.WriteLine($"App Name: {app.Name}");
|
||||
```
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### Window Options
|
||||
|
||||
Customize your main window:
|
||||
|
||||
```csharp
|
||||
var options = new BrowserWindowOptions
|
||||
{
|
||||
Width = 1400,
|
||||
Height = 900,
|
||||
MinWidth = 800,
|
||||
MinHeight = 600,
|
||||
Frame = true,
|
||||
Title = "My Custom App",
|
||||
Icon = "assets/app-icon.png"
|
||||
};
|
||||
```
|
||||
|
||||
### Multiple Windows
|
||||
|
||||
Create additional windows as needed:
|
||||
|
||||
```csharp
|
||||
var settingsWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Width = 600, Height = 400, Modal = true },
|
||||
"app://settings.html");
|
||||
```
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Debugging](Debugging.md)** - Learn about debugging console applications
|
||||
- **[Package Building](Package-Building.md)** - Create distributable packages
|
||||
- **[Migration Guide](../Core/Migration-Guide.md)** - Moving from ASP.NET projects
|
||||
|
||||
## 💡 Benefits of Console Apps
|
||||
|
||||
✅ **Simpler Architecture** - No ASP.NET complexity when not needed
|
||||
✅ **Flexible Content** - Use any HTML/JS source
|
||||
✅ **Faster Development** - Less overhead for simple applications
|
||||
✅ **Easy Deployment** - Minimal dependencies
|
||||
✅ **Better Performance** - Lighter weight than full web applications
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
# 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.
|
||||
|
||||
explain the ease of debugging and everything from what you've already read.
|
||||
## 🎯 Debugging Modes
|
||||
|
||||
ElectronNET.Core supports three main debugging approaches, all configured through Visual Studio's launch profiles:
|
||||
|
||||
This config enables all three possible ways for unpackaged debugging:
|
||||
### 1. ASP.NET-First Debugging (Recommended)
|
||||
|
||||
Debug your .NET code directly with full Hot Reload support:
|
||||
|
||||
The first and last are working by default (newly created prject). The 2nd one needs to the added manually, if desired.
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"ASP.Net (unpackaged)": {
|
||||
@@ -16,7 +18,83 @@ The first and last are working by default (newly created prject). The 2nd one ne
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
},
|
||||
"applicationUrl": "http://localhost:8001/"
|
||||
"applicationUrl": "https://localhost:7001/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**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:7001/",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development",
|
||||
"ASPNETCORE_URLS": "http://localhost:7001/"
|
||||
},
|
||||
"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": "https://localhost:7001/"
|
||||
},
|
||||
"Electron (unpackaged)": {
|
||||
"commandName": "Executable",
|
||||
@@ -29,15 +107,130 @@ The first and last are working by default (newly created prject). The 2nd one ne
|
||||
},
|
||||
"WSL": {
|
||||
"commandName": "WSL2",
|
||||
"launchUrl": "http://localhost:8001/",
|
||||
"launchUrl": "http://localhost:7001/",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development",
|
||||
"ASPNETCORE_URLS": "http://localhost:8001/"
|
||||
"ASPNETCORE_URLS": "http://localhost:7001/"
|
||||
},
|
||||
"distributionName": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Important: The runtime identifier needs to be changed in the project when switching between Windows and WSL.
|
||||
### 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
|
||||
|
||||
@@ -1,83 +1,85 @@
|
||||
# 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.
|
||||
|
||||
explain how to use VS publish to create package with electron-builder.
|
||||
## 🎯 Publishing Overview
|
||||
|
||||
The folder publishing is not the same between ASP.Net and console ap.
|
||||
The publishing process differs slightly between ASP.NET and console applications:
|
||||
|
||||
## For ASP.Net, these are working publishing profiles:
|
||||
- **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: Configure Runtime Identifier
|
||||
|
||||
Set the target platform in your `.csproj` file:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier> <!-- or linux-x64, osx-x64, etc. -->
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Step 2: Create Publish Profile
|
||||
|
||||
Add publish profiles to `Properties/PublishProfiles/`:
|
||||
|
||||
#### ASP.NET Application Profile (Windows)
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<DeleteExistingFiles>true</DeleteExistingFiles>
|
||||
<ExcludeApp_Data>false</ExcludeApp_Data>
|
||||
<LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
|
||||
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
|
||||
<PublishProvider>FileSystem</PublishProvider>
|
||||
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
|
||||
<WebPublishMethod>FileSystem</WebPublishMethod>
|
||||
<_TargetId>Folder</_TargetId>
|
||||
<SiteUrlToLaunchAfterPublish />
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
|
||||
<ProjectGuid>6ea447d9-343f-46b8-b456-66557bddbb9f</ProjectGuid>
|
||||
<SelfContained>true</SelfContained>
|
||||
<LastUsedPlatform>Any CPU</LastUsedPlatform>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<DeleteExistingFiles>true</DeleteExistingFiles>
|
||||
<ExcludeApp_Data>false</ExcludeApp_Data>
|
||||
<LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
|
||||
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
|
||||
<PublishProvider>FileSystem</PublishProvider>
|
||||
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
|
||||
<WebPublishMethod>FileSystem</WebPublishMethod>
|
||||
<_TargetId>Folder</_TargetId>
|
||||
<SiteUrlToLaunchAfterPublish />
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<ProjectGuid>6ea447d9-343f-46b8-b456-66557bddbb9f</ProjectGuid>
|
||||
<SelfContained>true</SelfContained>
|
||||
<LastUsedPlatform>Any CPU</LastUsedPlatform>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
|
||||
|
||||
|
||||
## For a console app, these ones are working:
|
||||
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\Release\net8.0\linux-x64</PublishDir>
|
||||
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
|
||||
<PublishProtocol>FileSystem</PublishProtocol>
|
||||
<_TargetId>Folder</_TargetId>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
|
||||
<SelfContained>false</SelfContained>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<SelfContained>true</SelfContained>
|
||||
<PublishSingleFile>false</PublishSingleFile>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### ASP.NET Application Profile (Linux)
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<Configuration>Release</Configuration>
|
||||
<Platform>Any CPU</Platform>
|
||||
<PublishDir>publish\Release\net8.0\win-x64</PublishDir>
|
||||
<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)
|
||||
|
||||
```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>
|
||||
<_TargetId>Folder</_TargetId>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<SelfContained>false</SelfContained>
|
||||
@@ -85,4 +87,235 @@ The folder publishing is not the same between ASP.Net and console ap.
|
||||
<PublishReadyToRun>false</PublishReadyToRun>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Console Application Profile (Linux)
|
||||
|
||||
```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 3: Configure Electron Builder
|
||||
|
||||
ElectronNET.Core automatically generates `electron-builder.json` based on your project configuration. Key settings include:
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "My Electron App",
|
||||
"appId": "com.mycompany.myapp",
|
||||
"directories": {
|
||||
"output": "release"
|
||||
},
|
||||
"files": [
|
||||
"**/*",
|
||||
"!**/*.pdb"
|
||||
],
|
||||
"win": {
|
||||
"target": "nsis",
|
||||
"icon": "assets/app.ico"
|
||||
},
|
||||
"linux": {
|
||||
"target": "AppImage",
|
||||
"icon": "assets/app.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Publish from Visual Studio
|
||||
|
||||
1. **Right-click your project** in Solution Explorer
|
||||
2. **Select "Publish"**
|
||||
3. **Choose "Folder"** as the publish target
|
||||
4. **Select your publish profile** (Windows/Linux)
|
||||
5. **Click "Publish"**
|
||||
|
||||
The publish process will:
|
||||
- Build your .NET application
|
||||
- Generate Electron configuration files
|
||||
- Copy Electron runtime files
|
||||
- Install npm dependencies
|
||||
- Create electron-builder configuration
|
||||
|
||||
### Step 5: Build Final Package
|
||||
|
||||
After publishing, build the final package:
|
||||
|
||||
```bash
|
||||
# Navigate to publish directory
|
||||
cd publish\Release\net8.0\win-x64\
|
||||
|
||||
# Install dependencies and build
|
||||
npm install
|
||||
npx electron-builder
|
||||
|
||||
# Find your package in the 'release' folder
|
||||
```
|
||||
|
||||
## 📁 Output Structure
|
||||
|
||||
After publishing, your folder structure will look like:
|
||||
|
||||
```
|
||||
publish\Release\net8.0\win-x64\
|
||||
├── MyElectronApp.exe # Your .NET application
|
||||
├── .electron\ # Electron runtime files
|
||||
│ ├── main.js
|
||||
│ ├── package.json
|
||||
│ └── node_modules\
|
||||
├── wwwroot\ # (ASP.NET only) Web assets
|
||||
├── electron-builder.json # Build configuration
|
||||
└── release\ # Final packages (after electron-builder)
|
||||
├── MyElectronApp-1.0.0.exe
|
||||
└── MyElectronApp-1.0.0-setup.exe
|
||||
```
|
||||
|
||||
## 🔧 Configuration Options
|
||||
|
||||
### Project Configuration
|
||||
|
||||
Configure Electron settings in your `.csproj`:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<ElectronNETCoreDescription>My Electron Application</ElectronNETCoreDescription>
|
||||
<ElectronNETCoreDisplayName>MyApp</ElectronNETCoreDisplayName>
|
||||
<ElectronNETCoreAuthorName>Your Company</ElectronNETCoreAuthorName>
|
||||
<ElectronNETCoreVersion>1.0.0</ElectronNETCoreVersion>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Electron Builder Configuration
|
||||
|
||||
Customize `electron-builder.json` for your needs:
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "MyApp",
|
||||
"appId": "com.mycompany.myapp",
|
||||
"copyright": "Copyright © 2024 My Company",
|
||||
"win": {
|
||||
"target": "nsis",
|
||||
"icon": "assets/icon.ico",
|
||||
"publisherName": "My Company"
|
||||
},
|
||||
"linux": {
|
||||
"target": "AppImage",
|
||||
"icon": "assets/icon.png",
|
||||
"category": "Office"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Platform-Specific Settings
|
||||
|
||||
### Windows Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"win": {
|
||||
"target": "nsis",
|
||||
"icon": "assets/app.ico",
|
||||
"verifyUpdateCodeSignature": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Linux Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"linux": {
|
||||
"target": "AppImage",
|
||||
"icon": "assets/app.png",
|
||||
"category": "Development"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### macOS Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mac": {
|
||||
"target": "dmg",
|
||||
"icon": "assets/app.icns",
|
||||
"category": "public.app-category.developer-tools"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚀 Advanced Publishing
|
||||
|
||||
### Cross-Platform Building
|
||||
|
||||
Build for multiple platforms from Windows using WSL:
|
||||
|
||||
1. **Set RuntimeIdentifier** to `linux-x64`
|
||||
2. **Publish to folder** using Linux profile
|
||||
3. **Copy to WSL** or build directly in WSL
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
For automated builds:
|
||||
|
||||
```bash
|
||||
# Restore packages
|
||||
dotnet restore
|
||||
|
||||
# Publish for specific platform
|
||||
dotnet publish -c Release -r win-x64 --self-contained
|
||||
|
||||
# Build Electron package
|
||||
cd publish\Release\net8.0\win-x64
|
||||
npm install
|
||||
npx electron-builder --publish=never
|
||||
```
|
||||
|
||||
## 🛠 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"electron-builder.json not found"**
|
||||
- Ensure project is published first
|
||||
- Check that RuntimeIdentifier is set
|
||||
- Verify .NET build succeeded
|
||||
|
||||
**"npm install fails"**
|
||||
- Ensure Node.js 22.x is installed
|
||||
- Check internet connection for npm packages
|
||||
- Verify no conflicting package versions
|
||||
|
||||
**"WSL publishing fails"**
|
||||
- Ensure WSL2 is properly configured
|
||||
- Check that Linux RID is set correctly
|
||||
- Verify WSL can access Windows files
|
||||
|
||||
## 🎨 Publishing Workflow
|
||||
|
||||
*Placeholder for image showing Visual Studio publish dialog and electron-builder output*
|
||||
|
||||
## 🚀 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
|
||||
|
||||
@@ -1,17 +1,243 @@
|
||||
# Startup Methods
|
||||
|
||||
// Explain the different startup modes
|
||||
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.
|
||||
|
||||
- Support new commandline flags:
|
||||
- unpackedelectron
|
||||
running in debug mode, electron first, so must launch dotnet
|
||||
- unpackeddotnet
|
||||
running in debug mode, dotnet first, do not launch dotnet
|
||||
- dotnetpacked
|
||||
running from electron-builder output, dotnet first, do not launch
|
||||
- {none of the above flags}
|
||||
running from electron-builder output, electron first, launch dotnet
|
||||
## 🎯 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("https://localhost:7001");
|
||||
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
|
||||
|
||||
*Placeholder for image showing the 8 different startup mode flows*
|
||||
|
||||
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.
|
||||
|
||||
59
docs/Home.md
59
docs/Home.md
@@ -1,4 +1,61 @@
|
||||
|
||||
|
||||
### Electron.NET Wiki Home
|
||||
# Electron.NET Wiki Home
|
||||
|
||||
Welcome to the **Electron.NET Core** documentation! This wiki covers everything you need to know about building cross-platform desktop applications with ASP.NET Core and Electron.NET.
|
||||
|
||||
## 🚀 What is Electron.NET Core?
|
||||
|
||||
Electron.NET Core is a complete modernization of Electron.NET that eliminates the CLI tool dependency and integrates deeply with Visual Studio's MSBuild system. It transforms the development experience by providing:
|
||||
|
||||
- **Native Visual Studio Integration** - No more CLI tools or JSON configuration files
|
||||
- **Console Application Support** - Build Electron apps with simple console applications, not just ASP.NET
|
||||
- **Cross-Platform Development** - Build and debug Linux applications from Windows via WSL
|
||||
- **Enhanced Debugging** - ASP.NET-first debugging with Hot Reload support
|
||||
- **Flexible Architecture** - Choose any Electron version and target multiple platforms
|
||||
|
||||
## 📚 Documentation Sections
|
||||
|
||||
### [Core Documentation](Core/What's-New.md)
|
||||
- **[What's New?](Core/What's-New.md)** - Complete overview of ElectronNET.Core features and improvements
|
||||
- **[Migration Guide](Core/Migration-Guide.md)** - Step-by-step migration from previous versions
|
||||
- **[Advanced Migration Topics](Core/Advanced-Migration-Topics.md)** - Technical details for complex scenarios
|
||||
|
||||
### [Getting Started](GettingStarted/ASP.Net.md)
|
||||
- **[ASP.NET Applications](GettingStarted/ASP.Net.md)** - Build Electron apps with ASP.NET Core
|
||||
- **[Console Applications](GettingStarted/Console-App.md)** - Use console apps for file system or remote content
|
||||
- **[Startup Methods](GettingStarted/Startup-Methods.md)** - Understanding different launch scenarios
|
||||
- **[Debugging](GettingStarted/Debugging.md)** - Debug Electron apps effectively in Visual Studio
|
||||
- **[Package Building](GettingStarted/Package-Building.md)** - Create distributable packages
|
||||
|
||||
### [Release Information](Releases/Package-Description.md)
|
||||
- **[Package Description](Releases/Package-Description.md)** - Understanding the three NuGet packages
|
||||
- **[Changelog](../Changelog.md)** - Complete list of changes and improvements
|
||||
|
||||
## 🛠 System Requirements
|
||||
|
||||
- **.NET 8.0** or later
|
||||
- **Node.js 22.x** or later
|
||||
- **Visual Studio 2022** (recommended) or other .NET IDE
|
||||
- **WSL2** (for Linux development on Windows)
|
||||
|
||||
## 💡 Key Benefits
|
||||
|
||||
✅ **No CLI Tools Required** - Everything works through Visual Studio
|
||||
✅ **Console App Support** - Use any HTML/JS source, not just ASP.NET
|
||||
✅ **True Cross-Platform** - Build Linux apps from Windows
|
||||
✅ **Modern Debugging** - Hot Reload and ASP.NET-first debugging
|
||||
✅ **Flexible Packaging** - Choose any Electron version
|
||||
✅ **MSBuild Integration** - Leverages .NET's build system
|
||||
|
||||
## 🚦 Getting Started
|
||||
|
||||
New to ElectronNET.Core? Start here:
|
||||
|
||||
1. **[ASP.NET Setup](GettingStarted/ASP.Net.md)** - Traditional web application approach
|
||||
2. **[Console App Setup](GettingStarted/Console-App.md)** - Lightweight console application approach
|
||||
3. **[Migration Guide](Core/Migration-Guide.md)** - Moving from previous versions
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Found an issue or want to improve the documentation? Contributions are welcome! The wiki is auto-generated from the `/docs` folder in the [GitHub repository](https://github.com/ElectronNET/Electron.NET).
|
||||
|
||||
102
docs/RelInfo/Package-Description.md
Normal file
102
docs/RelInfo/Package-Description.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Package Description
|
||||
|
||||
ElectronNET.Core consists of three specialized NuGet packages designed for different development scenarios and project architectures.
|
||||
|
||||
## 📦 Package Overview
|
||||
|
||||
### ElectronNET.Core (Main Package)
|
||||
**Primary package for Electron.NET applications**
|
||||
|
||||
- **Build system integration** - MSBuild targets and tasks for Electron
|
||||
- **Project system extensions** - Visual Studio designer integration
|
||||
- **Runtime orchestration** - Process lifecycle management
|
||||
- **Automatic configuration** - Generates electron-builder.json and package.json
|
||||
- **Includes ElectronNET.Core.Api** as a dependency
|
||||
|
||||
**When to use:**
|
||||
- Main application projects (startup projects)
|
||||
- Projects that need full Electron.NET functionality
|
||||
- Applications requiring build-time Electron configuration
|
||||
|
||||
### ElectronNET.Core.Api (API Package)
|
||||
**Pure API definitions without build integration**
|
||||
|
||||
- **Electron API wrappers** - Complete Electron API surface
|
||||
- **Type definitions** - Full TypeScript-style IntelliSense
|
||||
- **No build dependencies** - Clean API-only package
|
||||
- **Multi-platform support** - Windows, macOS, Linux
|
||||
|
||||
**When to use:**
|
||||
- Class library projects that interact with Electron APIs
|
||||
- Projects that only need API access without build integration
|
||||
- Multi-project solutions where only the startup project needs build integration
|
||||
|
||||
### ElectronNET.Core.AspNet (ASP.NET Integration)
|
||||
**ASP.NET-specific runtime components**
|
||||
|
||||
- **ASP.NET middleware** - UseElectron() extension methods
|
||||
- **WebHost integration** - Seamless ASP.NET + Electron hosting
|
||||
- **Hot Reload support** - Enhanced debugging experience
|
||||
- **Web-specific optimizations** - ASP.NET tailored performance
|
||||
|
||||
**When to use:**
|
||||
- ASP.NET Core projects building Electron applications
|
||||
- Applications requiring web server functionality
|
||||
- Projects using MVC, Razor Pages, or Blazor
|
||||
|
||||
## 🏗 Architecture Benefits
|
||||
|
||||
### Separation of Concerns
|
||||
- **Build logic separate from API** - Cleaner dependency management
|
||||
- **Optional ASP.NET integration** - Use only what you need
|
||||
- **Multi-project friendly** - Share APIs across projects without build conflicts
|
||||
|
||||
### Project Scenarios
|
||||
|
||||
**Single Project (ASP.NET):**
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core" Version="1.0.0" />
|
||||
<PackageReference Include="ElectronNET.Core.AspNet" Version="1.0.0" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
**Single Project (Console):**
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core" Version="1.0.0" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
**Multi-Project Solution:**
|
||||
```xml
|
||||
<!-- Startup project -->
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core" Version="1.0.0" />
|
||||
<PackageReference Include="ElectronNET.Core.AspNet" Version="1.0.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<!-- Class library projects -->
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core.Api" Version="1.0.0" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
## 🔗 Dependency Chain
|
||||
|
||||
```
|
||||
ElectronNET.Core.AspNet
|
||||
↓
|
||||
ElectronNET.Core → ElectronNET.Core.Api
|
||||
```
|
||||
|
||||
- **ElectronNET.Core.AspNet** depends on ElectronNET.Core
|
||||
- **ElectronNET.Core** depends on ElectronNET.Core.Api
|
||||
- **ElectronNET.Core.Api** has no dependencies
|
||||
|
||||
## 💡 Recommendations
|
||||
|
||||
✅ **Start with ElectronNET.Core** for new projects
|
||||
✅ **Add ElectronNET.Core.AspNet** only for ASP.NET applications
|
||||
✅ **Use ElectronNET.Core.Api** for class libraries and API-only scenarios
|
||||
✅ **Multi-project solutions** benefit from the modular architecture
|
||||
Reference in New Issue
Block a user