mirror of
https://github.com/ElectronNET/Electron.NET.git
synced 2026-07-08 17:56:51 +00:00
Update docs after manual review
This commit is contained in:
softworkz
@@ -6,46 +6,47 @@ This guide covers advanced scenarios and edge cases that may require additional
|
||||
|
||||
### Port Configuration Changes
|
||||
|
||||
**Previous Approach:**
|
||||
**Previous Approach:**
|
||||
Specifying the WebPort in `electron.manifest.json` is no longer supported because the ASP.NET-first launch mode makes this timing-dependent.
|
||||
|
||||
**New Approach:**
|
||||
**New Approach:**
|
||||
Configure custom ASP.NET ports through MSBuild metadata:
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<AssemblyMetadata Include="AspNetHttpPort" Value="4000" />
|
||||
<AssemblyMetadata Include="AspNetHttpsPort" Value="4001" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
**Usage in Code:**
|
||||
```csharp
|
||||
// Access configured ports at runtime
|
||||
var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5000");
|
||||
```
|
||||
|
||||
## Custom ElectronHostHook Configuration
|
||||
|
||||
> [!NOTE]
|
||||
> These changes are only required in case you are using a custom ElectronHostHook implementation!
|
||||
> If you have an ElectronHostHook folder in your project but you did not customize that code and aren't using its demo features (Excel and ZIP), you can also just remove that folder from your project.
|
||||
|
||||
|
||||
### TypeScript and Node.js Updates
|
||||
|
||||
**Update package.json:**
|
||||
|
||||
This shows the delevant changes only: All shown versions are the new required minimum versions.
|
||||
|
||||
```json
|
||||
{
|
||||
"devDependencies": {
|
||||
"eslint": "^9.37.0",
|
||||
"@types/node": "^22.18",
|
||||
"typescript": "^5.9.3"
|
||||
},
|
||||
"dependencies": {
|
||||
"archiver-utils": "^2.1.0",
|
||||
"socket.io": "^4.8.1",
|
||||
"exceljs": "^1.10.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Update Project File:**
|
||||
**Update Project File:**
|
||||
|
||||
The below modifications will allow you to use the latest TypeScript compiler in your ASP.Net project.
|
||||
|
||||
```xml
|
||||
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3" />
|
||||
|
||||
@@ -78,33 +79,9 @@ var port = int.Parse(Electron.App.GetEnvironmentVariable("AspNetHttpPort") ?? "5
|
||||
When using ElectronNET.Core in multi-project solutions:
|
||||
|
||||
1. **Install ElectronNET.Core.Api** in class library projects
|
||||
2. **Install ElectronNET.Core** only in the startup project
|
||||
2. **Install ElectronNET.Core and ElectronNET.Core.AspNet** only in the startup project
|
||||
3. **Share configuration** through project references or shared files
|
||||
|
||||
### Custom Build Processes
|
||||
|
||||
For advanced build customization:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<ElectronNETCoreOutputPath>custom\output\path</ElectronNETCoreOutputPath>
|
||||
<ElectronNETCoreNodeModulesPath>custom\node_modules</ElectronNETCoreNodeModulesPath>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Environment-Specific Configuration
|
||||
|
||||
Handle different environments with conditional configuration:
|
||||
|
||||
```xml
|
||||
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
|
||||
<ElectronNETCoreEnvironment>Development</ElectronNETCoreEnvironment>
|
||||
</PropertyGroup>
|
||||
|
||||
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
|
||||
<ElectronNETCoreEnvironment>Production</ElectronNETCoreEnvironment>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
||||
@@ -25,15 +25,15 @@ PM> Install-Package ElectronNET.Core
|
||||
PM> Install-Package ElectronNET.Core.AspNet # For ASP.NET projects
|
||||
```
|
||||
|
||||
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`. See [Package Description](../Releases/Package-Description.md) for details about the package structure.
|
||||
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`. See [Package Description](../RelInfo/Package-Description.md) for details about the package structure.
|
||||
|
||||
|
||||
### Step 2: Configure Project Settings
|
||||
|
||||
**Auto-generated Configuration:**
|
||||
**Auto-generated Configuration:**
|
||||
ElectronNET.Core automatically creates `electron-builder.json` during the first build or NuGet restore. No manual configuration is needed for basic setups.
|
||||
|
||||
**Migrate Existing Configuration:**
|
||||
**Migrate Existing Configuration:**
|
||||
If you have an existing `electron.manifest.json` file:
|
||||
|
||||
1. **Open the generated `electron-builder.json`** file in your project
|
||||
@@ -47,14 +47,18 @@ You can also manually edit `electron-builder.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "My Electron App",
|
||||
"appId": "com.mycompany.myapp",
|
||||
"directories": {
|
||||
"output": "release"
|
||||
"linux": {
|
||||
"target": [
|
||||
"tar.xz"
|
||||
]
|
||||
},
|
||||
"win": {
|
||||
"target": "nsis",
|
||||
"icon": "assets/app.ico"
|
||||
"target": [
|
||||
{
|
||||
"target": "portable",
|
||||
"arch": "x64"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -71,12 +75,10 @@ After completing the migration steps:
|
||||
## 🚨 Common Migration Issues
|
||||
|
||||
### Build Errors
|
||||
- **Missing RuntimeIdentifier**: Ensure `<RuntimeIdentifier>win-x64</RuntimeIdentifier>` is set
|
||||
- **Node.js version**: Verify Node.js 22.x is installed and in PATH
|
||||
- **Package conflicts**: Clean NuGet cache if needed
|
||||
|
||||
### Runtime Errors
|
||||
- **Port conflicts**: Update URLs in startup code to match your configuration
|
||||
- **Missing electron-builder.json**: Trigger rebuild or manual NuGet restore
|
||||
- **Process termination**: Use .NET-first startup mode for better cleanup
|
||||
|
||||
@@ -84,15 +86,15 @@ After completing the migration steps:
|
||||
|
||||
- **[What's New?](What's-New.md)** - Complete overview of ElectronNET.Core features
|
||||
- **[Advanced Migration Topics](Advanced-Migration-Topics.md)** - Handle complex scenarios
|
||||
- **[Getting Started](GettingStarted/ASP.Net.md)** - Learn about new development workflows
|
||||
- **[Getting Started](../GettingStarted/ASP.Net.md)** - Learn about new development workflows
|
||||
|
||||
## 💡 Migration Benefits
|
||||
|
||||
✅ **Simplified Configuration** - No more CLI tools or JSON files
|
||||
✅ **Better Debugging** - Native Visual Studio experience with Hot Reload
|
||||
✅ **Modern Architecture** - .NET-first process lifecycle
|
||||
✅ **Cross-Platform Ready** - Build Linux apps from Windows
|
||||
✅ **Future-Proof** - Flexible Electron version selection
|
||||
✅ **Simplified Configuration** - No more CLI tools or JSON files
|
||||
✅ **Better Debugging** - Native Visual Studio experience with Hot Reload
|
||||
✅ **Modern Architecture** - .NET-first process lifecycle
|
||||
✅ **Cross-Platform Ready** - Build Linux apps from Windows
|
||||
✅ **Future-Proof** - Flexible Electron version selection
|
||||
|
||||
### Step 3: Update Startup Code
|
||||
|
||||
@@ -104,76 +106,58 @@ After completing the migration steps:
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
// Enable Electron.NET with callback
|
||||
builder.WebHost.UseElectron(args, async () =>
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
builder.UseElectron(args, ElectronAppReady);
|
||||
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
});
|
||||
var app = builder.Build();
|
||||
app.Run();
|
||||
}
|
||||
|
||||
var app = builder.Build();
|
||||
app.Run();
|
||||
public static async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
```
|
||||
|
||||
#### Traditional ASP.NET Core (IWebHostBuilder)
|
||||
|
||||
```csharp
|
||||
```csharp
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
CreateWebHostBuilder(args).Build().Run();
|
||||
}
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>()
|
||||
.Build()
|
||||
.Run();
|
||||
}
|
||||
|
||||
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
|
||||
WebHost.CreateDefaultBuilder(args)
|
||||
.UseElectron(args, ElectronAppReady)
|
||||
.UseStartup<Startup>();
|
||||
public static async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
// Electron callback
|
||||
async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:5001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Step 4: Update Development Tools
|
||||
|
||||
**Node.js Upgrade:**
|
||||
ElectronNET.Core requires Node.js 22.x. Update your installation:
|
||||
|
||||
**Windows:**
|
||||
1. Download from [nodejs.org](https://nodejs.org)
|
||||
2. Run the installer
|
||||
3. Verify: `node --version` should show v22.x.x
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
# Using Node Version Manager (recommended)
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install 22
|
||||
nvm use 22
|
||||
|
||||
# Or using package manager
|
||||
sudo apt update
|
||||
sudo apt install nodejs=22.*
|
||||
```
|
||||
See [System Requirements](../GettingStarted/System-Requirements.md).
|
||||
|
||||
### Step 5: Update Debugging Setup
|
||||
|
||||
**Watch Feature Removal:**
|
||||
|
||||
The old 'watch' feature is no longer supported. Instead, use the new ASP.NET-first debugging with Hot Reload:
|
||||
|
||||
- **Old approach**: Manual process attachment and slow refresh
|
||||
@@ -181,4 +165,6 @@ The old 'watch' feature is no longer supported. Instead, use the new ASP.NET-fir
|
||||
- **Benefits**: Faster development cycle, better debugging experience
|
||||
|
||||
**Update Launch Settings:**
|
||||
Replace old watch configurations with new debugging profiles. See [Debugging](GettingStarted/Debugging.md) for detailed setup instructions.
|
||||
|
||||
Replace old watch configurations with new debugging profiles. See [Debugging](../GettingStarted/Debugging.md) for detailed setup instructions.
|
||||
|
||||
|
||||
@@ -20,13 +20,14 @@ The new package architecture reflects a clearer separation of concerns:
|
||||
- **ElectronNET.Core.Api** - Pure API definitions for Electron integration
|
||||
- **ElectronNET.Core.AspNet** - ASP.NET-specific runtime components
|
||||
|
||||
This modular approach allows projects to include only what they need while maintaining the flexibility to scale from simple console applications to complex web applications.
|
||||
This modular approach allows projects to include only what they need while maintaining the flexibility to scale from simple console applications to complex web applications.
|
||||
More about the avaílable nuget packages: [Package Description](../RelInfo/Package-Description.md).
|
||||
|
||||
## Beyond ASP.NET: Console Application Support
|
||||
|
||||
### A Fundamental Shift in Accessibility
|
||||
### A Shift in Accessibility
|
||||
|
||||
One of the most significant breakthroughs in ElectronNET.Core is the removal of the ASP.NET requirement. Developers can now build Electron applications using simple console applications, dramatically expanding the use cases and removing a major barrier to adoption.
|
||||
A major new opportunity in ElectronNET.Core is the removal of the ASP.NET requirement. Developers can now build Electron solutions using simple DotNet console applications, expanding the use cases and removing a major barrier to adoption for a number of use cases.
|
||||
|
||||
### Flexible Content Sources
|
||||
|
||||
@@ -43,7 +44,7 @@ This capability transforms ElectronNET from a web-focused framework into a versa
|
||||
|
||||
### Debugging Reimagined
|
||||
|
||||
The debugging experience has been completely transformed. The new ASP.NET-first launch mode means developers can now debug their .NET code directly, with full access to familiar debugging tools and Hot Reload capabilities. No more attaching to processes or working around limited debugging scenarios—the development workflow now matches standard ASP.NET development patterns.
|
||||
The debugging experience has been completely transformed. The new DotNet-first launch mode means developers can now debug their .NET code directly, with full access to familiar debugging tools and Hot Reload capabilities. No more attaching to processes or working around limited debugging scenarios — the development workflow now matches standard .NET development patterns.
|
||||
|
||||
### Cross-Platform Development Without Compromises
|
||||
|
||||
@@ -71,7 +72,8 @@ The underlying process architecture has been fundamentally redesigned. Instead o
|
||||
- Enhanced error handling and recovery
|
||||
- Cleaner separation between web and native concerns
|
||||
|
||||
This architecture supports eight different launch scenarios, covering every combination of packaged/unpackaged deployment, console/ASP.NET hosting, and dotnet-first/electron-first initialization.
|
||||
This architecture supports eight different launch scenarios, covering every combination of packaged/unpackaged deployment, console/ASP.NET hosting, and dotnet-first/electron-first initialization. The Electron-first launch method is still available or course.
|
||||
For more details, see: [Startup Methods](../GettingStarted/Startup-Methods.md).
|
||||
|
||||
### Unpackaged Development Mode
|
||||
|
||||
@@ -103,7 +105,9 @@ The migration path is designed to be straightforward:
|
||||
1. Update package references to the new structure
|
||||
2. Remove the old manifest file
|
||||
3. Configure project properties through Visual Studio
|
||||
4. Adopt new debugging workflows at your own pace
|
||||
4. Adopt new debugging workflows at your own pace
|
||||
|
||||
Further reading: [Migration Guide](Migration-Guide.md).
|
||||
|
||||
## Future Horizons
|
||||
|
||||
|
||||
@@ -1,22 +1,12 @@
|
||||
|
||||
|
||||
# ASP.NET Core Setup
|
||||
|
||||
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.
|
||||
|
||||
## 🛠 System Requirements
|
||||
|
||||
### 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
|
||||
See [System Requirements](../GettingStarted/System-Requirements.md).
|
||||
|
||||
### Supported Operating Systems
|
||||
- **Windows 10/11** (x64, ARM64)
|
||||
- **macOS 11+** (Intel, Apple Silicon)
|
||||
- **Linux** (most distributions with glibc 2.31+)
|
||||
|
||||
> **Note**: For Linux development on Windows, install [WSL2](https://docs.microsoft.com/windows/wsl/install) to build and debug Linux packages.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
@@ -35,8 +25,11 @@ cd MyElectronWebApp
|
||||
PM> Install-Package ElectronNET.Core
|
||||
PM> Install-Package ElectronNET.Core.AspNet
|
||||
```
|
||||
|
||||
|
||||
> [!Note]
|
||||
> `ElectronNET.Core.AspNet` provides ASP.NET-specific runtime components and should be used alongside `ElectronNET.Core`.
|
||||
|
||||
> **Note**: `ElectronNET.Core.AspNet` provides ASP.NET-specific runtime components and should be used alongside `ElectronNET.Core`.
|
||||
|
||||
### 3. Configure Program.cs
|
||||
|
||||
@@ -46,134 +39,56 @@ Update your `Program.cs` to enable Electron.NET:
|
||||
using ElectronNET.API;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
// Enable Electron.NET with callback for UI setup
|
||||
builder.WebHost.UseElectron(args, ElectronAppReady);
|
||||
|
||||
// Add services to the container
|
||||
builder.Services.AddControllersWithViews();
|
||||
|
||||
var app = builder.Build();
|
||||
|
||||
// Configure the HTTP request pipeline
|
||||
if (!app.Environment.IsDevelopment())
|
||||
public class Program
|
||||
{
|
||||
app.UseExceptionHandler("/Home/Error");
|
||||
app.UseHsts();
|
||||
}
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
app.UseHttpsRedirection();
|
||||
app.UseStaticFiles();
|
||||
app.UseRouting();
|
||||
app.UseAuthorization();
|
||||
builder.Services.AddRazorPages();
|
||||
|
||||
app.MapControllerRoute(
|
||||
name: "default",
|
||||
pattern: "{controller=Home}/{action=Index}/{id?}");
|
||||
// Add this line to enable Electron.NET:
|
||||
builder.UseElectron(args, ElectronAppReady);
|
||||
|
||||
app.Run();
|
||||
var app = builder.Build();
|
||||
|
||||
// Electron initialization callback
|
||||
async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
if (!app.Environment.IsDevelopment())
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Show = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
app.UseExceptionHandler("/Error");
|
||||
}
|
||||
app.UseStaticFiles();
|
||||
|
||||
// Load your ASP.NET application
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
|
||||
app.UseRouting();
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
app.UseAuthorization();
|
||||
|
||||
app.MapRazorPages();
|
||||
|
||||
app.Run();
|
||||
}
|
||||
|
||||
public static async Task ElectronAppReady()
|
||||
{
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions { Show = false });
|
||||
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ASP.NET Port
|
||||
|
||||
If you want to launch a specific URL, you can retrieve the actual ASP.NET port from the new `ElectronNetRuntime` static class, for example:
|
||||
|
||||
```csharp
|
||||
await browserWindow.WebContents
|
||||
.LoadURLAsync($"http://localhost:{ElectronNetRuntime.AspNetWebPort}/mypage.html");
|
||||
```
|
||||
|
||||
### 4. Alternative: IWebHostBuilder Setup
|
||||
|
||||
For projects using the traditional `Startup.cs` pattern:
|
||||
For projects using the traditional `Startup.cs` pattern, please see "Traditional ASP.NET Core" in the [Migration Guide](../Core/Migration-Guide.md).
|
||||
|
||||
```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
|
||||
|
||||
@@ -183,8 +98,8 @@ var settingsWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
|
||||
## 💡 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
|
||||
✅ **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
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
# Console Application Setup
|
||||
|
||||
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.
|
||||
A major benefit in ElectronNET.Core is the ability to build Electron applications using simple console applications instead of requiring ASP.NET Core. This removes a significant barrier and enables many more use cases.
|
||||
|
||||
## 🎯 What You Can Build
|
||||
|
||||
@@ -15,11 +15,8 @@ Console applications with ElectronNET.Core support multiple content scenarios:
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
See [System Requirements](../GettingStarted/System-Requirements.md).
|
||||
|
||||
- **.NET 8.0** or later
|
||||
- **Node.js 22.x** or later
|
||||
- **Visual Studio 2022** (recommended) or Visual Studio Code
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
@@ -38,7 +35,8 @@ cd MyElectronApp
|
||||
PM> Install-Package ElectronNET.Core
|
||||
```
|
||||
|
||||
> **Note**: The API package is automatically included as a dependency of `ElectronNET.Core`.
|
||||
> [!Note]
|
||||
> The API package is automatically included as a dependency of `ElectronNET.Core`.
|
||||
|
||||
### 3. Configure Project File
|
||||
|
||||
@@ -56,6 +54,11 @@ Add the Electron.NET configuration to your `.csproj` file:
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> Specifying `OutputType` property is crucial in order to get the ability of WSL debugging. Especially it is not included in ASP.NET projects.
|
||||
> When you migrate from ASP.NET to a console application, be sure to add this to the project file.
|
||||
|
||||
|
||||
### 4. Implement Basic Structure
|
||||
|
||||
Here's a complete console application example:
|
||||
@@ -66,55 +69,56 @@ using System.Threading.Tasks;
|
||||
using ElectronNET.API.Entities;
|
||||
|
||||
namespace MyElectronApp
|
||||
|
||||
public class Program
|
||||
{
|
||||
public class Program
|
||||
public static async Task Main(string[] args)
|
||||
{
|
||||
public static async Task Main(string[] args)
|
||||
var runtimeController = ElectronNetRuntime.RuntimeController;
|
||||
|
||||
try
|
||||
{
|
||||
var runtimeController = ElectronNetRuntime.RuntimeController;
|
||||
// Start Electron runtime
|
||||
await runtimeController.Start();
|
||||
await runtimeController.WaitReadyTask;
|
||||
|
||||
try
|
||||
{
|
||||
// Start Electron runtime
|
||||
await runtimeController.Start();
|
||||
await runtimeController.WaitReadyTask;
|
||||
// Initialize your Electron app
|
||||
await InitializeApp();
|
||||
|
||||
// Initialize your Electron app
|
||||
await InitializeApp();
|
||||
|
||||
// Wait for shutdown
|
||||
await runtimeController.WaitStoppedTask;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"Error: {ex.Message}");
|
||||
await runtimeController.Stop();
|
||||
await runtimeController.WaitStoppedTask.WaitAsync(TimeSpan.FromSeconds(2));
|
||||
}
|
||||
// Wait for shutdown
|
||||
await runtimeController.WaitStoppedTask.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static async Task InitializeApp()
|
||||
catch (Exception ex)
|
||||
{
|
||||
// Create main window
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
Console.WriteLine($"Error: {ex.Message}");
|
||||
await runtimeController.Stop().ConfigureAwait(false);
|
||||
await runtimeController.WaitStoppedTask.WaitAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
private static async Task InitializeApp()
|
||||
{
|
||||
// Create main window
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions
|
||||
{
|
||||
Show = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Show = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
// Add these two when using file:// URLs
|
||||
WebSecurity = false,
|
||||
AllowRunningInsecureContent = true,
|
||||
|
||||
// Load your content (file system, remote URL, etc.)
|
||||
await browserWindow.WebContents.LoadURLAsync("https://example.com");
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
|
||||
// Show window when ready
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
// Load your content (file system, remote URL, etc.)
|
||||
await browserWindow.WebContents.LoadURLAsync("https://example.com");
|
||||
|
||||
// Show window when ready
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -127,7 +131,11 @@ Serve HTML/JS files from your project:
|
||||
|
||||
```csharp
|
||||
// In your project root, create wwwroot/index.html
|
||||
await browserWindow.WebContents.LoadFileAsync("wwwroot/index.html");
|
||||
var fileInfo = new FileInfo(Environment.ProcessPath);
|
||||
var exeFolder = fileInfo.DirectoryName;
|
||||
var htmlPath = Path.Combine(exeFolder, "wwwroot/index.html");
|
||||
var url = new Uri(htmlPath, UriKind.Absolute);
|
||||
await browserWindow.WebContents.LoadFileAsync(url.ToString());
|
||||
```
|
||||
|
||||
### Remote Content
|
||||
@@ -138,80 +146,17 @@ Load content from any web server:
|
||||
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
|
||||
- **[Debugging](../Using/Debugging.md)** - Learn about debugging console applications
|
||||
- **[Package Building](../Using/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
|
||||
✅ **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,321 +0,0 @@
|
||||
# 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: 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"?>
|
||||
<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)
|
||||
|
||||
```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)
|
||||
|
||||
```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)
|
||||
|
||||
```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
|
||||
53
docs/GettingStarted/System-Requirements.md
Normal file
53
docs/GettingStarted/System-Requirements.md
Normal file
@@ -0,0 +1,53 @@
|
||||
|
||||
## 🛠 System Requirements
|
||||
|
||||
### Required Software
|
||||
|
||||
- **.NET 8.0** or later
|
||||
- **Node.js 22.x** or later (see below)
|
||||
- **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+)
|
||||
|
||||
> [!Note]
|
||||
> For Linux development on Windows, install [WSL2](https://docs.microsoft.com/windows/wsl/install) to build and debug Linux packages.
|
||||
> Do not forget to install NodeJS 22.x (LTS) on WSL.
|
||||
> Visual Studio will automatically install .NET when debugging on WSL. In all other cases you will need to install a matching .NET SDK on WSL as well.
|
||||
|
||||
|
||||
### NodeJS Installation
|
||||
|
||||
|
||||
ElectronNET.Core requires Node.js 22.x. Update your installation:
|
||||
|
||||
**Windows:**
|
||||
|
||||
1. Download from [nodejs.org](https://nodejs.org)
|
||||
2. Run the installer
|
||||
3. Verify: `node --version` should show v22.x.x
|
||||
|
||||
**Linux:**
|
||||
|
||||
```bash
|
||||
# Using Node Version Manager (recommended)
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install 22
|
||||
nvm use 22
|
||||
|
||||
# Or using package manager
|
||||
sudo apt update
|
||||
sudo apt install nodejs=22.*
|
||||
```
|
||||
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Debugging](../Using/Debugging.md)** - Learn about ASP.NET debugging features
|
||||
- **[Package Building](../Using/Package-Building.md)** - Create distributable packages
|
||||
- **[Startup Methods](../Using/Startup-Methods.md)** - Understanding launch scenarios
|
||||
|
||||
@@ -28,8 +28,8 @@ Electron.NET Core is a complete modernization of Electron.NET that eliminates th
|
||||
- **[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
|
||||
### [Release Information](RelInfo/Package-Description.md)
|
||||
- **[Package Description](RelInfo/Package-Description.md)** - Understanding the three NuGet packages
|
||||
- **[Changelog](../Changelog.md)** - Complete list of changes and improvements
|
||||
|
||||
## 🛠 System Requirements
|
||||
|
||||
@@ -47,7 +47,7 @@ ElectronNET.Core consists of three specialized NuGet packages designed for diffe
|
||||
## 🏗 Architecture Benefits
|
||||
|
||||
### Separation of Concerns
|
||||
- **Build logic separate from API** - Cleaner dependency management
|
||||
- **Build logic separate from API** - Clean dependency management
|
||||
- **Optional ASP.NET integration** - Use only what you need
|
||||
- **Multi-project friendly** - Share APIs across projects without build conflicts
|
||||
|
||||
@@ -68,7 +68,7 @@ ElectronNET.Core consists of three specialized NuGet packages designed for diffe
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
**Multi-Project Solution:**
|
||||
**Multi-Project Solution (ASP.NET):**
|
||||
```xml
|
||||
<!-- Startup project -->
|
||||
<ItemGroup>
|
||||
@@ -82,21 +82,35 @@ ElectronNET.Core consists of three specialized NuGet packages designed for diffe
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
**Multi-Project Solution (Console):**
|
||||
```xml
|
||||
<!-- Startup project -->
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ElectronNET.Core" 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.AspNet → ElectronNET.Core.Api
|
||||
|
||||
ElectronNET.Core → ElectronNET.Core.Api
|
||||
```
|
||||
|
||||
- **ElectronNET.Core.AspNet** depends on ElectronNET.Core
|
||||
- **ElectronNET.Core.AspNet** depends on ElectronNET.Core.Api
|
||||
- **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
|
||||
✅ **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
|
||||
|
||||
|
||||
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
|
||||
|
||||
@@ -18,7 +18,7 @@ Debug your .NET code directly with full Hot Reload support:
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
},
|
||||
"applicationUrl": "https://localhost:7001/"
|
||||
"applicationUrl": "http://localhost:8001/"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -64,10 +64,10 @@ Debug Linux builds directly from Windows Visual Studio:
|
||||
"profiles": {
|
||||
"WSL": {
|
||||
"commandName": "WSL2",
|
||||
"launchUrl": "http://localhost:7001/",
|
||||
"launchUrl": "http://localhost:8001/",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development",
|
||||
"ASPNETCORE_URLS": "http://localhost:7001/"
|
||||
"ASPNETCORE_URLS": "http://localhost:8001/"
|
||||
},
|
||||
"distributionName": ""
|
||||
}
|
||||
@@ -94,7 +94,7 @@ Add the debugging profiles to `Properties/launchSettings.json`:
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
},
|
||||
"applicationUrl": "https://localhost:7001/"
|
||||
"applicationUrl": "http://localhost:8001/"
|
||||
},
|
||||
"Electron (unpackaged)": {
|
||||
"commandName": "Executable",
|
||||
@@ -107,10 +107,10 @@ Add the debugging profiles to `Properties/launchSettings.json`:
|
||||
},
|
||||
"WSL": {
|
||||
"commandName": "WSL2",
|
||||
"launchUrl": "http://localhost:7001/",
|
||||
"launchUrl": "http://localhost:8001/",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development",
|
||||
"ASPNETCORE_URLS": "http://localhost:7001/"
|
||||
"ASPNETCORE_URLS": "http://localhost:8001/"
|
||||
},
|
||||
"distributionName": ""
|
||||
}
|
||||
@@ -229,8 +229,8 @@ The debugging interface provides familiar Visual Studio tools:
|
||||
|
||||
## 💡 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
|
||||
✅ **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
|
||||
@@ -14,13 +14,13 @@ The framework supports **8 different launch scenarios** covering every combinati
|
||||
|
||||
### Unpackaged Debugging Modes
|
||||
|
||||
**`-unpackedelectron`** - Electron-first debugging
|
||||
#### **`-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
|
||||
#### **`-unpackeddotnet`** - .NET-first debugging
|
||||
```bash
|
||||
# Launch .NET first, which then starts Electron
|
||||
dotnet run -unpackeddotnet
|
||||
@@ -28,13 +28,13 @@ dotnet run -unpackeddotnet
|
||||
|
||||
### Packaged Deployment Modes
|
||||
|
||||
**`-dotnetpacked`** - .NET-first packaged execution
|
||||
#### **`-dotnetpacked`** - .NET-first packaged execution
|
||||
```bash
|
||||
# Run packaged app with .NET starting first
|
||||
MyApp.exe -dotnetpacked
|
||||
```
|
||||
|
||||
**No flags** - Electron-first packaged execution (default)
|
||||
#### **No flags** - Electron-first packaged execution (default)
|
||||
```bash
|
||||
# Run packaged app with Electron starting first
|
||||
MyApp.exe
|
||||
@@ -92,7 +92,7 @@ builder.WebHost.UseElectron(args, async () =>
|
||||
var browserWindow = await Electron.WindowManager.CreateWindowAsync(
|
||||
new BrowserWindowOptions { Show = false });
|
||||
|
||||
await browserWindow.WebContents.LoadURLAsync("https://localhost:7001");
|
||||
await browserWindow.WebContents.LoadURLAsync("http://localhost:8001");
|
||||
browserWindow.OnReadyToShow += () => browserWindow.Show();
|
||||
});
|
||||
|
||||
@@ -119,7 +119,8 @@ public static async Task Main(string[] args)
|
||||
|
||||
## 🎨 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.
|
||||
|
||||
@@ -153,6 +154,7 @@ The image above illustrates how each combination of deployment type, application
|
||||
### Production Deployment
|
||||
|
||||
**Dotnet-First Deployment**
|
||||
|
||||
```bash
|
||||
# Build and package
|
||||
dotnet publish -c Release -r win-x64
|
||||
@@ -165,6 +167,7 @@ MyApp.exe -dotnetpacked
|
||||
```
|
||||
|
||||
**Electron-First Deployment** (Default)
|
||||
|
||||
```bash
|
||||
# Run packaged application (no special flags needed)
|
||||
MyApp.exe
|
||||
@@ -8,16 +8,20 @@
|
||||
|
||||
- [What's new?](Core/What's-New.md)
|
||||
- [Migration Guiide](Core/Migration-Guide.md)
|
||||
- [Advcanced Migration](Core/Advanced-Migration-Topics.md)
|
||||
- [Advanced Migration](Core/Advanced-Migration-Topics.md)
|
||||
|
||||
# Getting Started
|
||||
|
||||
- [System Requirements](GettingStarted/System-Requirements.md)
|
||||
- [With ASP.Net](GettingStarted/ASP.Net.md)
|
||||
- [With a Console App](GettingStarted/Console-App.md)
|
||||
- [Startup-Method](GettingStarted/Startup-Methods.md)
|
||||
- [Debugging](GettingStarted/Debugging.md)
|
||||
- [Package Building](GettingStarted/Package-Building.md)
|
||||
|
||||
# Using Electron.NET
|
||||
|
||||
- [Configuration](Using/Configuration.md)
|
||||
- [Startup-Methods](Using/Startup-Methods.md)
|
||||
- [Debugging](Using/Debugging.md)
|
||||
- [Package Building](Using/Package-Building.md)
|
||||
|
||||
|
||||
# Release Information
|
||||
|
||||
BIN
docs/images/app_designer1.png
Normal file
BIN
docs/images/app_designer1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
BIN
docs/images/app_designer2.png
Normal file
BIN
docs/images/app_designer2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Reference in New Issue
Block a user