Pruning ALox Code in C# from Release Builts

Table of Contents

• 1. What is Pruning?
• 2. How Pruning in ALox for C# works
• 3. Mission accomplished: Perfect Auto Pruning with ALox!

1. What is Pruning?

An introduction to the concept of pruning is given in FAQ: What is Pruning?.

2. How Pruning in ALox for C# works

Since Version 5, the Microsoft C# compiler supports methods to be annotated with class "ConditionalAttribute". This attribute uses a conditional compilation symbol which causes the compiler to ignore the invocation of methods when the symbol is not set. Again: the invocation of the methods is disabled, not the compilation of the methods itself!

Consider the following line of code:

Log.SetVerbosity( new ConsoleLogger() );

Method Log.SetVerbosity() is annotated as conditional using the symbol ALOX_DBG_LOG. Now the compiler does not include this line into the executable when ALOX_DBG_LOG is not set.

However, the compiler still checks the integrity of the parameter. Therefore, ALox provides empty method stubs for the most common classes and a few of their methods, even in the release configuration. To be able to compile the sample above in release mode, we need

• a class ConsoleLogger
• a constructor of class ConsoleLogger taking a String object

In the release version, both are empty "stubs" of their original classes. The reason why ALox creates stubs is to minimize the footprint of ALox in the moment it is not used (in the deployed applications that do not do release logging). Members of classes that are not too frequently used are not available in the release.

Consider the following code to setup the format of a log line:

ConsoleLogger cl= new ConsoleLogger();
cl.MetaInfo.Format= new AString( "%SF(%SL):%SM()%A3[%DD][%TD][%TC +%TL]%V[%D]<%#>: ");
Log.SetVerbosity( cl, Verbosity.Verbose );

This would lead to a compilation error in the release configuration of your project (if you do not use release logging). The reason is, that the field MetaInfo is not included in the release version of ALox. In fact, the whole class MetaInfo is not existing!

To resolve this, use conditional compilation for all non-standard code specific to ALox logging:

ConsoleLogger cl= new ConsoleLogger();
#if ALOX_DBG_LOG
    cl.MetaInfo.Format= new AString( "%SF(%SL):%SM()%A3[%DD][%TD][%TC +%TL]%V[%D] <%#>: ");
#endif
Log.SetVerbosity( cl, Verbosity.Verbose  );

While this is sufficient, in the last sample, when compiled in release configuration, there is an almost empty version of ConsoleLogger still created and never used. Therefore, you might want to do it like this:

#if ALOX_DBG_LOG
    ConsoleLogger cl= new ConsoleLogger();
    cl.MetaInfo.Format= new AString( "%SF(%SL):%SM()%A3[%DD][%TD][%TC +%TL]%V[%D] <%#>: ");
    Log.SetVerbosity( cl, Verbosity.Verbose );
#endif

This sample shows, that only for the configuration/bootstrap part your code gets "cluttered" with #if ... #endif statements. And: As long as you do not get compiler errors in the release version, you can trust ALox that the impact of remaining configuration code is minimal. Again: standard logging code is always removed 100%!

3. Mission accomplished: Perfect Auto Pruning with ALox!

The result of the things said above incorporate six great news for you:

1. You can safely use most methods of class Log without enclosing them by #if ... #endif statements!
2. The impact of using ALox debug Log Statements in respect to execution speed in the release version of your application is exactly ZERO, because the methods do not make it into your release executable!
3. The impact of using ALox in respect to the footprint of your executable extremely small (all that remains are some empty classes with a few stubs). This remains true, even if thousands of new features would come in future versions of ALox!
4. All debug Log Statements, including all textual messages you are adding to your log calls, are completely pruned from the release executable! Your "debug secrets" can not be reverse engineered, they are just gone!
5. You do not need to clutter your code with #if ... #endif statements if using ALox! Only within some "bootstrap sections".
6. Even if you mix debug and release logging features of ALox the above stays true, except that the footprint of the ALox library is a little higher (e.g. it is 50kb in V1.1.0) !

Note

This is all true for C#. For other platforms check out platform specific sections of ALox pruning techniques.