Skip to content

Commit 6b8d0ef

Browse files
softworkzsoftworkz
committed
Add documentation for migration checks
1 parent 453d0f0 commit 6b8d0ef

File tree

2 files changed

+236
-0
lines changed

2 files changed

+236
-0
lines changed

‎docs/Core/Migration-Checks.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# Migration Checks
2+
3+
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.
4+
5+
## Overview
6+
7+
When you build an Electron.NET project, the following validation checks are performed:
8+
9+
| Code | Check | Description |
10+
|------|-------|-------------|
11+
| [ELECTRON001](#1-packagejson-not-allowed) | package.json not allowed | Ensures no package.json exists outside ElectronHostHook |
12+
| [ELECTRON002](#2-electron-manifestjson-not-allowed) | electron-manifest.json not allowed | Detects deprecated manifest files |
13+
| [ELECTRON003](#3-electron-builderjson-location) | electron-builder.json location | Verifies electron-builder.json exists in Properties folder |
14+
| [ELECTRON004](#3-electron-builderjson-location) | electron-builder.json wrong location | Warns if electron-builder.json is found in incorrect locations |
15+
| [ELECTRON005](#4-parent-paths-not-allowed-in-electron-builderjson) | Parent paths not allowed | Checks for `..` references in config |
16+
| [ELECTRON006](#5-publish-profile-validation) | Publish profile validation | Validates pubxml configuration |
17+
18+
---
19+
20+
## 1. package.json not allowed
21+
22+
**Warning Code:** `ELECTRON001`
23+
24+
### What is checked
25+
26+
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).
27+
28+
### Why this matters
29+
30+
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.
31+
32+
### Exception
33+
34+
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.
35+
36+
### How to fix
37+
38+
1. **Open your project's `.csproj` file**
39+
2. **Add the required properties** to a PropertyGroup with the label `ElectronNetCommon`:
40+
41+
```xml
42+
<PropertyGroup Label="ElectronNetCommon">
43+
<PackageId>my-electron-app</PackageId>
44+
<Title>My Electron App</Title>
45+
<Version>1.0.0</Version>
46+
<Description>My awesome Electron.NET application</Description>
47+
<Company>My Company</Company>
48+
<Copyright>Copyright © 2025</Copyright>
49+
<ElectronVersion>30.0.9</ElectronVersion>
50+
</PropertyGroup>
51+
```
52+
53+
3. **Delete the old `package.json`** file from your project root
54+
55+
> **See also:** [Migration Guide](Migration-Guide.md) for complete migration instructions.
56+
57+
---
58+
59+
## 2. electron-manifest.json not allowed
60+
61+
**Warning Code:** `ELECTRON002`
62+
63+
### What is checked
64+
65+
The build system checks for the presence of `electron.manifest.json` or `electron-manifest.json` files in your project.
66+
67+
### Why this matters
68+
69+
The `electron.manifest.json` file format is deprecated. All configuration should now be specified using:
70+
- MSBuild properties in your `.csproj` file (for application metadata)
71+
- The `electron-builder.json` file in the `Properties` folder (for build configuration)
72+
73+
### How to fix
74+
75+
1. **Migrate application properties** to your `.csproj` file (see [Migration Guide](Migration-Guide.md))
76+
2. **Move the `build` section** from `electron.manifest.json` to `Properties/electron-builder.json`
77+
3. **Delete the old `electron.manifest.json`** file
78+
79+
**Example electron-builder.json:**
80+
```json
81+
{
82+
"compression": "maximum",
83+
"win": {
84+
"icon": "Assets/app.ico",
85+
"target": ["nsis", "portable"]
86+
},
87+
"linux": {
88+
"icon": "Assets/app.png",
89+
"target": ["AppImage", "deb"]
90+
},
91+
"mac": {
92+
"icon": "Assets/app.icns",
93+
"target": ["dmg", "zip"]
94+
}
95+
}
96+
```
97+
98+
---
99+
100+
## 3. electron-builder.json Location
101+
102+
**Warning Codes:** `ELECTRON003`, `ELECTRON004`
103+
104+
### What is checked
105+
106+
- `ELECTRON003`: Verifies that an `electron-builder.json` file exists in the `Properties` folder
107+
- `ELECTRON004`: Warns if `electron-builder.json` is found in incorrect locations
108+
109+
### Why this matters
110+
111+
The `electron-builder.json` file must be located in the `Properties` folder so it can be properly copied to the output directory during publishing.
112+
113+
### How to fix
114+
115+
1. **Create the Properties folder** if it doesn't exist
116+
2. **Move or create** `electron-builder.json` in `Properties/electron-builder.json`
117+
3. **Remove** any `electron-builder.json` files from other locations
118+
119+
**Expected structure:**
120+
```
121+
MyProject/
122+
├── Properties/
123+
│ ├── electron-builder.json ✅ Correct location
124+
│ ├── launchSettings.json
125+
│ └── PublishProfiles/
126+
├── MyProject.csproj
127+
└── Program.cs
128+
```
129+
130+
---
131+
132+
## 4. Parent paths not allowed in electron-builder.json
133+
134+
**Warning Code:** `ELECTRON005`
135+
136+
### What is checked
137+
138+
The build system scans the `electron-builder.json` file for parent-path references (`..`).
139+
140+
### Why this matters
141+
142+
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.
143+
144+
### How to fix
145+
146+
1. **Move resource files** (icons, installers, etc.) inside your project folder structure
147+
2. **Configure the files** to be copied to the output directory in your `.csproj`:
148+
149+
```xml
150+
<ItemGroup>
151+
<Content Include="Assets\**\*">
152+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
153+
</Content>
154+
</ItemGroup>
155+
```
156+
157+
3. **Update paths** in `electron-builder.json` to use relative paths without `..`:
158+
159+
**Before (incorrect):**
160+
```json
161+
{
162+
"win": {
163+
"icon": "../SharedAssets/app.ico"
164+
}
165+
}
166+
```
167+
168+
**After (correct):**
169+
```json
170+
{
171+
"win": {
172+
"icon": "Assets/app.ico"
173+
}
174+
}
175+
```
176+
177+
---
178+
179+
## 5. Publish Profile Validation
180+
181+
**Warning Code:** `ELECTRON006`
182+
183+
### What is checked
184+
185+
The build system examines `.pubxml` files in the `Properties/PublishProfiles` folder and checks for `WebPublishMethod` and `ProjectGuid` properties, which indicate ASP.NET-style publish profiles.
186+
187+
### Why this matters
188+
189+
Electron.NET uses a special publish process that packages your application with Electron. Standard ASP.NET publish profiles may not work correctly and can lead to incomplete or broken builds.
190+
191+
### How to fix
192+
193+
1. **Delete existing publish profiles** from `Properties/PublishProfiles/`
194+
2. **Create new publish profiles** using the Visual Studio Publishing Wizard:
195+
- Right-click on the project in Solution Explorer
196+
- Select **Publish...**
197+
- Follow the wizard to create a **Folder** publish profile
198+
199+
**Correct publish profile example:**
200+
```xml
201+
<?xml version="1.0" encoding="utf-8"?>
202+
<Project>
203+
<PropertyGroup>
204+
<PublishUrl>publish\</PublishUrl>
205+
<PublishDir>publish\</PublishDir>
206+
<SelfContained>true</SelfContained>
207+
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
208+
<PublishSingleFile>false</PublishSingleFile>
209+
</PropertyGroup>
210+
</Project>
211+
```
212+
213+
---
214+
215+
## Disabling Migration Checks
216+
217+
If you need to disable specific migration checks (not recommended), you can set the following properties in your `.csproj` file:
218+
219+
```xml
220+
<PropertyGroup>
221+
<!-- Disable all migration checks -->
222+
<ElectronSkipMigrationChecks>true</ElectronSkipMigrationChecks>
223+
</PropertyGroup>
224+
```
225+
226+
> ⚠️ **Warning:** Disabling migration checks may result in build or runtime errors. Only disable checks if you fully understand the implications.
227+
228+
---
229+
230+
## See Also
231+
232+
- [Migration Guide](Migration-Guide.md) - Complete step-by-step migration instructions
233+
- [Advanced Migration Topics](Advanced-Migration-Topics.md) - Complex migration scenarios
234+
- [Configuration](../Using/Configuration.md) - Project configuration options
235+
- [Package Building](../Using/Package-Building.md) - Building distributable packages

‎docs/_Sidebar.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
- [What's new?](Core/What's-New.md)
1111
- [Migration Guide](Core/Migration-Guide.md)
12+
- [Migration Checks](Core/Migration-Checks.md)
1213
- [Advanced Migration](Core/Advanced-Migration-Topics.md)
1314

1415
# Getting Started

0 commit comments

Comments
 (0)