Identify Renaming Exclusions

This page explains how to identify exclusions that need to be configured. This example is focused on renaming, but the concepts can be applied to other protections as well. The example used here is for a Xamarin application, but the workflow can be applied to all applications you are protecting.

There are multiple reasons why an application would need to have renaming exclusions. One of the common reasons is some frameworks, for example Xamarin, rely heavily on reflection, which assumes that names of types and members at compile time remain the same at runtime. Dotfuscator's renaming protection applies various rules to ensure proper behavior with these scenarios. As rule improvements are introduced with releases of Dotfuscator, many cases may be handled automatically, especially if you have the latest version of Dotfuscator.

However, there may be some cases that Dotfuscator cannot detect. When this happens, you will have to exclude the problematic code items from renaming in order to maintain correct behavior of the app.

The exact renaming exclusions needed vary significantly from app to app.

General Workflow

To configure Dotfuscator's renaming protection:

1. Enable Renaming. See the Settings Tab for details.

2. Make renaming exclusions using the Renaming Editor.

3. Build the Dotfuscator config.

4. Run the obfuscated app and test its behavior.

5. Investigate any issues by consulting device logs, exception messages, or other diagnostic tools.

6. Repeat from step 2 to continue making renaming exclusions as appropriate until the app functions normally.

Detailed Example

The advice above outlines the basics of making renaming exclusions, but it helps to have an example. Here's a detailed set of steps we took to determine renaming exclusions for BugSweeper.Android, the sample used on the Xamarin Getting Started page.

Note that these instructions were written against Dotfuscator Professional 4.33. Newer versions of Dotfuscator may require fewer exclusions for this example.

1. When we launched the protected BugSweeper.Android app on an Android device, the app ran. However, we noticed the text that reports how many bugs are left to find (e.g., "Flagged 2 out of 10 bugs.") was not updating as we played the game:

   

2. In our source code we noted that the BugSweeperPage.xaml file defines this text using two labels, each with a BindingContext to the board field:

   <StackLayout Orientation="Horizontal" Spacing="0" VerticalOptions="CenterAndExpand" HorizontalOptions="Center">
      <Label BindingContext="{x:Reference board}" Text="{Binding FlaggedTileCount, StringFormat='Flagged {0} '}" />
      <Label BindingContext="{x:Reference board}" Text="{Binding BugCount, StringFormat=' out of {0} bugs.'}" />
   </StackLayout>
   

3. We decided the issue must be due to the BugCount property being renamed. We excluded this manually from the Dotfuscator Config Editor.

   

4. We built and redeployed BugSweeper.Android. This time the app ran, and there were no problems when playing, winning, or losing the game.

   

5. We committed the change we've made to DotfuscatorConfig.xml to local version control.

Extra Tips

1. With Xamarin, after enabling USB debugging on the phone, open Android device log in Visual Studio to see detailed logs about possible errors. Filter the log down to just Error and Warning for clarity.

   

   

2. If an error occurs inspect the stack trace to locate the source of the error. You may have to cross reference with the renaming map file to discover the original name of the function. For example, given a stack trace as follows:

   Caused by: android.runtime.JavaProxyThrowable: System.Exception: Can't resolve name on Element
    at Xamarin.Forms.Xaml.ReferenceExtension.ProvideValue (System.IServiceProvider serviceProvider) [0x000b6] in <cdab8e5cc6744897b152dd4075cc1cb0>:0 
   ...
    at Xamarin.Forms.Xaml.Extensions.LoadFromXaml[TXaml] (TXaml view, System.Type callingType) [0x00000] in <cdab8e5cc6744897b152dd4075cc1cb0>:0 
    at BugSweeper.BugSweeperPage.b () [0x00000] in <7a7fbb7c3c1f42e59202c72d51d629fe>:0 
    at BugSweeper.BugSweeperPage..ctor () [0x00006] in <7a7fbb7c3c1f42e59202c72d51d629fe>:0 
    at BugSweeper.App..ctor () [0x00006] in <7a7fbb7c3c1f42e59202c72d51d629fe>:0 
    at BugSweeper.Droid.MainActivity.OnCreate (Android.OS.Bundle bundle) [0x0000e] in <bf5a3ea557124c988f94e73e801e2727>:0
   ...
   

   Based on this stack trace, we can see the error happened in a method named b() on type BugSweeper.BugSweeperPage. As the BugSweeper source code doesn't have a method by that name on that type, we can deduce this must be an obfuscated name. Open the renaming map file (C:\code\BugSweeper\BugSweeper\BugSweeper.Android\DotfuscatorReports\Release\Renaming.xml) and look up the appropriate module (BugSweeper.dll), name (BugSweeper.BugSweeperPage), and method (new name of b):

   <mapping>
      <module>
          <name>BugSweeper.dll</name>
          <type>
              <name>BugSweeper.BugSweeperPage</name>
              <methodlist>
                  <method>
                      <signature>void()</signature>
                      <name>InitializeComponent</name>
                      <newname>b</newname>
                  </method>
              </methodlist>
          </type>
      </module>
   </mapping>
   

   The map file indicates the original name of this method is InitializeComponent. This would be a good place to start looking for the source of the error.