After working out some of the minor issues with log4net-altconf and dropping a load of code up there on google code I thought it would be a good idea to put together a Getting Started post, to get you up and running, so here goes:
Running from Source
- You will firstly need to get the source code onto your machine, this can be done via an SVN client I use TortoiseSVN, the source can be found here http://code.google.com/p/log4net-altconf/source/checkout Built using visual studio 2008
- Once you have the source on your machine open up the solution in vs2008 and perform a build.
- There is a unit testing project provided, before trying to run the unit tests you should go through instructions located here http://code.google.com/p/log4net-altconf/wiki/TestDslsInNUnit Uses NUnit 2.4.7
Running from Binary
- Either download the binary release from here http://code.google.com/p/log4net-altconf/downloads/list or grab the source using step 1 from Running from Source then run nant against the folder with default.build in it requires nant 0.86. The binary files will be put in a build folder.
Adding to Project
You can add a reference to log4net-altconf via a project reference if you want to work from source or by just adding a binary reference to the log4net.altconf assembly.
If you have used log4net in the past you should be used to the idea of setting up the configuration of log4net at application startup, this will generally be one of the following:
- Application_Start in Global.asax for web projects
- Inside Main function for windows / console based projects.
The configuration for log4net-altconf follows the same method only instead of XmlConfigurator you use DslConfigurator, this object has property BaseDirectory and a method Configure, you would use them as follows:
DslConfigurator.BaseDirectory = // path to config file here DslConfigurator.Configure("logging.boo");
This tells log4net-altconf the path to look for the config file and then the name of the file is passed to the Configure method.
Unlike XmlConfigurator which has a ConfigureAndWatch method to keep track of file changes, DslConfigurator will implicitly keep track of changes made to the file and will reload the config if changes are made, not sure why you would not want this.
Creating a Configuration File
This is the next stage which is were you configure the settings log4net should use, there is nothing special about the configuration file it is simply at text file, generally I have tended to use .boo as the file extension however this is not compulsory.
The config file is generally split into 3 areas from top to bottom:
- The top area is where I generally like to set the global options for log4net i.e. internal debugging. I also use it for declaring any variables I would like to re-use further on.
- The next area is where your appenders are setup and configured.
- After that is where the actual logs should be placed.
Let’s take a look at an example configuration:
# globals and variables debug = true # appenders section add_appender @MyAppender, ConsoleAppender: Target = "Console.Error" # logs section log_for 'root': with_appenders: @MyAppender at_level ERROR
This should look fairly intuitive, you can find more in depth details about the syntax here http://code.google.com/p/log4net-altconf/wiki/DslKeywordsIdentifiers. Using these details you should be able to put together a configuration file that can be used.
Your now ready to try out logging, you do this the same way you would normally by using the LogManager method GetLogger() I generally stick to using the type of the caller as the argument so it would look like this LogManager.GetLogger(this.GetType()), once you have the returned ILog you can call the methods on it like you would normally such as log.Debug(“foo”).
If you aren’t receiving output to your appenders when you think you should turn internal debugging on by using debug = true in the config file, this should help track any problems.
There is one other point to make if you planning on using this in a web project and this would also affect using the standard XML configuration for log4net in that if you have your configuration file inside you web folder it can be requested and its content brought back to the user, not good! In order to restrict this please read this http://code.google.com/p/log4net-altconf/wiki/RestrictWebFileAccess