Skip to content

Commit 2c82206

Browse files
FlorianRapplFlorianRappl
authored
Merge pull request #966 from softworkz/submit_migrationchecks
Add migration checks
2 parents 44a820e + d0eb088 commit 2c82206

File tree

5 files changed

+531
-6
lines changed

5 files changed

+531
-6
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) | ASP.NET publish profile mismatch | Warns when ASP.NET projects have console-style profiles |
17+
| [ELECTRON007](#5-publish-profile-validation) | Console publish profile mismatch | Warns when console projects have ASP.NET-style profiles |
18+
19+
---
20+
21+
## 1. package.json not allowed
22+
23+
**Warning Code:** `ELECTRON001`
24+
25+
### What is checked
26+
27+
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).
28+
29+
### Why this matters
30+
31+
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.
32+
33+
### Exception
34+
35+
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.
36+
37+
### How to fix
38+
39+
1. **Open your project's `.csproj` file**
40+
2. **Add the required properties** to a PropertyGroup with the label `ElectronNetCommon`:
41+
42+
```xml
43+
<PropertyGroup Label="ElectronNetCommon">
44+
<PackageId>my-electron-app</PackageId>
45+
<Title>My Electron App</Title>
46+
<Version>1.0.0</Version>
47+
<Description>My awesome Electron.NET application</Description>
48+
<Company>My Company</Company>
49+
<Copyright>Copyright © 2025</Copyright>
50+
<ElectronVersion>30.0.9</ElectronVersion>
51+
</PropertyGroup>
52+
```
53+
54+
3. **Delete the old `package.json`** file from your project root
55+
56+
> **See also:** [Migration Guide](Migration-Guide.md) for complete migration instructions.
57+
58+
---
59+
60+
## 2. electron-manifest.json not allowed
61+
62+
**Warning Code:** `ELECTRON002`
63+
64+
### What is checked
65+
66+
The build system checks for the presence of `electron.manifest.json` or `electron-manifest.json` files in your project.
67+
68+
### Why this matters
69+
70+
The `electron.manifest.json` file format is deprecated. All configuration should now be specified using:
71+
- MSBuild properties in your `.csproj` file (for application metadata)
72+
- The `electron-builder.json` file in the `Properties` folder (for build configuration)
73+
74+
### How to fix
75+
76+
1. **Migrate application properties** to your `.csproj` file (see [Migration Guide](Migration-Guide.md))
77+
2. **Move the `build` section** from `electron.manifest.json` to `Properties/electron-builder.json`
78+
3. **Delete the old `electron.manifest.json`** file
79+
80+
**Example electron-builder.json:**
81+
```json
82+
{
83+
"compression": "maximum",
84+
"win": {
85+
"icon": "Assets/app.ico",
86+
"target": ["nsis", "portable"]
87+
},
88+
"linux": {
89+
"icon": "Assets/app.png",
90+
"target": ["AppImage", "deb"]
91+
},
92+
"mac": {
93+
"icon": "Assets/app.icns",
94+
"target": ["dmg", "zip"]
95+
}
96+
}
97+
```
98+
99+
---
100+
101+
## 3. electron-builder.json Location
102+
103+
**Warning Codes:** `ELECTRON003`, `ELECTRON004`
104+
105+
### What is checked
106+
107+
- `ELECTRON003`: Verifies that an `electron-builder.json` file exists in the `Properties` folder
108+
- `ELECTRON004`: Warns if `electron-builder.json` is found in incorrect locations
109+
110+
### Why this matters
111+
112+
The `electron-builder.json` file must be located in the `Properties` folder so it can be properly copied to the output directory during publishing.
113+
114+
### How to fix
115+
116+
1. **Create the Properties folder** if it doesn't exist
117+
2. **Move or create** `electron-builder.json` in `Properties/electron-builder.json`
118+
3. **Remove** any `electron-builder.json` files from other locations
119+
120+
**Expected structure:**
121+
```
122+
MyProject/
123+
├── Properties/
124+
│ ├── electron-builder.json ✅ Correct location
125+
│ ├── launchSettings.json
126+
│ └── PublishProfiles/
127+
├── MyProject.csproj
128+
└── Program.cs
129+
```
130+
131+
---
132+
133+
## 4. Parent paths not allowed in electron-builder.json
134+
135+
**Warning Code:** `ELECTRON005`
136+
137+
### What is checked
138+
139+
The build system scans the `electron-builder.json` file for parent-path references (`..`).
140+
141+
### Why this matters
142+
143+
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.
144+
145+
### How to fix
146+
147+
1. **Move resource files** (icons, installers, etc.) inside your project folder structure
148+
2. **Configure the files** to be copied to the output directory in your `.csproj`:
149+
150+
```xml
151+
<ItemGroup>
152+
<Content Include="Assets\**\*">
153+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
154+
</Content>
155+
</ItemGroup>
156+
```
157+
158+
3. **Update paths** in `electron-builder.json` to use relative paths without `..`:
159+
160+
**Before (incorrect):**
161+
```json
162+
{
163+
"win": {
164+
"icon": "../SharedAssets/app.ico"
165+
}
166+
}
167+
```
168+
169+
**After (correct):**
170+
```json
171+
{
172+
"win": {
173+
"icon": "Assets/app.ico"
174+
}
175+
}
176+
```
177+
178+
---
179+
180+
## 5. Publish Profile Validation
181+
182+
**Warning Codes:** `ELECTRON006`, `ELECTRON007`
183+
184+
### What is checked
185+
186+
The build system examines `.pubxml` files in the `Properties/PublishProfiles` folder and validates that they match the project type:
187+
188+
- **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.
189+
190+
- **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.
191+
192+
### Why this matters
193+
194+
Electron.NET supports both ASP.NET and console application project types, each requiring different publish profile configurations:
195+
196+
| Project Type | SDK | Expected Properties |
197+
|--------------|-----|---------------------|
198+
| ASP.NET (Razor Pages, MVC, Blazor) | `Microsoft.NET.Sdk.Web` | `WebPublishMethod`, no `PublishProtocol` |
199+
| Console Application | `Microsoft.NET.Sdk` | `PublishProtocol`, no `WebPublishMethod` |
200+
201+
Using the wrong publish profile type can lead to incomplete or broken builds.
202+
203+
### How to fix
204+
205+
1. **Delete existing publish profiles** from `Properties/PublishProfiles/`
206+
2. **Create new publish profiles** using the Visual Studio Publishing Wizard:
207+
- Right-click on the project in Solution Explorer
208+
- Select **Publish...**
209+
- Follow the wizard to create a **Folder** publish profile
210+
211+
For correct publish profile examples for both ASP.NET and Console applications, see **[Package Building](../Using/Package-Building.md#step-1-create-publish-profiles)**.
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/Using/Package-Building.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,15 @@ Add publish profiles to `Properties/PublishProfiles/`:
2626
<PropertyGroup>
2727
<Configuration>Release</Configuration>
2828
<Platform>Any CPU</Platform>
29-
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
30-
<PublishProtocol>FileSystem</PublishProtocol>
29+
<DeleteExistingFiles>true</DeleteExistingFiles>
30+
<PublishProvider>FileSystem</PublishProvider>
31+
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
32+
<WebPublishMethod>FileSystem</WebPublishMethod>
33+
<_TargetId>Folder</_TargetId>
3134
<TargetFramework>net10.0</TargetFramework>
3235
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
36+
<ProjectGuid>48eff821-2f4d-60cc-aa44-be0f1d6e5f35</ProjectGuid>
3337
<SelfContained>true</SelfContained>
34-
<PublishSingleFile>false</PublishSingleFile>
3538
</PropertyGroup>
3639
</Project>
3740
```
@@ -46,12 +49,15 @@ Add publish profiles to `Properties/PublishProfiles/`:
4649
<PropertyGroup>
4750
<Configuration>Release</Configuration>
4851
<Platform>Any CPU</Platform>
49-
<PublishDir>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishDir>
50-
<PublishProtocol>FileSystem</PublishProtocol>
52+
<DeleteExistingFiles>true</DeleteExistingFiles>
53+
<PublishProvider>FileSystem</PublishProvider>
54+
<PublishUrl>publish\$(Configuration)\$(TargetFramework)\$(RuntimeIdentifier)\</PublishUrl>
55+
<WebPublishMethod>FileSystem</WebPublishMethod>
56+
<_TargetId>Folder</_TargetId>
5157
<TargetFramework>net10.0</TargetFramework>
5258
<RuntimeIdentifier>linux-x64</RuntimeIdentifier>
59+
<ProjectGuid>48eff821-2f4d-60cc-aa44-be0f1d6e5f35</ProjectGuid>
5360
<SelfContained>true</SelfContained>
54-
<PublishSingleFile>false</PublishSingleFile>
5561
</PropertyGroup>
5662
</Project>
5763
```

‎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

‎src/ElectronNET/build/ElectronNET.Core.targets‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,7 @@
2323
<AssemblyMetadata Include="IsAspNet" Value="$(_IsMsAspNetProject)" />
2424
</ItemGroup>
2525

26+
<!-- Import migration validation checks -->
27+
<Import Project="$(MSBuildThisFileDirectory)ElectronNET.MigrationChecks.targets" />
28+
2629
</Project>

0 commit comments

Comments
 (0)