Using the GUI
Note: The following instructions cover both the Professional Edition and the Community Edition of Dotfuscator
The following instructions will walk you through using Dotfuscator to protect apps made with Unity. You can apply these steps to each platform your app supports, creating an app with a proven, layered protection strategy, no matter what device it's running on.
In order to follow along with these instructions you will need the Unity-supplied Space Shooter example project or you can follow along with your own project and use this guide as a reference for adding protection.
You will also need to install Dotfuscator if you do not already have it. To do so, see Dotfuscator Editions to learn which Edition is best suited for your project, and see the Dotfuscator Downloads page to get the latest version of your selected edition of Dotfuscator.
If you already have Dotfuscator, please verify that you have a version that supports Unity.
|Dotfuscator Edition||Minimum Version for Unity|
Dotfuscator supports Unity projects that target the following platforms:
After you have Dotfuscator installed you will need to set up the example project. This guide uses the Space Shooter tutorial available on Unity's website.
On the Asset Store page:
SpaceShooterand the location is
Find the _Complete-Game directory in the Assets directory of the project. Click on the
_Complete-Game scene to bring it into the Scene tab, and then click the play button. Take a moment to play the game in the preview so you will be able to tell if anything is not working later in the protected version.
In the file menu click on
Build Settings to open the build settings window. Add the
_Complete-Game scene to the "Scenes the Build" by clicking the
add open scenes button.
The general process for protecting Unity applications with Dotfuscator is the same across all the supported platforms, with the exception of a few platform specific steps. There are links to platform specific instructions from these general instructions when they are necessary.
Steps 1-7 will give basic protection to the application. Step 8 will add more protection to harden the app even further.
To build the application that will be protected by Dotfuscator, first select the platform to build, then set the necessary player settings for the selected platform, and lastly build and save the Unity produced app.
To change the build platform in Unity, select
Build Settings to open the build settings window. The list of platform options will be on the left. Select the desired platform and click the 'Switch Platform' button.
Unity offers the option of three different scripting backends depending on target platform: Mono, .NET and IL2CPP.
The first two scripting backends, Mono and .NET, produce managed code which can be easily reversed engineered. (See the viewing an unprotected assembly example to see how easy it is)
The Mono and .NET scripting backends combine all the C# scripts written for the project into one dynamic linked library, called Assembly-CSharp.dll. The Assembly-CSharp.dll is what needs to be protected with Dotfuscator.
IL2CPP as a scripting backend does not produce output that can be used as an input to Dotfuscator.
The scripting backend can be set by clicking on the
Player Settings... button in the Build Settings window. Under the "Configurations" section is the drop down menu for selecting the scripting backend. Select the appropriate scripting backend for your project.
See the Unity documentation for more information on scripting backends.
The iOS Platform and the Android Platform require additional configuration. Please see the following sections for details:
Once everything for the build is configured in Unity, press the "Build" button in the "Build Settings" window. See the section on Building for Windows Store Inputs for platform specific details.
If you haven't built for another platform already, create a new directory in
C:\Unity\SpaceShooter called "Builds" where we will store the build output for all the platforms we build in this example.
C:\Unity\SpaceShooter\Builds create a directory with the name of the platform and select this directory as where to save the build output. Set the file name to be SpaceShooter if it is required for building on your current platform. For example the output for a Standalone platform build will be in
C:\Unity\SpaceShooter\Builds\Standalone and the executable will be named
Then build the project for the specified platform by pressing "Save".
Open the Dotfuscator Gui and add the input by following instructions for Professional Edition or Community Edition. The correct input will depend on the target platform. See the following sections for details:
If you are following along with your own app the input will be in a similar location.
If you are using Dotfuscator Professional Edition go to the settings tab, under the Advanced section, and change "Use only Mono-compatable-transforms" from 'No' to 'Yes'.
Save the Dotfuscator project in
C:\Unity\SpaceShooter\Builds\<Platform>, and give it any name you would like. This Dotfuscator config file can be used to reopen the Dotfuscator project for this platform later.
See the Windows Store Dotfuscator Configuration section for an additional setting for Windows Store Universal 10 apps.
Now, you are ready to press the build button in the Dotfuscator GUI. Verify that the build was successful by looking in the output at the bottom of the GUI.
Next to the build button is a button with an arrow on it. Pressing this will take you to the location of Dotfuscator's Output.
After you've found the output from Dotfuscator, copy it and go back to the original location of the input
Assembly-CSharp.dll. Replace the unprotected
Assembly-CSharp.dll with the protected version you copied from Dotfuscator's output.
The Windows Store platform skips this step.
Now that we've built a protected version of the
Assembly-CSharp.dll, we need to build the entire app that uses it. Instructions on how can be found in the platform specific sections:
The Standalone platform skips this step.
Try out the app on your computer, device, or emulator to verify the app's behavior with protection added. If there are issues, this most likely means that you need to add additional renaming exclusions beyond library mode. Please see the protection exclusions page for additional details on the workflow for identifying renaming exclusions.
Now that your app is working with basic protection, you can increase the strength of the protection by following the steps below.
First, in Dotfuscator you will want to turn off library mode for the
Assembly-CSharp.dll. This step will make the obfuscation on the assembly more aggressive.
In Dotfuscator Professional, click the plus sign next to the assembly to expand the options. Then uncheck "Library" to turn off library mode. If you are using Dotfuscator CE, click on the assembly, and then to the right in the properties section uncheck Library mode.
We can improve protection by turning off Library Mode, but that will un-exclude some things that need to be excluded, so we need to add specific exclusion rules to cover those things.
For more information on renaming in Dotfuscator Professional see:
For information on renaming in Community Edition see:
It is neccessary to exclude:
After this, all public methods that weren’t specifically excluded will be renamed, which is an improvement over when we had Library Mode turned on. To add these exclusions follow the steps bellow. When you are done your renaming tab page should look like the following:
To add the necessary renaming exclusions :
+publicattribute in the Attribute Specifier for that type. This takes care of excluding all public types in the assembly.
.*Update. The names are regular expressions so they will cover all the methods listed above. For example
.*Updatewill cover both Update() and FixedUpdate() methods.
You can verify this by selecting the method and then pressing "Preview". In the tree view of the inputs on the left you will see both of those types highlighted.
These exclusion rules aren't just important for the Space Shooter app, they can and should also be excluded from renaming in your own apps you build with Unity. See the general workflow for identifying renaming exclusions for finding and configuring additional renaming exclusions that may also be needed for your own app.
Since not all the methods are able to be renamed its important to keep this in mind when you are writing the scripts for your project. Try to keep any critical code out of methods that have to be excluded so it is not as easy to find.
See the Windows Store specific exclusions if you are targeting that platform.
For the Standalone platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator. For the Space Shooter example this can be found in the
These instructions assume you are using Unity on Windows but all the steps should be similar if you are using Unity on a Mac.
After the platform and scripting backend are set, you will also have to configure the build for the device you plan to test the app on. In Player Settings below where the scripting backend was set in the 'Configuration' section, change the Target SDK to either Simulator or Device depending on which you are going to test the application on.
For the iOS platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator. For the Space Shooter example this can be found in
Unity produces an XCode project which you use to build the actual iOS app. Before you can build the XCode project you need to update the
C:\Unity\SpaceShooter\Builds\iOS\Libraries by using Ahead of Time Compilation or AOT on the protected version of the Assembly-CSharp.dll.
To create a compatible version of the Assembly-CSharp.dll.s
C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcomiler.exe. The steps below assume you have Unity installed on Windows.
/Applications/Unity/PlaybackEngines/iOSSupport/Tools/OSX/mono-xcompilerand you can run a similar version of the following steps. Note you will need to use
SETXin step 3.
C:\Unity\SpaceShooter\Builds\iOS) open a new command prompt.
SETX MONO_PATH "Data\Managed" SETX GAC_PATH "Data\Managed" "C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcompiler.exe" --aot=full,static,nodebug,asmonly,outfile="Libraries/Assembly-CSharp.dll.s" "Data/Managed/Assembly-CSharp.dll"
Assembly-CSharp.dll.sis located in
Now that there is a new version of the
Assembly-CSharp.dll.s, you'll need to copy
C:\Unity\SpaceShooter\Builds\iOS\ over to a Mac in order to be able to build the XCode project.
Open the XCode project called
Unity-iPhone.xcodeproj located in
If XCode suggests you "Update the project to recommended settings", don't do it. For this example updating may cause the app not to work.
Build the XCode project and from here you can also test the app on a device or an Emulator to see that Space Shooter works as expected.
Open the player settings window by clicking on the 'Player Settings' button in the "Build Settings" window. The player settings window will be to the right in the regular Unity window. In the player settings window, set the Package Name in the Identification section above the Configuration section (where you set the scripting backend) to be
com.Company.SpaceShooter. Then at the top of the Player Settings change the company name to Company and the product name to SpaceShooter.
To access the Assembly-CSharp.dll you will have to decompile the APK that Unity produced.
Download and set up APKtool with the instructions from the APKTool install page
In a command prompt in the directory that the APK is in,
C:\Unity\SpaceShooter\Builds\Android, run the command:
apktool d SpaceShooter.apk
The Assembly-CSharp.dll can now be found in
After replacing the unprotected assembly with the protected assembly, you must rebuild and re-sign the APK with the protected assembly.
In the command prompt window from when you decomiled the APK run the following command to rebuild the APK
apktool b SpaceShooter -o SpaceShooter.apk
Sign the app using your keystore and the jarsigner tool If you don't already know how to do this, for this example project you can enter the command:
keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
Remember the password you set, and fill in appropriate values for your project.
Sign the APK by executing:
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore SpaceShooter.apk alias_name
Once that is done, you can install the APK on your Android device or Emulator and test out the Space Shooter app verify its behavior.
For the Windows store platform instead of using the "Build" button, use the "Build and Run" button. The input used for Dotfuscator will be created by doing this instead and you won't have to manually open up Visual Studio to build the Appx.(You can still build from Visual Studio if you want to)
If you built and ran the application from Unity then the input can be found in the directory
C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppX. If you build yourself from visual studio, the
AppX directory will be located similarly based on what configuration you built the project in.
See the Windows store inputs page for instructions on adding this input.
Exclude everything from the package except the Assembly-CSharp.dll by left clicking on the assemblies and selecting "Exclude assembly from package". You should see all the assemblies you excluded show up in "Package Artifacts".
If you are using the Universal 10 SDK for the Windows Store platform there is an additional configuration setting required. In the "Settings Tab", add the Project Property
ilreader.alias_system_runtime.never with the value
0. See the Project Properties section for details on how to add Project Properties.
For a more permanent solution you can follow this article on integrating Dotfuscator into the Appx build.
To test protecting a Windows Store app in development:
To build the Appx from the output from Dotfuscator, first locate the MakeAppx tool, usually it can be found somewhere like
C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe.
Then open a command prompt and execute the command
"C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe" pack /d "C:\Unity\SpaceShooter\Builds\Windows\Dotfuscated" /p "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx" /l
This will save the Appx in the
Note: Make sure you don't include your map file in with the Appx.
The next step is to sign the Appx so you will be able to install it to test it. You can see the Microsoft documentation for help on this step.
Next, use SignTool to sign the application with the certificate.
In the Administrator PowerShell command prompt execute the following commmand to install the Appx to test:
add-appxpackage -path "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx"
Windows Store platform apps need a few extra renaming exclusions that the other platforms don't need.
It is neccessary to additionally exclude:
UnityEngine.Internalin the Assembly-CSharp.dll
UnityEngine.Internal.Typesin the Assembly-CSharp.dll
To exclude all types:
To add the namespaces to the renaming exclusions:
C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppXnode , then Assembly-CSharp.dll below it, then expand the Assembly-CSharp.dll listed under that
If you have any trouble finding the necessary settings mentioned in these instructions in Unity, please refer to the Unity Documentation.
These instructions focused mainly on renaming exclsions, but Dotfuscator offers additional protections beyond renaming. Check out and explore the quickstart guide, Professional Edition documentation, and Community Edition documentation for information on all the other protection available for your apps.
We on the Dotfuscator team are always adding new features to improve the protection provided by Dotfuscator, as well as making the configuration process easier. Stay up-to-date with the latest Dotfuscator version by visiting the Dotfuscator Downloads page. For announcements and other information, keep an eye on our blog and follow our Twitter account, @PreEmptive.
Dotfuscator Version 188.8.131.5291. Copyright © 2017 PreEmptive Solutions, LLC