Skip to content

Commit a4f1e0a

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

File tree

3 files changed

+295
-33
lines changed

3 files changed

+295
-33
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

‎src/ElectronNET/build/ElectronNET.MigrationChecks.targets‎

Lines changed: 59 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@
1414
<!-- Main migration checks target that runs before build -->
1515
<Target Name="ElectronMigrationChecks"
1616
BeforeTargets="BeforeBuild"
17-
DependsOnTargets="$(ElectronMigrationChecksDependsOn)">
17+
DependsOnTargets="$(ElectronMigrationChecksDependsOn)"
18+
Condition="'$(ElectronSkipMigrationChecks)' != 'true'">
1819
</Target>
1920

2021
<!--
@@ -164,7 +165,7 @@ Move the electron-builder.json file to: $(MSBuildProjectDirectory)\Properties\el
164165
<PropertyGroup>
165166
<_ElectronBuilderJsonContent>@(_ElectronBuilderJsonLines, ' ')</_ElectronBuilderJsonContent>
166167
<_HasParentPathReference>false</_HasParentPathReference>
167-
<_HasParentPathReference Condition="$(_ElectronBuilderJsonContent.Contains('..'))" >true</_HasParentPathReference>
168+
<_HasParentPathReference Condition="$(_ElectronBuilderJsonContent.Contains('../')) OR $(_ElectronBuilderJsonContent.Contains('..\\'))" >true</_HasParentPathReference>
168169
</PropertyGroup>
169170

170171
<Warning Condition="'$(_HasParentPathReference)' == 'true'"
@@ -194,6 +195,10 @@ For more information, see: https://github.com/ElectronNET/Electron.NET/wiki/Migr
194195

195196
<!--
196197
Check 5: Pubxml files match the project type
198+
199+
This check validates that publish profiles are appropriate for the project type:
200+
- ASP.NET projects (using Microsoft.NET.Sdk.Web) should have WebPublishMethod in their pubxml files
201+
- Console/other projects should NOT have WebPublishMethod or ProjectGuid in their pubxml files
197202
-->
198203
<Target Name="ElectronCheckPubxmlFiles">
199204

@@ -202,50 +207,71 @@ For more information, see: https://github.com/ElectronNET/Electron.NET/wiki/Migr
202207
<_PubxmlFiles Include="$(MSBuildProjectDirectory)\Properties\PublishProfiles\*.pubxml" />
203208
</ItemGroup>
204209

205-
<!-- Read content of pubxml files to check for WebPublishMethod and ProjectGuid -->
206-
<XmlPeek XmlInputPath="%(_PubxmlFiles.Identity)"
207-
Query="/Project/PropertyGroup/WebPublishMethod/text()"
208-
Condition="@(_PubxmlFiles->Count()) > 0">
209-
<Output TaskParameter="Result" ItemName="_WebPublishMethodValues" />
210-
</XmlPeek>
211-
212-
<XmlPeek XmlInputPath="%(_PubxmlFiles.Identity)"
213-
Query="/Project/PropertyGroup/ProjectGuid/text()"
214-
Condition="@(_PubxmlFiles->Count()) > 0">
215-
<Output TaskParameter="Result" ItemName="_ProjectGuidValues" />
216-
</XmlPeek>
217-
218-
<!-- Determine if pubxml is for ASP.NET (has WebPublishMethod or ProjectGuid) -->
210+
<!-- Determine if this is an ASP.NET project (UsingMicrosoftNETSdkWeb is set by the Web SDK) -->
219211
<PropertyGroup>
220-
<_HasAspNetPubxml>false</_HasAspNetPubxml>
221-
<_HasAspNetPubxml Condition="@(_WebPublishMethodValues->Count()) > 0 OR @(_ProjectGuidValues->Count()) > 0">true</_HasAspNetPubxml>
212+
<_IsAspNetProject>false</_IsAspNetProject>
213+
<_IsAspNetProject Condition="'$(UsingMicrosoftNETSdkWeb)' == 'true'">true</_IsAspNetProject>
214+
<_HasPubxmlFiles>false</_HasPubxmlFiles>
215+
<_HasPubxmlFiles Condition="@(_PubxmlFiles->Count()) > 0">true</_HasPubxmlFiles>
222216
</PropertyGroup>
223217

224-
<!-- Check if the project is using the Web SDK (ASP.NET) -->
225-
<PropertyGroup>
226-
<_IsWebProject>false</_IsWebProject>
227-
<_IsWebProject Condition="'$(UsingMicrosoftNETSdkWeb)' == 'true'">true</_IsWebProject>
228-
</PropertyGroup>
218+
<!-- Build a combined content string for each file and check (only if files exist) -->
219+
<ItemGroup Condition="'$(_HasPubxmlFiles)' == 'true'">
220+
<_PubxmlFileInfo Include="@(_PubxmlFiles)" Condition="'%(Identity)' != ''">
221+
<FileContent>$([System.IO.File]::ReadAllText('%(Identity)'))</FileContent>
222+
</_PubxmlFileInfo>
223+
</ItemGroup>
229224

230-
<!-- For Electron.NET projects, we need the correct pubxml format -->
231-
<Warning Condition="'$(_HasAspNetPubxml)' == 'true' AND @(_PubxmlFiles->Count()) > 0"
232-
Code="ELECTRON006"
233-
Text="The publish profile(s) appear to be configured for standard ASP.NET publishing (containing WebPublishMethod and/or ProjectGuid properties).
225+
<!-- Check each file for WebPublishMethod presence -->
226+
<ItemGroup Condition="'$(_HasPubxmlFiles)' == 'true'">
227+
<_PubxmlFileInfoWithFlags Include="@(_PubxmlFileInfo)" Condition="'%(Identity)' != ''">
228+
<HasWebPublishMethod>$([System.Text.RegularExpressions.Regex]::IsMatch('%(FileContent)', '&lt;WebPublishMethod&gt;'))</HasWebPublishMethod>
229+
</_PubxmlFileInfoWithFlags>
230+
</ItemGroup>
234231

235-
Pubxml files found:
236-
@(_PubxmlFiles, '%0A')
232+
<!-- For ASP.NET projects: find pubxml files MISSING WebPublishMethod -->
233+
<ItemGroup>
234+
<_AspNetMissingWebPublishMethod Include="@(_PubxmlFileInfoWithFlags)"
235+
Condition="'$(_IsAspNetProject)' == 'true' AND '%(HasWebPublishMethod)' == 'False'" />
236+
</ItemGroup>
237+
238+
<!-- For Console/Non-ASP.NET projects: find pubxml files that HAVE WebPublishMethod -->
239+
<ItemGroup>
240+
<_ConsolePubxmlWithAspNetProperties Include="@(_PubxmlFileInfoWithFlags)"
241+
Condition="'$(_IsAspNetProject)' != 'true' AND '%(HasWebPublishMethod)' == 'True'" />
242+
</ItemGroup>
243+
244+
<!-- Warning for ASP.NET projects with incorrect pubxml files -->
245+
<Warning
246+
Condition="'@(_AspNetMissingWebPublishMethod)' != ''"
247+
Code="ELECTRON006"
248+
Text="The publish profile '%(_AspNetMissingWebPublishMethod.Identity)' appears to be configured for a console application (missing WebPublishMethod property), but this is an ASP.NET project.
249+
250+
RECOMMENDED ACTION:
251+
1. Delete the existing publish profiles
252+
2. Use the Visual Studio Publishing Wizard to create a new profile:
253+
- Right-click on the project in Solution Explorer
254+
- Select 'Publish...'
255+
- Follow the wizard to create a Folder publish profile for ASP.NET
256+
257+
Note: ASP.NET Electron.NET projects require publish profiles with WebPublishMethod set to FileSystem.
258+
259+
For more information, see: https://github.com/ElectronNET/Electron.NET/wiki/Migration-Checks#5-publish-profile-validation" />
237260

238-
For Electron.NET projects, the publish profiles need to be configured correctly.
261+
<!-- Warning for Console projects with incorrect pubxml files -->
262+
<Warning
263+
Condition="'@(_ConsolePubxmlWithAspNetProperties)' != ''"
264+
Code="ELECTRON007"
265+
Text="The publish profile '%(_ConsolePubxmlWithAspNetProperties.Identity)' appears to be configured for ASP.NET publishing (containing WebPublishMethod and/or ProjectGuid properties), but this is a console application project.
239266
240267
RECOMMENDED ACTION:
241268
1. Delete the existing publish profiles
242269
2. Use the Visual Studio Publishing Wizard to create a new profile:
243270
- Right-click on the project in Solution Explorer
244271
- Select 'Publish...'
245-
- Follow the wizard to create a Folder publish profile for Electron.NET
272+
- Follow the wizard to create a Folder publish profile for console applications
246273
247-
Note: Electron.NET uses a special publish process that packages your app with Electron.
248-
Standard ASP.NET publish profiles may not work correctly.
274+
Note: Console Electron.NET projects should not use ASP.NET-style publish profiles.
249275
250276
For more information, see: https://github.com/ElectronNET/Electron.NET/wiki/Migration-Checks#5-publish-profile-validation" />
251277

0 commit comments

Comments
 (0)