Obfuscar: A Minimal .NET Assembly Obfuscator You Configure With XML

What Obfuscar Does to a .NET Assembly

Obfuscar renames the metadata inside a compiled .NET assembly so that class, method and field names stop describing what the code does. A method called CalculateInvoiceTotal becomes something like a, and a type called CustomerRepository becomes a meaningless identifier. The IL stays functionally equivalent; what changes is the information a reader can recover from the binary.

The intended audience is narrow. If you distribute a desktop application, a plugin, or a library to customers who will have the DLLs on disk, Obfuscar raises the effort required to read your code. It does not encrypt anything, and it does not stop a determined analyst who is willing to run a decompiler and read the renamed IL. The README describes the goal plainly: "basic obfuscation features that help secure secrets in a .NET assembly." Basic is the operative word, and the project does not pretend otherwise.

It is the wrong tool for a web service you operate yourself, where the binary never leaves your infrastructure. It is also the wrong tool if your threat model includes someone patching your assembly at runtime, because renaming symbols does not detect or prevent modification.

How the XML Project File Drives the Pipeline

Obfuscar is not a command you point at a DLL with flags. It reads an XML project file that declares the modules to process, where the obfuscated output goes, and which names must survive. That file is the whole interface.

The configuration carries two categories of instruction. Input and output paths tell Obfuscar which assemblies to load and where to write the rewritten copies. Rules then control what is renamed: you can keep specific types or members untouched, and you can mark names that external code depends on. This matters because reflection, serialization and plugin contracts all break when a name changes underneath them. Anything your application looks up by string at runtime has to be listed as preserved, and the README points to the documentation site for the details rather than reproducing the schema.

Two deprecation notices in the README affect how you write that file today. Environment-variable expansion inside configuration files is deprecated and will be removed in a future release, so relying on it now means a migration later. Relative paths in configuration files are also deprecated, and future releases will require absolute paths. A config that works on your machine may need rewriting before the next upgrade.

The README also carries a security notice worth reading before you run anything. Obfuscar depends on low-level metadata and PE-reading APIs, naming System.Reflection.Metadata and System.Reflection.PortableExecutable.PEReader, which the notice says are not designed to handle untrusted input. Malformed or malicious assemblies or metadata can cause unexpected behavior, including crashes or hangs. The instruction that follows is direct: only run Obfuscar on assemblies and inputs you trust. That rules out using it as a scanning step over DLLs you did not build.

Installing Obfuscar and Running a First Obfuscation

The README links two NuGet packages. Obfuscar.GlobalTool is the .NET global tool, and Obfuscar is the .NET Framework package. The README does not print the install command itself, so take the exact syntax from the NuGet page for Obfuscar.GlobalTool rather than copying it from here.

Once the tool is installed, the workflow is the same either way: you write an XML project file and pass it to the tool. The README does not reproduce the configuration schema, and it does not show a sample project file, so the element names and the invocation syntax have to come from the documentation site at docs.obfuscar.com. That is the only place the project points readers for this.

Two constraints from the README shape the file you write. Environment-variable expansion inside configuration files is deprecated and will be removed in a future release, so avoid environment-variable syntax and follow the migration guidance in the documentation. Relative paths in configuration files are also deprecated, and future releases will require absolute paths, so write absolute paths from the start.

What you should expect after a run: the output assemblies land wherever your configuration directs them, and opening one in a decompiler should show type and member names that no longer match your source. If a name you expected to be renamed is still readable, it was probably preserved by a rule, or it is referenced somewhere that forced Obfuscar to keep it. The README does not document rollback, so keep the original assemblies and a copy of the config before you overwrite anything.

Where Obfuscar Stops Being the Right Answer

The limitation is not a bug, it is the design. Obfuscar renames metadata. It does not encrypt string literals, it does not flatten control flow, and it does not add tamper detection. If your application embeds an API key or a licence check as a string constant, renaming the surrounding method does not hide that string, and a reader who decompiles the assembly will still find it.

The reflection problem is the second constraint. Any code path that resolves a type or member by name at runtime depends on that name surviving obfuscation. Serializers, dependency injection containers configured by convention, and plugin loaders all fall into this category. Each one needs an explicit preservation rule, and a missed rule produces a runtime failure that may not appear until a specific code path executes. Testing the obfuscated build, not just the original, is the only way to catch this.

The trust boundary is the third. Because Obfuscar reads PE metadata with APIs the README describes as not designed for untrusted input, feeding it a third-party assembly is a risk the project explicitly flags. Treat it as a build step over your own output, not as a general-purpose tool for inspecting arbitrary binaries.

Obfuscar Compared With ConfuserEx

The closest point of comparison in the .NET space is ConfuserEx, and the difference is scope rather than quality. ConfuserEx applies protection passes beyond renaming, including control-flow obfuscation, reference proxies and anti-tamper. Obfuscar does renaming and stops there.

That difference changes what you have to maintain. A ConfuserEx configuration is a protection pipeline with multiple passes, each of which can interact badly with reflection or with the runtime. An Obfuscar configuration is a rename map plus a preservation list, which is a much smaller surface to reason about and a much smaller surface to break. If your goal is to make a decompiled assembly harder to read and you can enumerate the names that must survive, Obfuscar gets there with less machinery. If your goal is to resist an analyst who is actively working against the binary, renaming alone will not carry that weight, and you need a tool that does more than Obfuscar claims to do.

The other axis is the release cadence. Recent releases are all v3.0.0 beta builds, with v3.0.0-beta.22 on 2026-09-18, v3.0.0-beta.21 on 2026-09-14 and v3.0.0-beta.20 on 2026-08-29. The 3.0 line has not shipped a stable release so far, so teams that require a stable version tag should account for that before standardizing on it. The last push to the repository was on 2026-09-18.

Licence, Maintenance and Upgrade Cost

Obfuscar is released under the MIT licence, which permits commercial use and modification with the licence text retained. The README does not discuss patent terms or trademark use, and nothing here should be read as legal advice; if your organization has a policy on bundled dependencies, the MIT text is short enough to review directly.

Maintenance is visible in the repository: the last push was on 2026-09-18, and the project is maintained by LeXtudio Inc., which the README lists as the party to contact for support services. The project is not archived. It accepts pull requests, with a Contributor License Agreement required before contributions are merged.

The upgrade cost is the part that deserves attention. Two deprecations are already announced and both will force edits to configuration files: environment-variable expansion inside config files, and relative paths. A team that adopts Obfuscar today and uses either feature will pay for it at the next upgrade. Writing absolute paths and avoiding environment-variable syntax from the start removes that future work entirely. The README does not state when those removals take effect, so the timing is unknown.

Editorial conclusion

Adopt Obfuscar if you ship a .NET Framework or .NET assembly and want name-level obfuscation driven by a config file you can check into source control. Do not adopt it if you need string encryption, control-flow rewriting or anti-tamper, and do not run it on assemblies from third parties: the README states that malformed or malicious metadata can cause crashes or hangs. Before rolling it out, verify which of your assemblies a single config file actually covers, and confirm that your release pipeline can supply the absolute paths that future releases will require.

Frequently asked questions

Official sources

1. License: MIT
2. obfuscar/obfuscar on GitHub
3. Project website
4. README
5. Releases