Figaro - The XML Database for the .NET Framework

Berkeley DB XML throws a combination of Berkeley XML DB, Berkeley DB and std::exception objects whenever error conditions occur. Because the Figaro library acts as an intermediary between Figaro and the .NET Framework, these exceptions are wrapped in custom .NET exception classes before being re-thrown. In some cases, Figaro will perform simple validation tests in advance and throw a .NET Framework exception; for example, most method arguments undergo a basic validity check before method call in order to prevent problems with the Berkeley DB XML subsystem. For more information about these conditions, consult with the API documentation.

Debugging Figaro Applications

In some cases, the exceptions thrown by your Figaro application may not contain enough information to allow you to debug the source of an error. In this case, you can cause Figaro to issue more information using the messaging and error streams.

The Figaro library allows access to these environments through two mechanisms – file output and events. Configuring file output is as simple as calling the SetErrorFile and/or SetMessageFile methods. Calling these methods will initialize output to the files specified; if files already exist with the names given, they will be overwritten. Turning off file output requires calling the same method with a null parameter.

For example:

CopyC#
using Figaro.BerkeleyDB.Xml;
namespace Figaro.Documentation.Examples
{
    class Debugging
    {
        static void Main()
        {
            //NOTE: XmlManager is going to adopt this, so don't explicitly dispose it at the end
            FigaroEnv env = new FigaroEnv();
            env.SetVerbose(VerboseOption.AllFileOps, true);

            //set the error file to turn on error logging - set to null to turn off
            env.SetErrorFile(@"C:\dev\db\DebuggingDemo\debugging.log");
            env.SetMessageFile(@"C:\dev\db\DebuggingDemo\debugging-messages.log");
            env.Open(@"C:\dev\db\DebuggingDemo\", EnvOpenOptions.Create);

            //set the global log categories to log everything
            LogConfiguration.SetCategory(LogConfigurationCategory.All,true);
            LogConfiguration.SetLogLevel(LogConfigurationLevel.All, true);

            //get our manager
            using (var mgr = new XmlManager(env,ManagerInitOptions.AdoptFigaroEnv |
                        ManagerInitOptions.AllowExternalAccess | ManagerInitOptions.AllowAutoOpen))
            {
                //open a container
                using (var container = mgr.OpenContainer(baseUri + testdb))
                {
                    try
                    {
                        //turn off logging 
                        env.SetMessageFile(null);
                        env.SetErrorFile(null);
                        /*your app code goes here*/
                    }
                    finally
                    {
                        container.Close();
                    }
                }
            }
        }

If you wish to display the output, you may consider capturing the output as an event in your application. For example:

CopyC#
using System;
using Figaro.BerkeleyDB.Xml;

namespace Figaro.Documentation.Examples
{
    class DebugEvents
    {
        static void Main()
        {
            FigaroEnv env = new FigaroEnv();
            env.SetVerbose(VerboseOption.AllFileOps, true);
            //set the error event - set to false to turn off
            env.ErrEventEnabled = true;
            env.MessageEventEnabled = true;
            env.OnErr += env_OnErr;
            env.OnMessage += env_OnMessage;

            env.Open(@"C:\dev\db\DebugEvents\", EnvOpenOptions.Create);
            LogConfiguration.SetLogLevel(LogConfigurationLevel.All, true);
            LogConfiguration.SetCategory(LogConfigurationCategory.All, true);

            //get our manager
            using (var mgr = new XmlManager(env,ManagerInitOptions.AdoptFigaroEnv
                |ManagerInitOptions.AllowExternalAccess | ManagerInitOptions.AllowAutoOpen))
            {
                prepareContainer(true);
                //open a container
                using (var container = mgr.OpenContainer(baseUri + testdb))
                {
                    try
                    {
                        Console.WriteLine("container has {0} documents.", container.GetNumDocuments());
                        // add a container alias if your container is not in 
                        // the same directory as your application
                        container.AddAlias("testdb");
                        /* your app code goes here */
                    }
                    finally
                    {
                        container.Close();
                    }
                }
            }
        }

        static void env_OnErr(object sender, ErrEventArgs args)
        {
            Console.WriteLine("Err event | {0}", args.Message);
        }

        static void env_OnMessage(object sender, MsgEventArgs args)
        {
            Console.WriteLine("OnMessage | {0}", args.Message);
        }

See Also