How to obfuscate a NuGet package

A .nupkg is a zip file one double-click from a decompiler — and the easiest artifact to break, because other code compiles against it. Where obfuscation fits between build and pack, why the public API stays intact, multi-targeting, and the symbol-package and friend-assembly mistakes that undo the protection.

A NuGet package is the easiest .NET artifact to decompile: it is a zip file, and the assemblies inside are one double-click from ILSpy. It is also the easiest to break by obfuscating carelessly, because other people's code compiles against it. This guide covers where obfuscation fits in the pack step, what must stay untouched, and the package-specific mistakes that quietly undo the protection.

What is actually in the package

Rename a .nupkg to .zip and open it. The parts that matter:

  • lib/<tfm>/YourLib.dll — the implementation assemblies, one per target framework. These are what consumers run, and what a decompiler reads. This is what you obfuscate.
  • lib/<tfm>/YourLib.xml — XML documentation for IntelliSense. It describes only your public API, which is not renamed, so it stays correct.
  • ref/<tfm>/ — optional reference assemblies with signatures and no method bodies. There is nothing in them to protect.
  • The .nuspec — package metadata. Unaffected.

Why the public API is left alone

A consumer's compiled code refers to your public types and members by name. If InvoiceClient.SendAsync became a.b, every project referencing your package would stop compiling. So for a library, the public surface is preserved and everything behind it — private and internal types, methods, fields — is renamed. The rule and its reasoning are in why public names are only renamed in applications.

The practical consequence: the less of your library is public, the more of it is protected. Before you obfuscate, it is worth an hour making implementation types internal that were only public by habit. That one change does more for a package than any extra layer.

Where obfuscation goes: between build and pack

dotnet pack builds and packs in one step by default, which leaves no gap to protect the assembly. Split it:

  1. Build in Release: dotnet build -c Release.
  2. Test against the unobfuscated output.
  3. Obfuscate each bin/Release/<tfm>/YourLib.dll and write the result back over the original.
  4. Pack without rebuilding: dotnet pack -c Release --no-build. The --no-build flag is the one that matters — without it, pack recompiles and silently ships the unprotected assembly.
  5. Sign the package, then push.

In a pipeline, step three is one API call per assembly:

dotnet build -c Release

for tfm in net8.0 netstandard2.0; do
  curl -sS --fail-with-body \
    -X POST https://freeobfuscator.com/api/v1/obfuscate \
    -H "X-Api-Key: $FO_API_KEY" \
    -F "file=@bin/Release/$tfm/YourLib.dll" \
    -F "encryptStrings=true" \
    -F "controlFlow=true" \
    -o "YourLib.$tfm.protected.dll"
  mv "YourLib.$tfm.protected.dll" "bin/Release/$tfm/YourLib.dll"
done

dotnet pack -c Release --no-build

API access is a Pro feature; the full pipeline setup, including why --fail-with-body matters, is in obfuscating .NET builds in CI/CD. For a one-off release you can do the same by hand: upload the DLL in the browser, download the protected copy, replace the file, and pack with --no-build.

Multi-targeting: protect every target

If the package targets several frameworks, each lib/<tfm> folder holds a separately compiled assembly. Protect all of them. Leaving netstandard2.0 unprotected because "everyone uses net8.0 now" hands a reader the same logic in clear — they will simply open the unprotected one.

The mistakes that undo it

  • Publishing a symbol package. A .snupkg with PDBs, or Source Link pointing at your repository, gives back names and source that obfuscation removed. If the implementation is what you are protecting, do not publish symbols for it — and if you keep PDBs privately, keep the ones that match the obfuscated build.
  • Embedding sources or debug info. EmbedAllSources and DebugType=embedded put your source text inside the DLL. Check the Release configuration before you ship.
  • Friend assemblies. InternalsVisibleTo lets another assembly bind to your internal names — and internal names are renamed. A friend that points at your test project is harmless, because tests run before obfuscation. A friend that points at another shipped assembly is not, if the two are protected separately: the second one will fail to bind at runtime. Protect them together instead — the API's /api/v1/obfuscate/set endpoint takes both assemblies in one request and rewrites the references between them, so they still load. Failing that, merge the two or make the members they share part of the public contract.
  • Name-based lookups inside the library. Serializers, DI containers and anything else that finds members by string. Public members are safe; internal DTOs deserialized by name are the usual casualty. See obfuscation and reflection.

Signing: after, never before

Obfuscation rewrites the assembly, so it invalidates a strong-name or Authenticode signature applied earlier. Sign the DLLs after obfuscating, pack, then sign the package itself with dotnet nuget sign. The reasoning is in obfuscation and code signing.

Test it the way a consumer would

Unit tests against your project prove nothing about the package. Before pushing, add the built .nupkg to a local folder feed, reference it from a small throwaway console app, and exercise the documented entry points. That one check covers the three things that actually go wrong: the public API still binds, name-based lookups still resolve, and the right (protected) assembly is the one that got packed. A broader workflow is in how to test your obfuscated build before you ship.

The honest limit. Your public API is, by design, readable — its names are the contract. Obfuscation protects how the library works, not what it exposes. If the valuable part is the implementation behind a small facade, that is a good fit. If the value is the shape of the API itself, obfuscation cannot hide it, and nothing that ships to a developer's machine can.

Selling the library? The paid libraries and SDKs use case covers the commercial side — what licensees can still see, and how to structure a package so more of it is protected.

Try it on your own assembly

Upload a DLL or EXE and download the obfuscated result. Free, no signup, nothing stored.