Obfuscar Documentation¶
Attention
Obfuscar 3.0 Beta is now available!
Version 3.0 is a major upgrade with:
Significant performance improvements (modern IL pipeline, no Mono.Cecil)
Better .NET language feature support (recent async/LINQ patterns)
Stricter configuration (absolute paths only, no variable expansion)
Install via:
Global Tool (console):
dotnet tool install --global Obfuscar.GlobalTool --prereleaseNuGet Package (.NET Framework/projects):
dotnet package add Obfuscar --prerelease
Without --prerelease, the stable version 2.2 is installed.
Warning
Obfuscar 3.0 configuration files must use absolute paths for InPath, OutPath, and LogFile. Relative paths are rejected.
Warning
Obfuscar 3.0 does not expand environment variables or $(...) placeholders in configuration files. Provide explicit values.
Note
It is recommended to generate the Obfuscar XML configuration file as part of your build or CI pipeline. Expand environment variables and resolve relative paths during generation so the produced XML contains only absolute paths and explicit values.
General¶
Obfuscar is a basic obfuscator for .NET assemblies. It uses massive overloading to rename metadata in .NET assemblies (including the names of methods, properties, events, fields, types and namespaces) to a minimal set, distinguishable in most cases only by signature.
For example, if a class contains only methods that accept different parameters, they can all be renamed ‘A’. If another method is added to the class that accepts the same parameters as an existing method, it could be named ‘a’.
It makes decompiled code very difficult to follow. The wiki has more details about What It Does.
The current release is Obfuscar 2.x. The project historically used the Mono.Cecil library for metadata handling. With the upcoming v3 release Obfuscar has been refactored to use System.Reflection.Metadata (SRM)-backed readers and mutable metadata abstractions; v3 will not have a runtime dependency on Mono.Cecil for its core obfuscation pipeline. See the developer notes for migration details.
Note
Since version 1.5 the attrib attribute is evaluated correctly. Be sure to check if there are any unintended attrib values from the example in your configuration file.
Its source code can be found at GitHub,
https://github.com/obfuscar/obfuscar
Obfuscar previously relied on Jb Evain’s Mono.Cecil for low-level metadata manipulation. The codebase has since moved to SRM/mutable adapters.
The documentation section includes the following topics,
- Visit Docs Home
- Getting Started
- What does Obfuscar do?
- Configuration
- Settings
- Variables, InPath and OutPath
- Assembly Search Path (2.2.5+)
- KeepPublicApi and HidePrivateApi
- Modules
- Exclusion Rules by Configuration
- Skipping special-name and compiler-generated members
- Inclusion Rules by Configuration (new)
- Name Matching
- Accessibility Check
- Exclusion by Attributes in Code
- Inclusion/Exclusion Rule Priorities
- Control Generation of Obfuscated Names
- Control String Hiding
- SuppressIldasm Attribute
- Signing of Strongly Named Assemblies
- Configuration Fragments (2.2.5+)
- SkipGenerated
- Related Resources
- Project History
- Ecosystem Around Obfuscar
- Tutorials
- Support
- Frequent Asked Questions
- How to understand the return code?
- How to troubleshoot IOException?
- How to troubleshoot ArgumentException?
- How to troubleshoot BadImageFormatException?
- How to troubleshoot ResolutionException or AssemblyResolutionException?
- How to troubleshoot NotSupportedException?
- Why does Obfuscar reject relative paths or $(…) placeholders?
- How to troubleshoot UnauthorizedAccessException?
- How to troubleshoot TypeLoadException during reflection?
- How to troubleshoot TypeLoadException if a method does not have implementation?
- How to analyze exception call stack if obfuscated?
- Related Resources
- Support Services
- Frequent Asked Questions
- Contribute
- Privacy Policy
Contribute to Documentation¶
The documentation on this site is the handiwork of our many contributors.
We accept pull requests! But you’re more likely to have yours accepted if you follow these guidelines:
Read the Contributing Guide.