From f94ffb6df487c78a19d5d27eb53ed16d64084f21 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 14 Dec 2025 21:13:35 +0000 Subject: [PATCH] Update wiki bdfbcd5b7741da933771d1a1c380268f48f9ab41 --- Console-App.md | 2 +- Migration-Checks.md | 234 +++++++++++++++++++++++++++++++++++++++++++ Package-Building.md | 104 +++++++++++++++++-- RelInfo/Changelog.md | 22 ++++ _Sidebar.md | 1 + 5 files changed, 356 insertions(+), 7 deletions(-) create mode 100644 Migration-Checks.md diff --git a/Console-App.md b/Console-App.md index bf4bfa3..c3806b0 100644 --- a/Console-App.md +++ b/Console-App.md @@ -53,7 +53,7 @@ Add the Electron.NET configuration to your `.csproj` file: - + ``` diff --git a/Migration-Checks.md b/Migration-Checks.md new file mode 100644 index 0000000..c3d9153 --- /dev/null +++ b/Migration-Checks.md @@ -0,0 +1,234 @@ + +Electron.NET includes automatic build-time validation checks that help users migrating from previous versions avoid common configuration issues. These checks run automatically during the build process and provide helpful guidance when problems are detected. + +## Overview + +When you build an Electron.NET project, the following validation checks are performed: + +| Code | Check | Description | +|------|-------|-------------| +| [ELECTRON001](#1-packagejson-not-allowed) | package.json not allowed | Ensures no package.json exists outside ElectronHostHook | +| [ELECTRON002](#2-electron-manifestjson-not-allowed) | electron-manifest.json not allowed | Detects deprecated manifest files | +| [ELECTRON003](#3-electron-builderjson-location) | electron-builder.json location | Verifies electron-builder.json exists in Properties folder | +| [ELECTRON004](#3-electron-builderjson-location) | electron-builder.json wrong location | Warns if electron-builder.json is found in incorrect locations | +| [ELECTRON005](#4-parent-paths-not-allowed-in-electron-builderjson) | Parent paths not allowed | Checks for `..` references in config | +| [ELECTRON006](#5-publish-profile-validation) | ASP.NET publish profile mismatch | Warns when ASP.NET projects have console-style profiles | +| [ELECTRON007](#5-publish-profile-validation) | Console publish profile mismatch | Warns when console projects have ASP.NET-style profiles | + +--- + +## 1. package.json not allowed + +**Warning Code:** `ELECTRON001` + +### What is checked + +The build system scans for `package.json` and `package-lock.json` files in your project directory. These files should not exist in the project root or subdirectories (with one exception). + +### Why this matters + +In previous versions of Electron.NET, a `package.json` file was required in the project. The new version generates this file automatically from MSBuild properties defined in your `.csproj` file. + +### Exception + +A `package.json` file **is allowed** in the `ElectronHostHook` folder if you're using custom host hooks. This is the only valid location for a manually maintained package.json. + +### How to fix + +1. **Open your project's `.csproj` file** +2. **Add the required properties** to a PropertyGroup with the label `ElectronNetCommon`: + +```xml + + my-electron-app + My Electron App + 1.0.0 + My awesome Electron.NET application + My Company + Copyright © 2025 + 30.0.9 + +``` + +3. **Delete the old `package.json`** file from your project root + +> **See also:** [Migration Guide](Migration-Guide) for complete migration instructions. + +--- + +## 2. electron-manifest.json not allowed + +**Warning Code:** `ELECTRON002` + +### What is checked + +The build system checks for the presence of `electron.manifest.json` or `electron-manifest.json` files in your project. + +### Why this matters + +The `electron.manifest.json` file format is deprecated. All configuration should now be specified using: +- MSBuild properties in your `.csproj` file (for application metadata) +- The `electron-builder.json` file in the `Properties` folder (for build configuration) + +### How to fix + +1. **Migrate application properties** to your `.csproj` file (see [Migration Guide](Migration-Guide)) +2. **Move the `build` section** from `electron.manifest.json` to `Properties/electron-builder.json` +3. **Delete the old `electron.manifest.json`** file + +**Example electron-builder.json:** +```json +{ + "compression": "maximum", + "win": { + "icon": "Assets/app.ico", + "target": ["nsis", "portable"] + }, + "linux": { + "icon": "Assets/app.png", + "target": ["AppImage", "deb"] + }, + "mac": { + "icon": "Assets/app.icns", + "target": ["dmg", "zip"] + } +} +``` + +--- + +## 3. electron-builder.json Location + +**Warning Codes:** `ELECTRON003`, `ELECTRON004` + +### What is checked + +- `ELECTRON003`: Verifies that an `electron-builder.json` file exists in the `Properties` folder +- `ELECTRON004`: Warns if `electron-builder.json` is found in incorrect locations + +### Why this matters + +The `electron-builder.json` file must be located in the `Properties` folder so it can be properly copied to the output directory during publishing. + +### How to fix + +1. **Create the Properties folder** if it doesn't exist +2. **Move or create** `electron-builder.json` in `Properties/electron-builder.json` +3. **Remove** any `electron-builder.json` files from other locations + +**Expected structure:** +``` +MyProject/ +├── Properties/ +│ ├── electron-builder.json ✅ Correct location +│ ├── launchSettings.json +│ └── PublishProfiles/ +├── MyProject.csproj +└── Program.cs +``` + +--- + +## 4. Parent paths not allowed in electron-builder.json + +**Warning Code:** `ELECTRON005` + +### What is checked + +The build system scans the `electron-builder.json` file for parent-path references (`..`). + +### Why this matters + +During the publish process, the `electron-builder.json` file is copied to the build output directory. Any relative paths in this file are resolved from that location, not from your project directory. Parent-path references (`../`) will not work correctly because they would point outside the published application. + +### How to fix + +1. **Move resource files** (icons, installers, etc.) inside your project folder structure +2. **Configure the files** to be copied to the output directory in your `.csproj`: + +```xml + + + PreserveNewest + + +``` + +3. **Update paths** in `electron-builder.json` to use relative paths without `..`: + +**Before (incorrect):** +```json +{ + "win": { + "icon": "../SharedAssets/app.ico" + } +} +``` + +**After (correct):** +```json +{ + "win": { + "icon": "Assets/app.ico" + } +} +``` + +--- + +## 5. Publish Profile Validation + +**Warning Codes:** `ELECTRON006`, `ELECTRON007` + +### What is checked + +The build system examines `.pubxml` files in the `Properties/PublishProfiles` folder and validates that they match the project type: + +- **ELECTRON006**: For **ASP.NET projects** (using `Microsoft.NET.Sdk.Web`), checks that publish profiles include `WebPublishMethod`. This property is required for proper ASP.NET publishing. + +- **ELECTRON007**: For **console/other projects** (not using the Web SDK), checks that publish profiles do NOT include the `WebPublishMethod` property. These ASP.NET-specific properties are incorrect for non-web applications. + +### Why this matters + +Electron.NET supports both ASP.NET and console application project types, each requiring different publish profile configurations: + +| Project Type | SDK | Expected Properties | +|--------------|-----|---------------------| +| ASP.NET (Razor Pages, MVC, Blazor) | `Microsoft.NET.Sdk.Web` | `WebPublishMethod`, no `PublishProtocol` | +| Console Application | `Microsoft.NET.Sdk` | `PublishProtocol`, no `WebPublishMethod` | + +Using the wrong publish profile type can lead to incomplete or broken builds. + +### How to fix + +1. **Delete existing publish profiles** from `Properties/PublishProfiles/` +2. **Create new publish profiles** using the Visual Studio Publishing Wizard: + - Right-click on the project in Solution Explorer + - Select **Publish...** + - Follow the wizard to create a **Folder** publish profile + +For correct publish profile examples for both ASP.NET and Console applications, see **[Package Building](Package-Building#step-1-create-publish-profiles)**. + +--- + +## Disabling Migration Checks + +If you need to disable specific migration checks (not recommended), you can set the following properties in your `.csproj` file: + +```xml + + + true + +``` + +> ⚠️ **Warning:** Disabling migration checks may result in build or runtime errors. Only disable checks if you fully understand the implications. + +--- + +## See Also + +- [Migration Guide](Migration-Guide) - Complete step-by-step migration instructions +- [Advanced Migration Topics](Advanced-Migration-Topics) - Complex migration scenarios +- [Configuration](Configuration) - Project configuration options +- [Package Building](Package-Building) - Building distributable packages diff --git a/Package-Building.md b/Package-Building.md index 2b441cc..e90936b 100644 --- a/Package-Building.md +++ b/Package-Building.md @@ -25,12 +25,15 @@ Add publish profiles to `Properties/PublishProfiles/`: Release Any CPU - publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ - FileSystem + true + FileSystem + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + <_TargetId>Folder net10.0 win-x64 + 48eff821-2f4d-60cc-aa44-be0f1d6e5f35 true - false ``` @@ -45,12 +48,61 @@ Add publish profiles to `Properties/PublishProfiles/`: Release Any CPU - publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ - FileSystem + true + FileSystem + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + <_TargetId>Folder net10.0 linux-x64 + 48eff821-2f4d-60cc-aa44-be0f1d6e5f35 + true + + +``` + +#### ASP.NET Application Profile (macOS Apple Silicon ARM64) + +**osx-arm64.pubxml:** + +```xml + + + + Release + Any CPU + true + FileSystem + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + <_TargetId>Folder + net10.0 + osx-arm64 + 48eff821-2f4d-60cc-aa44-be0f1d6e5f35 + true + + +``` + +#### ASP.NET Application Profile (macOS Intel x64) + +**osx-x64.pubxml:** + +```xml + + + + Release + Any CPU + true + FileSystem + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + <_TargetId>Folder + net10.0 + osx-x64 + 48eff821-2f4d-60cc-aa44-be0f1d6e5f35 true - false ``` @@ -96,6 +148,46 @@ Add publish profiles to `Properties/PublishProfiles/`: ``` +#### Console Application Profile (macOS Apple Silicon ARM64) + +**osx-arm64.pubxml:** + +```xml + + + + Release + Any CPU + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + net10.0 + osx-arm64 + false + false + + +``` + +#### Console Application Profile (macOS Intel x64) + +**osx-x64.pubxml:** + +```xml + + + + Release + Any CPU + publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\ + FileSystem + net10.0 + osx-x64 + false + false + + +``` + ### Step 2: Configure Electron Builder ElectronNET.Core automatically adds a default `electron-builder.json` file under `Properties\electron-builder.json`. diff --git a/RelInfo/Changelog.md b/RelInfo/Changelog.md index 4293436..2859e7b 100644 --- a/RelInfo/Changelog.md +++ b/RelInfo/Changelog.md @@ -1,3 +1,25 @@ +# 0.3.0 + +## ElectronNET.Core + +- Updated infrastructure (#937, #939) @softworkz +- Updated all model classes to Electron API 39.2 (#949) @softworkz +- Fixed output path for `electron-builder` (#942) @softworkz +- Fixed floating point display resolution (#944) @softworkz +- Fixed error in case of missing electron-host-hook (#978) +- Fixed previous API break using exposed `JsonElement` objects (#938) @softworkz +- Fixed and improved several test cases (#962) @softworkz +- Fixed startup of Electron.NET from VS Code Debug Adapter (#952) +- Fixed the `BrowserWindowOptions` (#945) @softworkz +- Fixed example for `AutoMenuHide` to reflect platform capabilities (#982) @markatosi +- Added several migration checks for publishing (#966) @softworkz +- Added more test runners for E2E tests (#950, #951) @agracio +- Added dynamic updates for tray menu (#973) @davidroth +- Added matrix tests with 6 runners and 2 electron version (#948) @softworkz +- Added additional APIs for WebContents (#958) @agracio +- Added documentation for MacOS package publish (#983) @markatosi +- Added sample application for `ElectronHostHook` (#967) @adityashirsatrao007 + # 0.2.0 ## ElectronNET.Core diff --git a/_Sidebar.md b/_Sidebar.md index 558297a..d51e0a6 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -9,6 +9,7 @@ - [What's new?](What's-New) - [Migration Guide](Migration-Guide) +- [Migration Checks](Migration-Checks) - [Advanced Migration](Advanced-Migration-Topics)