NuGet Package

The Babel Obfuscator NuGet package will allow you to deploy Babel on any build server based on .NET SDK.

Babel.Obfuscator NuGet Package

The Babel.Obfuscator.nupkg NuGet package is a part of the Babel Obfuscator software and is made available for use after purchasing the Ultimate edition or one of the Babel Licensing editions. Please refer to the installation section in the documentation to learn how to set up your build environment to use the Babel Obfuscator NuGet package properly.

Add Babel Obfuscator NuGet Package Reference

The Babel Obfuscator NuGet package provides the babel tool for your .NET projects. You can install the Babel Obfuscator NuGet package in your Microsoft Visual Studio projects using the NuGet Package Manager. Upon successful installation, you can proceed with building your solution. During the build process, Babel Obfuscator will obfuscate the designated target assembly.

The Babel Obfuscator NuGet package can be easily added to a .NET project from the NuGet package manager. This package includes the babel build tool, which is used for obfuscating .NET assemblies.

When you add Babel.Obfuscator NuGet package to your project through the Visual Studio NuGet Package Manager, the following XML element will be added to your project file (.csproj or .vbproj file) as a PackageReference:

<ItemGroup>
  <PackageReference Include="Babel.Obfuscator" Version="10.0.0">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
</ItemGroup>

The <PackageReference> element, specifies the package name and version and includes additional metadata such as the assets to include and exclude. The PrivateAssets element is set to all to prevent babel from being included as a dependency of the project, and the IncludeAssets element specifies which assets to include when the package is installed.

it is essential to include additional metadata to prevent the babel tool from being added as a reference to the built assembly. If you add the PackageReference manually to your project, this additional metadata must also be added; otherwise, the babel tool will be added as a reference in your assembly, leading to undesired behaviour. Thus, including the additional metadata is necessary to ensure the proper functioning of the Babel Obfuscator.

Acrivating License

The Babel Obfuscator tool requires the availability of a valid license throughout the compilation phase. If you possess a license file, you can place the babel.licenses file within your solution directory prior to initiating the build. Alternatively, you may opt to define the BABEL_LICENSE_PATH environment variable as described in the License File section.

In scenarios where a license key has been directly provided to you, integration of the license with your MSBuild project can be seamlessly achieved by embedding the following snippet within your project file. This inclusion ensures that the Babel Obfuscator is appropriately licensed each time it is invoked during the build process.

<PropertyGroup>
  <BabelLicense>floating:YOUR_BABEL_LICENSE_KEY</BabelLicense>
</PropertyGroup>

In this context, YOUR_BABEL_LICENSE_KEY is a placeholder. You should replace it with the actual license key you have received.

Customize Obfuscation Settings

The customization of Babel Obfuscator can be performed by editing the Visual Studio project file. One aspect of customization that can be done is to disable Babel Obfuscator in Debug build by adding the BabelEnabled element to the PropertyGroup defined for the Debug configuration. This can be achieved by adding the following code:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <BabelEnabled>false</BabelEnabled>
</PropertyGroup>

By adding this code, Babel Obfuscator will not run during the build process in the Debug configuration. This can be useful in scenarios where you need to debug and view the un-obfuscated code without the added complexity of working with obfuscated code.

The PropertyGroup element serves as a container for the configuration-specific options. For example, you can specify different Babel Obfuscator options to fine-tune the obfuscation and meet your specific requirements.

<PropertyGroup>
    <OverloadedRenaming>true</OverloadedRenaming>       
    <ControlFlowObfuscation>if=on;switch=on;call=on</ControlFlowObfuscation>
    <ILIterations>5</ILIterations>
    <MsilEncryption>.*</MsilEncryption>
    <VerboseLevel>1</VerboseLevel>
</PropertyGroup>

Each property maps an MSBuild Babel task attribute. Please refer to the MSBuild Task paragraph to learn about all the properties you can use in your project file.

Building The Project

When building the project with the Babel Obfuscator NuGet package, the target assembly will be obfuscated, and the obfuscation log will be displayed in the Visual Studio Output window.

Babel Obfuscator Visual Studio Output

NuGet Package Known Variables

The Babel Obfuscator NuGet package defines several MSBuild variables that can be used to customize the obfuscation process.

MSBuild Variable	Description
$(BabelAfterTargets)	This variable holds the MSBuild target name that will run after the obfuscation step.
$(BabelBeforeTargets)	This variable holds the MSBuild target name that will run before the obfuscation step.
$(BabelEnabled)	This boolean property enables or disables execution of the Babel task during the obfuscation process.
$(BabelPackageDir)	The Babel.Obfuscator NuGet package root directory.
$(BabelProvideCommandLineArgs)	This setting specifies whether the Babel task should emit the command line arguments utilized by the babel CLI tool. When set to true, the command line arguments are captured and stored within the MSBuild item array @(CommandLineArgs). Additionally, these arguments are also displayed in the build log.
$(BabelTaskDir)	The directory where MSBuild loads the Babel task.
$(CopyOutputSymbolsToPublishDirectory)	Set this property to true to prevent debugging information PDB files from being added to the deployment package. By default, this property is set to true for the Release configuration.
$(RunBabelAfterBuild)	This Boolean variable controls the obfuscation timing: True: Obfuscation occurs after the AfterBuild target. False or Not Set: Obfuscation runs after the Compile target or aligns with the steps defined by $(BabelBeforeTargets) or $(BabelAfterTargets)
$(SymbolsRenaming)	Boolean variable to enable or disable the renaming of symbols during obfuscation process.

The Babel Obfuscator NuGet package provides several task names that can be used as entry points for MSBuild to execute additional tasks. These entry points allow developers to extend the obfuscation process.

Task Name	Description
BeforeObfuscate	Redefine this target in your project to run tasks just before CoreObfuscate.
CoreObfuscate	This target is the point in the MSBuild project where the Babel Obfuscator task is executed. The CoreObfuscate target is typically executed after the source code compilation and before the application deployment.
AfterObfuscate	Redefine this target in your project to run tasks just after CoreObfuscate.
SetupObfuscate ObfuscateCustomSettings	These targets are steps in the build process executed before the Babel obfuscation task. They are designed to allow developers to modify the Babel task properties to suit their specific needs.
UpdateBabelFilesToPublish	This target is executed during the build process after ComputeFilesToPublish task and is designed to remove merge and embedded assemblies from the deployment set of assemblies.

Select Babel SDK Version

The Babel Obfuscator NuGet package supports the latest .NET SDK versions, including NET7, NET6, and NET Core 3.1. When your build environment has one of these .NET SDK versions installed, the Babel NuGet package will automatically select the most appropriate version of Babel to run.

If your build machine has multiple .NET SDKs installed, you have the ability to specify which SDK Babel should utilize by setting the BabelTaskDir property. This property allows you to explicitly define the directory path where the Babel Obfuscator assembly should be loaded.

For example, you can set the BabelTaskDir as follows:

<BabelTaskDir>$(BabelPackageDir)tools\net6.0\</BabelTaskDir>

By adjusting the path to match the location of the desired SDK version, such as net6.0, you instruct Babel to use that specific SDK when executing the obfuscation task.

If none of the supported SDK versions is installed on your build machine, the Babel Obfuscator NuGet package will fall back to using the .NET Core 3.1 SDK as the default.

This approach ensures that Babel runs with the specified SDK version, granting you greater control over the build process and compatibility with your target environment.

Positioning the Obfuscation Step in the Build Pipeline

When integrating the Babel Obfuscator NuGet package into a project, the obfuscation step is strategically positioned in the build pipeline based on the project’s type.

For .NET Framework projects, the obfuscation occurs immediately after the AfterBuild target, directly obfuscating the build output. In contrast, for newer .NET applications, the obfuscation is injected after the Compile target. This placement ensures consistency with modern build optimizations, and in this case, obfuscation is performed on assemblies located in the intermediate obj folder.

In certain scenarios, it may be necessary to modify this default injection point. To achieve this, several MSBuild variables can be used to customize the obfuscation step’s location within the build pipeline:

1. Set $(BabelAfterTargets) to true for .NET projects if you want obfuscation to occur immediately after the AfterBuild target, similar to legacy .NET Framework applications.

If this option is enabled, consider disabling all Ahead-of-Time (AOT) optimizations that run before the obfuscation step, as these optimizations are incompatible with Babel Obfuscator.

1. Set $(BabelAfterTargets) or $(BabelBeforeTargets) to specify an MSBuild target name and adjust the obfuscation step to run after or before the given target.

For example, in a .NET WinForms application with localized resources, you might configure Babel to run after the target responsible for generating satellite assemblies. This allows Babel Obfuscator to process these assemblies effectively:

<PropertyGroup>
   <BabelAfterTargets>CoreGenerateSatelliteAssemblies</BabelAfterTargets>
</PropertyGroup>

By moving the obfuscation after the target CoreGenerateSatelliteAssemblies babel can process satellite assemblies.

Adding Obfuscation Rules Files

Obfuscation rules can be configured by adding to the project an XML file named babelRules.xml.

If you have multiple XML rules files, you can add them to your project by configuring an ItemGroup that references all the rules files Babel Obfuscator should process, ex:

<ItemGroup>
   <BabelRules Include="renamingRules.xml" />
   <BabelRules Include="codeRules.xml" />
</ItemGroup>

Merge and Embed Assemblies

The process of merging or embedding additional assemblies into the obfuscation target can be achieved by defining additional ItemGroup elements in the project file:

<ItemGroup>
   <MergeAssembly Include="$(TargetDir)\Acme.View.dll" />
   <MergeAssembly Include="$(TargetDir)\Acme.ViewModel.dll" />
</ItemGroup>
<ItemGroup>
   <EmbedAssembly Include="$(TargetDir)\Framework.Mvvm.dll" />
   <EmbedAssembly Include="$(TargetDir)\Acme.Wpf.dll" />
</ItemGroup>

When merging types from an external assembly, it is possible to change the visibility of merged types from public to internal, thereby enhancing the efficiency of the renaming process. To internalize the merged types, set the MergeInternalize property to true.

<PropertyGroup>
   <MergeInternalize>true</MergeInternalize>
</PropertyGroup>

Mapping Files

Some obfuscation features, such as renaming public interfaces, require Babel Obfuscator to access the XML mapping files of external obfuscated assemblies. In this case, you can define an ItemGroup that includes multiple MapInFile elements for each mapping file to be processed:

<ItemGroup>
  <MapInFile Include="$(TargetDir)\Acme.View.dll.map.xml" />
  <MapInFile Include="$(TargetDir)\Acme.ViewModel.dll.map.xml" />
</ItemGroup>

To generate an XML mapping file for the obfuscated target assembly, you can add the GenerateMapOutFile property to your project file.

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

Optimizations

Adding specific properties to the Visual Studio project file enables optimizations that Babel Obfuscator can perform during the obfuscation process. These optimizations may improve the performance and efficiency of the target assembly.

<PropertyGroup>
   <DeadCodeElimination>true</DeadCodeElimination>
   <SealClasses>true</SealClasses>
   <EnumRemoval>true</EnumRemoval>
   <ConstRemoval>true</ConstRemoval>
   <DisgregateRemoval>true</DisgregateRemoval>
   <InlineExpansion>true</InlineExpansion>
   <CleanAttributes>true</CleanAttributes>
</PropertyGroup>

Plugins

If you want to incorporate external plugins into your obfuscation process, you can add a reference to them by adding an ItemGroup with BabelPlugin child elements as follow:

<ItemGroup>
   <BabelPlugin Include="BabelEncrypt.dll" />
</ItemGroup>
<PropertyGroup>
   <PluginArguments>dictionary=exclusionlist.txt</PluginArguments>
</PropertyGroup>

Where the PluginArguments property can be added to pass key-value pairs options to the referenced plugins.

Overriding Babel Task Configuration

The Babel Obfuscator NuGet package contains several MSBuild instructions that configure the Babel task according to the specific target assembly framework and build configuration. These instructions are designed to provide a default configuration that works for most scenarios. However, there may be cases where you need to override this configuration to suit your specific needs.

By creating a Task element named "BeforeObfuscate" in your project file, you can intervene in the build process before the Babel task is executed and modify its configuration. This allows you to customize the obfuscation settings, properties, or ItemGroup elements associated with the Babel task.

Here's an example of how you can define the "BeforeObfuscate" task and add custom properties or ItemGroup elements:

<Target Name="BeforeObfuscate">
  <!-- Add custom properties -->
  <PropertyGroup>
    <GenerateDebug>true</GenerateDebug>    
  </PropertyGroup>

  <!-- Replace Babel search directories -->
  <ItemGroup>
    <BabelSearchDirectories Remove="@(BabelSearchDirectories)" />
    <BabelSearchDirectories Include="$(TargetDir)" />
  </ItemGroup>
</Target>

Inside the BeforeObfuscate target, you can add custom properties and ItemGroup elements as per your requirements. These properties and ItemGroup elements can override or supplement the configuration prepared by the Babel Obfuscator NuGet package.

By adding custom properties and ItemGroup elements within the "BeforeObfuscate" target, you can customize the Babel task configuration to suit your specific needs. These customizations will be applied before the actual obfuscation process takes place.

You can add several properties related to the Babel Obfuscator NuGet package to your Visual Studio project file. These properties enable further customization of the obfuscation process, allowing you to tailor the output per your requirements. Further details about all the available properties can be found in the following section (NuGet Package Reference).