XML Map Files

Babel Obfuscator uses XML map files to map the original, unobfuscated names of classes, methods, properties, events and fields to their obfuscated names. These files can be generated by the Babel Obfuscator during the obfuscation process, and they are stored in the same directory as the obfuscated assembly.

The XML map files are important because they allow developers to:

1. Deobfuscate the exception stack traces.

2. Obfuscate the public interface of an assembly.

Deobfuscate Stack Trace

When an exception is thrown in an obfuscated application, the stack trace contains the names of the obfuscated symbols, which are not easily readable or identifiable. However, by using the XML map files, the obfuscated names can be mapped back to their original names, allowing developers to more easily identify the source of the exception and debug the issue. This makes the XML map files a valuable tool for developers working with obfuscated applications.

To learn more about deobfuscating stack traces, please refer to the Stack Decoder paragraph.

Obfuscate Public Interface

Since .NET assemblies often reference other assemblies, including third-party libraries, it is common for the names of objects, methods, and properties in one assembly to be used in another. When these assemblies are obfuscated separately, the obfuscation process may change the original names of externally visible objects and methods in one assembly, causing the other assemblies that reference them to no longer work properly. The obfuscation of externally visible assembly members is often referred to as Cross Assembly Renaming.

XML map files provide a way to maintain the relationships between the original names and the obfuscated names across multiple assemblies. When multiple assemblies are obfuscated, their respective XML map files can be combined to ensure that the original relationships between the names are preserved. This allows the obfuscated code to work correctly even when it is being called from other assemblies that have not been obfuscated.

Configuring XML Map File Generation

The XML map file generation can be configured from the command line, the Babel user interface, or in build environments through the MSBuild Babel task and the Babel Obfuscator NuGet package.

Command Line

The Babel Obfuscator command line tool can accept the maoput option to enable XML map file generation. The basic syntax for enabling map file generation is as follows:

babel MyApp.exe --mapout [output file]

The option can accept the full path of the generated XML map file. If the path is not specified, the XML map file will be named as the original target file name adding the “.map.xml” extension and stored in the same directory of the obfuscated assembly.

For example, if the obfuscated assembly is named "MyApp.exe", the XML map file will be named "MyApp.exe.map.xml".

You can also specify additional options to customize the map file generation, such as specifying a different output encoding format for the map file names:

babel MyApp.exe --mapout encoding=base64

The supported formats are 'none' and 'base64'. If the encoding format is not specified, babel will choose the base64 format when the Unicode Normalization is enabled.

MSBuild Babel Task

To enable the generation of XML map files in the MSBuild Babel task, set the GenerateMapOutFile task attribute to true. Optionally you can specify the generated file path using the MapOutFile attribute:

<Babel GenerateMapOutFile="true" MapOutFile="MyAssembly.map.xml" />

If you are using in your project file, the Babel Obfuscator NuGet package, you can add the following XML element to your project file to enable the generation of the XML map file of the obfuscated target assembly:

<PropertyGroup>
  <GenerateMapOutFile>true</GenerateMapOutFile>
</PropertyGroup>

You can override the file path of the generated XML map file using the following property:

<PropertyGroup>
  <GenerateMapOutFile>true</GenerateMapOutFile>
  <BabelMapOutFile>MyAssembly.map.xml</BabelMapOutFile>
</PropertyGroup>

Babel UI

To enable the generation of XML map files from the Babel Obfuscator user interface, follow these steps:

1. Open the Babel Obfuscator UI application.

2. Load an existing project file, or add the target assembly in the Input grid.

3. In the "Output" section, check the box Map File in the "Additional Files" panel.

4. You can optionally choose the output directory where the XML map files will be saved by clicking on the "..." button next to the "Map File" field.

5. Click the save button on the toolbar to save the changes.

Babel UI XML Map File

After enabling the generation of XML map files, Babel Obfuscator will create a map file for the input assembly that it obfuscates, with the same name as the obfuscated assembly but with a .map.xml extension. The map files will be saved in the directory that was specified in the "Map File" field.