build-windows-exe

Build Process

Phase 0: Update ImageEditor Submodule

cd 'ShareX Team\XerahS'
git submodule update --remote --merge ImageEditor

Phase 1: Pre-Build Cleanup

1. Kill all potential file-locking processes:
   powershell

   Get-Process | Where-Object { 
     $_.Name -like '*XerahS*' -or 
     $_.Name -like '*dotnet*' -or 
     $_.Name -like '*MSBuild*' -or 
     $_.Name -like '*VBCSCompiler*' 
   } | Stop-Process -Force -ErrorAction SilentlyContinue

2. Clean the solution:
   powershell

   cd 'ShareX Team\XerahS'
   dotnet clean src/desktop/XerahS.sln --nologo -c Release

3. If file locks persist, delete the problematic obj folder:
   powershell

   Remove-Item 'ShareX Team\XerahS\ImageEditor\src\ShareX.ImageEditor\obj' -Recurse -Force -ErrorAction SilentlyContinue

Phase 2: Initial Build Attempt

1. Run the packaging script:
   powershell

   cd 'ShareX Team\XerahS\build\windows'
   .\package-windows.ps1

2. Check for successful completion:
   • Script should complete with exit code 0
   • Both installers should be created in the

     dist

     folder

Phase 3: Handle File Lock Failures

• CS2012: Cannot open '...ShareX.ImageEditor.dll' for writing

• The process cannot access the file ... because it is being used by another process

• file may be locked by 'VBCSCompiler' or '.NET Host' or 'csc'

1. Kill compiler processes again:
   powershell

   Get-Process | Where-Object { 
     $_.Name -like '*VBCSCompiler*' -or 
     $_.Name -like '*dotnet*' -or 
     $_.Name -like '*csc*' 
   } | Stop-Process -Force -ErrorAction SilentlyContinue
   Start-Sleep -Seconds 2

2. Remove the locked obj folder:
   powershell

   Remove-Item 'ShareX Team\XerahS\ImageEditor\src\ShareX.ImageEditor\obj\Release' -Recurse -Force -ErrorAction SilentlyContinue

3. Pre-build the ImageEditor project separately with single-threaded compilation:
   powershell

   dotnet build 'ShareX Team\XerahS\ImageEditor\src\ShareX.ImageEditor\ShareX.ImageEditor.csproj' -c Release -p:UseSharedCompilation=false /m:1

   • The

     /m:1

     flag forces single-threaded build

   • UseSharedCompilation=false

     disables the VBCSCompiler server
4. Re-run the packaging script:
   powershell

   cd 'ShareX Team\XerahS\build\windows'
   .\package-windows.ps1

Phase 4: Fallback - Manual ARM64 Build

1. Clean and kill processes:
   powershell

   Get-Process | Where-Object { $_.Name -like '*VBCSCompiler*' -or $_.Name -like '*dotnet*' } | Stop-Process -Force -ErrorAction SilentlyContinue
   Remove-Item 'ShareX Team\XerahS\ImageEditor\src\ShareX.ImageEditor\obj\Release' -Recurse -Force -ErrorAction SilentlyContinue

2. Pre-build ImageEditor:
   powershell

   dotnet build 'ShareX Team\XerahS\ImageEditor\src\ShareX.ImageEditor\ShareX.ImageEditor.csproj' -c Release -p:UseSharedCompilation=false /m:1

3. Publish ARM64 manually:
   powershell

   $root = 'ShareX Team\XerahS'
   $project = "$root\src\desktop\app\XerahS.App\XerahS.App.csproj"
   $publishOutput = "$root\build\publish-temp-win-arm64"
   
   dotnet publish $project -c Release -p:OS=Windows_NT -r win-arm64 -p:PublishSingleFile=false -p:SkipBundlePlugins=true -p:UseSharedCompilation=false --self-contained true -o $publishOutput

4. Publish plugins:
   powershell

   $pluginsDir = "$publishOutput\Plugins"
   New-Item -ItemType Directory -Force -Path $pluginsDir | Out-Null
   
   Get-ChildItem "$root\src\desktop\plugins" -Filter "*.csproj" -Recurse | ForEach-Object {
     $pluginId = $_.BaseName
     $pluginJsonPath = Join-Path $_.Directory.FullName "plugin.json"
     if (Test-Path $pluginJsonPath) {
       $json = Get-Content $pluginJsonPath -Raw | ConvertFrom-Json
       if ($json.pluginId) { $pluginId = $json.pluginId }
     }
     Write-Host "Publishing plugin: $pluginId"
     dotnet publish $_.FullName -c Release -r win-arm64 -p:UseSharedCompilation=false --self-contained false -o "$pluginsDir\$pluginId"
   }

5. Run Inno Setup manually:
   powershell

   $isccPath = "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe"
   $issScript = "$root\build\windows\XerahS-setup.iss"
   $version = ([xml](Get-Content "$root\Directory.Build.props")).SelectSingleNode("//Version").InnerText.Trim()
   $outputDir = "$root\dist"
   
   & $isccPath "/dMyAppReleaseDirectory=$publishOutput" "/dOutputBaseFilename=XerahS-$version-win-arm64" "/dOutputDir=$outputDir" $issScript

Phase 5: Validation

1. Check that both installers exist:
   powershell

   Get-ChildItem 'ShareX Team\XerahS\dist' -Filter '*.exe' | Select-Object Name, Length, LastWriteTime | Format-Table -AutoSize

2. Verify they were created recently (within the last few minutes)
3. Expected output:

   Name                          Length     LastWriteTime
   ----                          ------     -------------
   XerahS-{version}-win-arm64.exe  ~55-60MB   [Today's date]
   XerahS-{version}-win-x64.exe    ~55-60MB   [Today's date]

Important Notes

Sequential Builds Are Mandatory

net9.0

net10.0

net9.0-windows10.0.26100.0

net10.0-windows10.0.26100.0

ShareX.ImageEditor.dll

CS2012

• Architectures:

  package-windows.ps1

  already iterates

  win-x64

  then

  win-arm64

  sequentially via

  foreach

  — never invoke it twice concurrently.
• Internal parallelism: Controlled by

  /m:1

  on the

  dotnet publish

  call, which forces single-threaded MSBuild and eliminates the intra-build race.
• Between builds: Always run

  dotnet build-server shutdown

  and kill VBCSCompiler between consecutive build sessions.

Why File Locking Happens

• VBCSCompiler: Roslyn compiler server caches assemblies for faster builds
• Parallel builds: Multiple projects trying to write the same DLL simultaneously
• Running XerahS instances: The Watch Folder daemon loads DLLs from Debug folder
• Avalonia designer: May hold references to compiled DLLs

Key Build Parameters

• -p:UseSharedCompilation=false

  : Disables VBCSCompiler server

• -p:nodeReuse=false

  : Prevents MSBuild from reusing build nodes

• /m:1

  : Forces single-threaded build (slower but no race conditions)

• -p:SkipBundlePlugins=true

  : Avoids custom MSBuild target path resolution bugs

Build Error Handling

• Don't panic if you see CS2012 errors: The build may still succeed
• Always check if XerahS.exe was created: The error might be during a retry
• ImageEditor is the usual culprit: It has parallel TFM builds (net9.0, net10.0, with/without Windows SDK)
• ARM64 builds are more prone to locking: They run after x64 which may leave processes

Best Practices

1. Always run Phase 1 cleanup first
2. Monitor the build output for "file may be locked by" messages
3. Check actual file creation, not just exit codes
4. Keep VBCSCompiler killed during builds
5. Close any running XerahS instances before building

Success Criteria

• ✅ Both win-x64 and win-arm64 .exe installers created
• ✅ Files are ~55-60 MB in size
• ✅ Timestamps are recent (within build session)
• ✅ No lingering build processes (VBCSCompiler, dotnet, MSBuild)
• ✅ Dist folder contains the expected installer files

Troubleshooting

/m:1

iscc_log_win-{arch}.txt

Related Files

• Build script: build\windows\package-windows.ps1
• Inno Setup script: build\windows\XerahS-setup.iss
• Version config: Directory.Build.props
• Build logs:

  build/windows/iscc_log_win-{arch}.txt