# Obfuscating a ClickOnce app without breaking launch


There is a particular way a ClickOnce app fails after you add obfuscation that sends people down entirely the wrong rabbit hole: the app installs fine, then refuses to launch with a file validation or hash-mismatch error, and nothing in your code changed. The instinct is to suspect the obfuscator broke the assembly. It did not. ClickOnce is doing exactly what it is designed to do — refusing to run a file whose bytes do not match the hash it recorded — and the real bug is the *order* in which your build steps ran. Get the order right and obfuscation and ClickOnce coexist with no drama.

## Why ClickOnce is unusually sensitive

Most deployment mechanisms copy files and run them. ClickOnce does more: its **application manifest** records, for every file in the deployment, a cryptographic hash and a size, and the ClickOnce runtime verifies each file against that record before launching. This is a tamper- and corruption-detection feature — it guarantees the user runs exactly what you published.

That guarantee is precisely what obfuscation collides with. Obfuscation *rewrites the bytes* of your assemblies — renaming, control-flow flattening, string encryption all change the file. If the manifest's hash for `MyApp.dll` was computed over the **pre-obfuscation** DLL, the post-obfuscation DLL you actually ship no longer matches, and ClickOnce halts with a validation error before a line of your code runs.

<svg viewBox="0 0 740 210" role="img" aria-labelledby="co-title" xmlns="http://www.w3.org/2000/svg" style="max-width:100%;height:auto;font-family:system-ui,sans-serif">
  <title id="co-title">Obfuscate before manifests are hashed, not after</title>
  <style>.b{fill:none;stroke:#64748b;stroke-width:1.5}.t{fill:currentColor;font-size:12.5px}.s{fill:#64748b;font-size:11px}.ob{stroke:#6366f1;stroke-width:2}.bad{stroke:#ef4444;stroke-width:1.5}.ar{stroke:#64748b;stroke-width:1.5;marker-end:url(#c)}</style>
  <defs><marker id="c" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0 0L10 5L0 10z" fill="#64748b"/></marker></defs>
  <text class="s" x="20" y="30">Correct order:</text>
  <rect class="b" x="20" y="40" width="120" height="40" rx="8"/><text class="t" x="34" y="64">compile</text>
  <line class="ar" x1="140" y1="60" x2="168" y2="60"/>
  <rect class="b ob" x="170" y="40" width="120" height="40" rx="8"/><text class="t" x="184" y="64">obfuscate</text>
  <line class="ar" x1="290" y1="60" x2="318" y2="60"/>
  <rect class="b" x="320" y="40" width="120" height="40" rx="8"/><text class="t" x="334" y="58">sign</text><text class="s" x="334" y="74">strong-name/Authenticode</text>
  <line class="ar" x1="440" y1="60" x2="468" y2="60"/>
  <rect class="b" x="470" y="40" width="140" height="40" rx="8"/><text class="t" x="484" y="58">mage: manifests</text><text class="s" x="484" y="74">hash final files</text>
  <text class="s" x="20" y="120">Wrong order (app won't launch):</text>
  <rect class="b" x="20" y="130" width="120" height="40" rx="8"/><text class="t" x="34" y="154">compile</text>
  <line class="ar" x1="140" y1="150" x2="168" y2="150"/>
  <rect class="bad" fill="none" x="170" y="130" width="140" height="40" rx="8"/><text class="t" x="184" y="148">mage: manifests</text><text class="s" x="184" y="164">hashes PRE-obf files</text>
  <line class="ar" x1="310" y1="150" x2="338" y2="150"/>
  <rect class="bad" fill="none" x="340" y="130" width="120" height="40" rx="8"/><text class="t" x="354" y="154">obfuscate</text>
  <text class="s" x="470" y="154">→ hash mismatch at launch</text>
</svg>

## The correct build order

The rule is one sentence: **every transformation of the assemblies must happen before the manifests are generated, and manifest generation must be last.** Concretely:

1. **Compile** the project.
2. **Obfuscate** the output assemblies.
3. **Re-apply the strong name** if you delay-signed (obfuscation that re-emits the assembly must preserve or re-establish the strong name — see [re-signing obfuscated assemblies](https://delta1labs.com/blog/re-sign-obfuscated-assembly-strong-name-authenticode/)).
4. **Authenticode-sign** the binaries, if you sign them.
5. **Generate the application and deployment manifests** with `mage`/`mageUI` or the MSBuild ClickOnce targets — this is where the hashes are computed, over the now-final files.
6. **Sign the manifests.**

If you use Visual Studio's one-click Publish, the trap is that publish *does step 5 for you right after build*, before any post-build obfuscation hook has run. The fix is to take manifest generation out of the Publish step and run `mage` yourself after obfuscation (a small CI script), or run obfuscation as part of the build such that it completes before the ClickOnce targets execute.

## A minimal CI sketch

```bash
# 1-2: build then obfuscate the output
dotnet build -c Release -o publish
nebula protect publish/MyApp.dll   # (plus other assemblies)

# 3-4: re-sign as needed
sn -R publish/MyApp.dll keypair.snk           # if delay-signed
signtool sign /f cert.pfx publish/MyApp.dll    # Authenticode (optional)

# 5: generate manifests over the FINAL files (hashes computed now)
mage -New Application -Processor msil -ToFile publish/MyApp.exe.manifest \
     -Name "MyApp" -Version 1.2.0.0 -FromDirectory publish
mage -New Deployment -Processor msil -Install true \
     -ToFile MyApp.application -AppManifest publish/MyApp.exe.manifest \
     -providerUrl "https://downloads.example.com/MyApp/"

# 6: sign the manifests
mage -Sign MyApp.application -CertFile cert.pfx
```

Because the hashes in step 5 are taken over the obfuscated, signed assemblies, the ClickOnce runtime's verification passes and the app launches.

## Doing this with Nebula

[Nebula](https://delta1labs.com/nebula) slots into the obfuscation step above, and because it runs as a build/CI stage (see [obfuscating on the build server only](https://delta1labs.com/blog/obfuscate-on-build-server-only/) and the [Azure DevOps](https://delta1labs.com/blog/obfuscate-dotnet-azure-devops/) / [GitHub Actions](https://delta1labs.com/blog/obfuscate-dotnet-github-actions/) guides), it is straightforward to place it before ClickOnce manifest generation. It preserves strong-name signing so the re-sign step is clean, and its keep-rules handle any WinForms/WPF reflection your app does. The only ClickOnce-specific rule is the ordering — get that right and nothing else changes.

Start with the [free edition](https://delta1labs.com/blog/free-dotnet-obfuscator/), or see the [plans](https://delta1labs.com/pricing?product=nebula).

