The logging framework is initialized at run-time by using one of the following configurator classes (or by writing your own):
| Class | Description |
|---|---|
| BasicConfigurator | Configures the logging framework to write errors to the console. |
| PropertyConfigurator | Configures the logging framework by reading settings from a text file. |
| ModulePropertyConfigurator | Configures the logging framework by reading a text file, whose name and location is relative to the currently executing module. |
| XllConfigurator | Configures the logging framework by reading a text file, whose name and location is relative to the XLL add-in. |
For an XLL add-in, the XllConfigurator is the best choice.
The configure() method takes one optional argument:
CopyC++static bool XllConfigurator::configure(bool bIgnoreMissingFile=true);
For an XLL C:\MyAddinDir\MyAddin.xll, the XllConfigurator
will look for a configuration file C:\MyAddinDir\MyAddin.xll.log.ini.
If it fails during configuration, it will (i) display an error message
(ii) write the error to an error file and (iii) return false.
If it succeeds, it will return true.
If you pass true for bIgnoreMissingFile, then a missing configuration file will not be treated as an error. The process will fail elegantly: logging will not be started, but no error code will be returned. If bIgnoreMissingFile is false, then a missing configuration file will be treated as an error.
Your OnXllOpenEx() method should call XllConfigurator::configure()
and should handle the return value appropriately, by immediately returning FALSE
if XllConfigurator::configure() returns false.
This will prevent the add-in from loading.
See the LogDemo sample for an example
of this configuration pattern.
XLL+ AppWizard
If you select Enable Logging in the XLL+ AppWizard, your new add-in project will contain code to initialize the logging framework and also a log configuration file.