Skip to main content

Velopack Packaging and Deployment Guide

This document describes the Velopack packaging, installation, auto-update workflow, and common issues for ProcessVision.

1. Core Concepts​

ItemValueDescription
PackIdProcessVisionInstallation identifier name, cannot be changed
MainExeJope.App.ProcessVision.exeMain executable name, cannot be changed
Install Directory%LOCALAPPDATA%\ProcessVision\User directory, no Admin required
Data Directory%APPDATA%\ProcessVision\User data (unaffected by updates)
Update SourceGitHub Releasesgather-system/GST.App.ProcessVision
Velopack Version0.0.1298NuGet Package

Important Principle: Once deployed, PackId and MainExe cannot be changed; otherwise, shortcuts will break and uninstallation will fail.

2. Packaging Pipeline​

Stage 1: PUBLISH
  dotnet publish -c Release -r win-x64 --self-contained
  └→ bin/Release/net8.0-windows/win-x64/publish/

Stage 2: PROTECT (Optional)
  Protect-GstAssemblies.ps1
  └→ .NET Reactor three-tier protection

Stage 3: PACK
  vpk pack --packId ProcessVision --mainExe Jope.App.ProcessVision.exe
  └→ .nupkg + Setup.exe + RELEASES

Stage 4: RELEASE (Optional)
  gh release create v{version}
  └→ Upload to GitHub Releases

2.1 Execution Methods​

# 預設（Publish + Protect + Pack）
.\publish-velopack.ps1 -Version "1.0.6"

# 跳過保護
.\publish-velopack.ps1 -Version "1.0.6" -SkipProtection

# 完整流程 + 上傳 GitHub
.\publish-velopack.ps1 -Version "1.0.6" -UploadToGitHub

# Prerelease（Beta Channel）
.\publish-velopack.ps1 -Version "1.0.6-beta.1" -Channel "beta" -UploadToGitHub -Prerelease

# 只到 Publish（除錯用）
.\publish-velopack.ps1 -Step Publish

2.2 Output Files​

releases/v1.0.6/
├── ProcessVision-1.0.6-full.nupkg    ← Full installation package
├── ProcessVision-1.0.6-delta.nupkg   ← Delta update package
├── ProcessVision-win-Setup.exe       ← Installer
├── RELEASES                          ← Release metadata
└── releases.win.json                 ← Update manifest

3. .csproj Configuration​

<PropertyGroup>
    <OutputType>WinExe</OutputType>
    <AssemblyName>Jope.App.ProcessVision</AssemblyName>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Version>1.0.6</Version>
    <PublishSingleFile>false</PublishSingleFile>  <!-- Velopack 不支援 SingleFile -->
</PropertyGroup>

<ItemGroup>
    <PackageReference Include="Velopack" Version="0.0.1298" />
</ItemGroup>

4. app.manifest Configuration​

<requestedExecutionLevel level="asInvoker" uiAccess="false" />

Must use asInvoker. Using requireAdministrator will cause Setup.exe to fail on launch after installation (OS Error 740), because Velopack installs to the user directory and does not require Admin privileges.

5. Application Initialization​

5.1 App.xaml.cs Startup Sequence​

// 1. Velopack 初始化（必須最先執行）
VelopackApp.Build().Run();

// 2. License 檔案複製（在 DI 之前）
CopyLicenseFiles();

// 3. 單一實例檢查
SingleInstanceGuard("Jope.App.ProcessVision");

// 4. DI 註冊
services.AddSingleton<IUpdateService>(sp =>
    new VelopackUpdateService(logger, localizationService, updateSource));

// 5. 延遲更新檢查（UI 就緒後 3 秒）
await Task.Delay(3000);
await CheckForUpdatesOnStartupAsync();

5.2 VelopackUpdateService​

  • Update Source: GitHub Releases (can be overridden via UpdateSource in appsettings.json)
  • Token Priority: Environment variable PROCESSVISION_UPDATE_TOKEN > Embedded Token
  • Retry Mechanism: Update check retries 3 times (2-second interval), download retries 3 times (5-second interval)
  • Non-blocking: Update check does not block main application startup

5.3 Update UI Flow​

Startup → 3-second delay → CheckForUpdatesAsync()
  ↓ Update available
UpdateWindow Dialog (displays version diff)
  ↓ User clicks "Update Now"
DownloadUpdatesAsync() (progress bar 0-100%)
  ↓ Download complete
ApplyUpdatesAndRestart() (restart application)

6. Channel Management​

ChannelPurposePackaging Command
stableProduction release (default)-Channel "stable" or unspecified
betaTest version-Channel "beta" -Prerelease
alphaDevelopment version-Channel "alpha" -Prerelease

VelopackUpdateService defaults to checking prerelease: false (stable) only and will not auto-update to beta/alpha.

7. Excluded Files​

The following files are not included in the Velopack update package and will not be overwritten during updates:

appsettings.json       ← Application settings (user may have modified)
deviceconfig.json      ← Device configuration

Implemented via vpk's --exclude regex: "appsettings\.json$|deviceconfig\.json$"

8. Frequently Asked Questions​

8.1 OS Error 740 (Launch Failure After Installation)​

Cause: app.manifest was set to requireAdministrator. Solution: Change to asInvoker. (JOP-163)

8.2 Blank Shortcut Icon​

Cause: Windows icon cache expired. Solution:

ie4uinit.exe -show

8.3 Shortcut Broken / Cannot Uninstall After Renaming exe​

Cause: Velopack writes the MainExe name to the registry and shortcuts during installation; renaming causes a mismatch. Solution: Manually clean up the old installation and perform a fresh install:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ProcessVision"
Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\ProcessVision" -Recurse -ErrorAction SilentlyContinue

8.4 "Not a Velopack Installation" Shown in Development Mode​

Expected behavior. When running via dotnet run or Visual Studio, IsInstalled is false and update checks are skipped.

Document Version: v1.0 | Created: 2026-03-16 | Linear Issue: GST-164