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:
- Build in Release:
dotnet build -c Release. - Test against the unobfuscated output.
- Obfuscate each
bin/Release/<tfm>/YourLib.dlland write the result back over the original. - Pack without rebuilding:
dotnet pack -c Release --no-build. The--no-buildflag is the one that matters — without it, pack recompiles and silently ships the unprotected assembly. - 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
.snupkgwith 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.
EmbedAllSourcesandDebugType=embeddedput your source text inside the DLL. Check the Release configuration before you ship. -
Friend assemblies.
InternalsVisibleTolets 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/setendpoint 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.
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.