1. Introduction

To use ALox, you need to

compile the ALox library and
configure your project to use the library.

Altogether this should not be too difficult to set up and this does not differ from the use of other C# libraries.

Note: There is no NuGet packaged distribution of ALox for C# available today.

Currently, ALox provides ready to use IDE projects for

Microsoft Visual Studio,
Mono Develop and
JetBrains Rider

If you compile your C# code with a different build system, all you need to know is two things:

the list of source files and
which Conditional Compilation Symbols need to be set on compilation of debug and release configurations.

2. Download

Unpack the ALox distribution (e.g. as zip) from Alox at GitHub and move all its contents to a place where you commonly store 3rd party libraries your projects are using.

In this tutorial, we call this folder the ALOX_LIB_PATH. After downloading and unpacking ALox within the folder ALOX_LIB_PATH you should find at least the following subfolders:

    ALOX_LIB_PATH\src.cs
    ALOX_LIB_PATH\build
    ALOX_LIB_PATH\html

3. Set up the Build System

As mentioned above, for three different IDEs pre-configured projects exists.

Note

The Mono Develop projects have been created using V. 5.10 of the IDE
Microsoft claims that Visual Studio enables "round trip engineering" between Visual Studio versions 2010 and higher. We have not tested ALox with VS 2010, however, 2012 and 2013 both formerly worked well within our installation. Currently we use 2015.
The JetBrains IDE Rider was still in a beta stage when this got tested. It worked very well and should continue to do so.

You have to add the library projects to the solution that includes the project you want to equip with ALox.

If you do not actually have a C# project (or do not want to touch it now), there are ready to use sample solutions for Mono Develop and Microsoft Visual Studio available. They are found in:

ALOX_LIB_PATH/build/ide.cs.vstudio/Solution/ALox-CS.VStudio.sln
ALOX_LIB_PATH/build/ide.cs.monodevelop/Solution/ALox-CS.Mono.sln
ALOX_LIB_PATH/build/ide.cs.rider/Solution/ALox-CS.Rider.sln

Choose the right class library project that fits well to your own project target and platform.

Your, choices are:

Project Name	Description
ALox-CS-.Net45-DLL	For .Net 4.5 projects that do not use ALox release logging
ALox-CS-.Net45-DLL-Release-Log	For .Net 4.5 projects that intent to use ALox release logging (besides debug logging)
ALox-CS-.WP80-DLL	For windows Phone 8 projects that do not use ALox release logging
ALox-CS-.WP80-DLL-Release-Log	For windows Phone 8 projects that intent to use ALox release logging (besides debug logging)

Note: If you do not know the difference between debug and release logging, see the FAQ

Note

The difference between the project versions with or without the release logging options are:

Those projects named ALox-CS-???-DLL-Release-Log have the Conditional Compilation Symbols ALOX_REL_LOG set in their release configuration.
Due to this, ALox features are still included in the release version of these projects' assemblies. (Only, class Log gets its interface replaced by thin stub methods in release mode.).
The size of the release assembly slightly increases if you use the release log enabled projects.
Temporary or long-term pruning of the release Log Statements in your code is still enabled when you use the release log versions of the library!
Therefore: Only, if you never want to use release logging, choose the smaller library that only enables debug logging.

Note: The windows phone projects should support the Windows Phone 8.1 as well. Until ALox Version 1.1.2, support for Windows Phone 7.1 was officially provided. Due to problems in installing and testing this outdated platform, support was dropped. Nevertheless, there are still the appropriate Conditional Compilation Symbols in the C# source files. Although not tested, we are optimistic that this platform still compiles nicely. So, if you are in need for Windows Phone 7.1 logging, have a try.

Sounds complicated, but isn't! Just go with the release-log enabled version for now! Choosing the other one is indicated if distribution size matters.

Set a build dependency from your project to the just added ALox-CS-DLL project. and add the ALox-CS-DLL project as a reference to your project.

3.1. Alternatively: Working with the sources

If

there is no appropriate predefined project for your target and platform or
for any reason you want to setup your own library project for ALox or
for any reason you want to compile ALox directly within your project

the sources of ALox are found in the following two folders and their subfolders:

    ALOX_LIB_PATH/src.cs/alib
    ALOX_LIB_PATH/src.cs/alox

Unit tests (which do not belong into the library) are found in:

    ALOX_LIB_PATH/src.cs/alib.unittests
    ALOX_LIB_PATH/src.cs/alox.unittests

3.2. Conditional Compilation Symbols

Now, as ALox is a part of your IDEs solution or build system, the final step is to set compilation symbols within your own project (!), hence the one that is supposed to use ALox. Different settings are needed for the debug and release configurations.

Please find an overview over all compilation symbols introduced by ALox here: Conditional Compilation Symbols.

The following step by step guide examples this for Visual Studio:

Note: In addition, the right system libraries may have to be chosen to successfully compile ALox and your project!

Open your projects' properties and:
- choose "Debug" as the Configuration you want to modify.
- In the 'Build' section add ALOX_DBG_LOG to the list of conditional compilation symbols (separated from existing symbols by a semicolon).
- Make sure that the checkbox "Define DEBUG constant" is checked (this is the default).
- For windows phone projects, also add either ALOX_WP71 or ALOX_WP8 to that list depending on what platform you are targeting.
  Note: Besides other minor changes, this disables a feature to recursively log an object using reflection, because reflection operations are not supported (permitted!) on the Windows Phone platform.
- If you want to use ALox for release logging (see FAQ) then you do the same for the "Release" configuration. But, instead of ALOX_DBG_LOG please specify ALOX_REL_LOG.
Now close the project properties and continue with adjusting the references of your project:
- In Solution Explorer, right-click the "References" folder in your project
- choose "Add Reference..."
- In the now open dialog navigate to section "Assemblies" and here choose "Framework".
  
  Make sure that you have ticked the check boxes for:
  - System.Xml.Linq library (you can avoid this by setting the conditional compilation symbol ALOX_NO_XML, see above)
  - For Windows Phone 7.1 projects: "Microsoft.Phone" (not needed for Windows Phone 8)
For Windows Phone 7.1 projects (not needed for Windows Phone 8) you need to download and install the Microsoft BCL Portability Pack Using the NuGet package manager as described on the libraries' page. This should be a matter of just a minute.

3.3. Test your setup

To test your setup, add minimum ALox functionality to your project as described in the first chapter of ALox for C# Tutorial into your main method or anywhere you think it is appropriate:

    Log.Info( "Hello ALox" );

You are set if:

your project compiles and runs without error
you see the log output when running the debug version
you do not see the log output when running the release version

4. Tweaking The Log Output

In addition to setting up the project, the format of the log output of ALox should be recognizable by your IDE: the source code file name and line number that generated the output should become "clickable" in the log: It should link back to the source in the editor.

While different IDEs have different abilities and syntax for that, unfortunately, there are some IDEs that do not support such "clickable log output" at all.
This chapter gives some tips for different IDEs. We hope that the IDE you are using is listed here and it supports this feature. Otherwise, it may need a little testing, maybe some trial and error process, to see how the output needs to be done to be properly consumed by your IDE.

4.1 Microsoft Visual Studio

As far as we know, clickable log output is only possible to have when launching a project in debug mode. In this case, ALox automatically adds a second logger of type CLRDebuggerLogger. (This is the default behavior by default, implemented with method Log.AddDebugLogger.)

This logger does everything right to have clickable log lines in Visual Studio. No adjustments need to be done.

4.2 MonoDevelop

MonoDevelop does not support linking log output back to source code. Also, no colorful log output is supported. The configuration should reflect this and suppress colorful loggers by setting variable ALOX_CONSOLE_TYPE to "plain".

CONSOLE_TYPE=           plain

4.2 Rider

JetBrains Rider has an intelligent output console that supports ANSI colors and detects links to files when they are given with full path name.

There is one specialty about the ANSI color support: Rider does not support light colors. Therefore, the use of light colors has to be switched off. If this is not done, colors are in most cases not effective.

Furthermore, the use of an C# CLRDebuggerLogger needs to be switched off. This is done by setting configuration variable NO_IDE_LOGGER.

As a summary, these or similar configuration variable settings are recommended:

[ALOX]
NO_IDE_LOGGER=          true
CONSOLE_TYPE=           ANSI
CONSOLE_LIGHT_COLORS=   never
DEBUG_LOGGER_FORMAT=    %SF(%SL):%A5%SM() %A5[%TC +%TL][%tN][%D]%A1(%#): %V,    \
                        \e[31m,                                                 \
                        \e[34m,                                                 \
                        ,                                                       \
                        \e[33m

Table of Contents