|
From: Mark P. <mar...@us...> - 2007-10-10 19:13:09
|
Update of /cvsroot/springnet/Spring.Net/doc/reference/src In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv1032 Modified Files: dbprovider.xml logging.xml Log Message: SPRNET-667 - Update Common.Logging documentation to point to NetCommon sourceforge project web site. SPRNET-747 - Add description of how to do assembly redirects for database assemblies. Index: logging.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/logging.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** logging.xml 3 Jan 2007 12:49:29 -0000 1.2 --- logging.xml 10 Oct 2007 19:13:01 -0000 1.3 *************** *** 9,383 **** of indirection between logging calls made by Spring and the specific logging library used in your application (log4net, EntLib logging, NLog). ! Many other .NET projects have done a similar task. As such this library is ! to be moved out of the Spring project and into a more general open source ! project. Stay tuned for further information.</para> ! ! <para>This logging abstraction goes by the name 'Common.Logging' and is ! simply a more packaged version of the logging abstraction used inside the ! iBATIS project. Many thanks to them! The library is available for .NET ! 1.0, 1.1, and 2.0 with both debug and strongly signed assemblies.</para> ! ! <para>Spring ships with the base logging library, Common.Logging, that ! provides console and trace based loggers. The libraries are located under ! lib/logging. There are two enterprise logging implementations, one for ! log4net 1.2.9 and another for log4net 1.2.10. The need for two log4net ! versions is due to the fact that each is signed with a different strong ! key making assembly redirection impossible.</para> ! ! <para>Note that it is not the intention of this library to be a replacement for the many fine logging libraries that are out there. The ! API is incredibly minimal and will very likely stay that way. Only use ! this library if you truely need to support multiple logging APIs.</para> ! </section> ! ! <section id="logging-usage"> ! <title>Using Common.Logging API</title> ! ! <para>Usage of the Logging API is fairly simple. First you need to obtain ! a logger from the LogManager and call the appropriate logging ! method:</para> ! ! <programlisting>using Common.Logging; ! ... ! ILog log = LogManager.GetLogger(this.GetType()); ! log.Debug("hello world");</programlisting> ! ! <para>A logger instance provides the following methods for logging:</para> ! ! <programlisting>public interface ILog ! { ! void Debug( object message ); ! void Debug( object message, Exception exception ); ! void Error( object message ); ! void Error( object message, Exception exception ); ! void Fatal( object message ); ! void Fatal( object message, Exception exception ); ! void Info( object message ); ! void Info( object message, Exception exception ); ! void Warn( object message ); ! void Warn( object message, Exception exception ); ! ! bool IsDebugEnabled { get; } ! bool IsErrorEnabled { get; } ! bool IsFatalEnabled { get; } ! bool IsInfoEnabled { get; } ! bool IsWarnEnabled { get; } ! }</programlisting> ! ! <para>You can get a reference to an instance of an ILog using the ! LoggingManager class. Its API is shown below:</para> ! ! <programlisting>public sealed class LogManager ! { ! public static ILog GetLogger( Type type ) ... ! public static ILog GetLogger( string name ) ... ! ! public static ILoggerFactoryAdapter Adapter ... ! ! }</programlisting> ! ! <para>The Adapter property is used by the framework itself.</para> ! </section> ! ! <section id="logging-config"> ! <title>Configuring Logging</title> ! ! <para>There are 2 ways of configuring logging in your application - either ! declaratively or programmatically.</para> ! ! <section> ! <title>Declarative Configuration</title> ! ! <para>Logging configuration can be done declaratively in your ! app.config</para> ! ! <programlisting><configuration> ! <configSections> ! <sectionGroup name="common"> ! <section name="logging" type="Common.Logging.ConfigurationSectionHandler, Common.Logging" /> ! </sectionGroup> ! </configSections> ! ! <common> ! <logging> ! <factoryAdapter type="Common.Logging.Simple.TraceLoggerFactoryAdapter, Common.Logging"> ! <arg key="level" value="DEBUG" /> ! <arg key="showLogName" value="true" /> ! <arg key="showDataTime" value="true" /> ! <arg key="dateTimeFormat" value="yyyy/MM/dd HH:mm:ss:fff" /> ! </factoryAdapter> ! </logging> ! </common> ! </configuration></programlisting> ! ! <note> ! <para>The concrete set of <arg> elements you may specify depends ! on the FactoryAdapter being used.</para> ! </note> ! </section> ! ! <section> ! <title>Configuring Logging in your code</title> ! ! <para>You may manually configure logging by setting a ! LoggerFactoryAdapter in your code.</para> ! ! <programlisting>// create properties ! NameValueCollection properties = new NameValueCollection(); ! properties["showDateTime"] = "true"; ! ! // set Adapter ! Common.Logging.LogManager.Adapter = new Common.Logging.Simple.TraceLoggerFactoryAdapter(properties);</programlisting> ! ! <note> ! <para>The concrete set of properties you may specify depends on the ! FactoryAdapter being used.</para> ! </note> ! </section> ! </section> ! ! <section id="logging-adapters"> ! <title>Logging Adapters</title> ! ! <para>There are simple out-of-the-box implementations coming with ! Common.Logging itself. For connecting to log4net, separate adapters do ! exist.</para> ! ! <section> ! <title>NoOpLoggerFactoryAdapter</title> ! ! <para>This is the default FactoryAdapter if logging is not configured. ! It simply does nothing.</para> ! </section> ! ! <section> ! <title>ConsoleOutLoggerFactoryAdapter</title> ! ! <para>ConsoleOutLoggerFactoryAdapter uses Console.Out for logging ! output.</para> ! ! <table> ! <title>Configuration Properties</title> ! ! <tgroup cols="3"> ! <thead> ! <row> ! <entry>Key</entry> ! ! <entry>Possible Value(s)</entry> ! ! <entry>Description</entry> ! </row> ! </thead> ! ! <tbody> ! <row> ! <entry>level</entry> ! ! <entry>All Debug Info Warn Error Fatal Off</entry> ! ! <entry>Defines the global maximum level of logging.</entry> ! </row> ! ! <row> ! <entry>showDateTime</entry> ! ! <entry>true|false</entry> ! ! <entry>output timestamp?</entry> ! </row> ! ! <row> ! <entry>showLogName</entry> ! ! <entry>true|false</entry> ! ! <entry>output logger name?</entry> ! </row> ! ! <row> ! <entry>dateTimeFormat</entry> ! ! <entry>any formatstring accepted by DateTime.ToString()</entry> ! ! <entry>defines the format to be used for output the timestamp. ! If no format is specified DateTime.ToString() will be ! used.</entry> ! </row> ! </tbody> ! </tgroup> ! </table> ! </section> ! ! <section> ! <title>TraceLoggerFactoryAdapter</title> ! ! <para>TraceLoggerFactoryAdapter uses ! <classname>System.Diagnostics.Trace</classname> for logging output. For ! viewing it's output you can use any tool that is capable of capturing ! calls to Win32 <function>OutputDebugString()</function> - e.g. the tool ! "DebugView" from <ulink ! url="www.sysinternals.com">www.sysinternals.com</ulink>.</para> ! ! <table> ! <title>Configuration Properties</title> ! ! <tgroup cols="3"> ! <thead> ! <row> ! <entry>Key</entry> ! ! <entry>Possible Value(s)</entry> ! ! <entry>Description</entry> ! </row> ! </thead> ! ! <tbody> ! <row> ! <entry>level</entry> ! ! <entry>All Debug Info Warn Error Fatal Off</entry> ! ! <entry>Defines the global maximum level of logging.</entry> ! </row> ! ! <row> ! <entry>showDateTime</entry> ! ! <entry>true|false</entry> ! ! <entry>output timestamp?</entry> ! </row> ! ! <row> ! <entry>showLogName</entry> ! ! <entry>true|false</entry> ! ! <entry>output logger name?</entry> ! </row> ! ! <row> ! <entry>dateTimeFormat</entry> ! ! <entry>any formatstring accepted by DateTime.ToString()</entry> ! ! <entry>defines the format to be used for output the timestamp. ! If no format is specified DateTime.ToString() will be ! used.</entry> ! </row> ! </tbody> ! </tgroup> ! </table> ! </section> ! ! <section id="logging-adapters-log4net"> ! <title>Log4NetLoggerFactoryAdapter</title> ! ! <para>There are two implementations, both configured similarly.</para> ! ! <itemizedlist> ! <listitem> ! <para><package>Common.Logging.Log4Net</package></para> ! ! <para>is linked against log4net 1.2.10.0</para> ! </listitem> ! ! <listitem> ! <para><package>Common.Logging.Log4Net129</package></para> ! ! <para>is linked against log4net 1.2.9.0</para> ! </listitem> ! </itemizedlist> ! ! <para>The only difference is in the type specified to the factory ! adapter. Both Adapters accept the following configuration ! properties:</para> ! ! <table> ! <title>Configuration Properties</title> ! ! <tgroup cols="3"> ! <thead> ! <row> ! <entry>Key</entry> ! ! <entry>Possible Value(s)</entry> ! ! <entry>Description</entry> ! </row> ! </thead> ! ! <tbody> ! <row> ! <entry>configType</entry> ! ! <entry><para>FILE</para><para>FILE-WATCH</para><para>INLINE</para><para>EXTERNAL</para></entry> ! ! <entry><para>INLINE will simply call ! XmlConfigurator.Configure()</para><para>EXTERNAL expects log4net ! being configured somewhere else in your code and does nothing. ! </para><para>FILE, FILE-WATCH: see property "configFile" ! below.</para></entry> ! </row> ! ! <row> ! <entry>configFile</entry> ! ! <entry><path to your log4net.config file></entry> ! ! <entry>if configType is FILE or FILE-WATCH, the value of ! "configFile" is passed to XmlConfigurator.Configure (FileInfo) / ! ConfigureAndWatch(FileInfo) method.</entry> ! </row> ! </tbody> ! </tgroup> ! </table> ! ! <para>The example below will configure log4net 1.2.10.0 using the file ! <filename>log4net.config</filename> from your application's root ! directory by calling ! <function>XmlConfigurator.ConfigureAndWatch()</function>:</para> ! ! <programlisting> <common> ! <logging> ! <factoryAdapter type="Common.Logging.Log4Net.Log4NetLoggerFactoryAdapter, Common.Logging.Log4net"> ! <arg key="configType" value="FILE-WATCH" /> ! <arg key="configFile" value="~/log4net.config" /> ! </factoryAdapter> ! </logging> ! </common></programlisting> ! ! <para>For log4net 1.2.9, change the assembly name ! <package>Common.Logging.Log4Net129</package></para> ! </section> ! </section> ! ! <section id="logging-advanced"> ! <title>Advanced Logging Tasks</title> ! ! <section id="logging-advanced-customfactoryadapter"> ! <title>Implementing a custom FactoryAdapter</title> ! ! <para>f you want to plug in a new, yet unsupported logging library, you ! need to implement the ! <interfacename>Common.Logging.ILoggerFactoryAdapter</interfacename> ! interface.</para> ! ! <para><guilabel>Important:</guilabel> Any implementation ! <emphasis>must</emphasis> provide a public constructor accepting a ! <classname>NameValueCollection</classname> parameter as shown in the ! example below:<programlisting>public class MyLoggingFactoryAdapter : ILoggerFactoryAdapter ! { ! public MyLoggingFactoryAdapter(NameValueCollection properties) ! { ! // configure according to properties ! } ! public ILog GetLogger(Type type) { ... } ! public ILog GetLogger(string name) { ... } ! }</programlisting></para> ! </section> </section> </chapter> \ No newline at end of file --- 9,34 ---- of indirection between logging calls made by Spring and the specific logging library used in your application (log4net, EntLib logging, NLog). ! The library is available for .NET 1.0, 1.1, and 2.0 with both debug and ! strongly signed assemblies. Since this need is not specific to Spirng, the ! logging library was moved out of the Spring project and into a more ! general open source project called <ulink ! url="http://netcommon.sourceforge.net/">Common Infrastructure Libraries ! for .NET</ulink>. The logging abstraction within the project is known as ! Common.Logging. Note that it is not the intention of this library to be a replacement for the many fine logging libraries that are out there. The ! API is incredibly minimal and will very likely stay that way. Please note ! that this library is intended only for use where the paramount requirement ! is portability and you will generally be better served by using a specific ! logging implementation so that you can leverage its advanced features and ! extended APIs to your advantage. </para> ! <para>You can find online documentation on how to configure Common.Logging ! is available in <ulink ! url="http://netcommon.sourceforge.net/doc-latest/reference/html/index.html">HTML</ulink> ! , <ulink ! url="http://netcommon.sourceforge.net/doc-latest/reference/html/index.html">PDF</ulink>, ! and <ulink ! url="http://netcommon.sourceforge.net/doc-latest/reference/htmlhelp/htmlhelp.chm">HTMLHelp</ulink> ! formats.</para> </section> </chapter> \ No newline at end of file Index: dbprovider.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/dbprovider.xml,v retrieving revision 1.11 retrieving revision 1.12 diff -C2 -d -r1.11 -r1.12 *** dbprovider.xml 3 Oct 2007 14:38:35 -0000 1.11 --- dbprovider.xml 10 Oct 2007 19:13:00 -0000 1.12 *************** *** 132,136 **** <listitem> ! <para><code>MySql</code> - MySQL, MySQL provider 1.0.7.3007</para> </listitem> --- 132,136 ---- <listitem> ! <para><code>MySql</code> - MySQL, MySQL provider 1.0.10.1</para> </listitem> *************** *** 201,204 **** --- 201,221 ---- mechanism will eventually be replaced shorly with one based on custom configuration section in App.config/Web.config.</para> + + <para>it may happen that the version number of an assembly you have + downloaded is different than the one listed above. If it is a point + release, i.e. the API hasn't changed in anyway that is material to your + application, you should add an assembly redirect of the form shown + below.</para> + + <programlisting><dependentAssembly> + <assemblyIdentity name="MySql.Data" + publicKeyToken="c5687fc88969c44d" + culture="neutral"/> + <bindingRedirect oldVersion="0.0.0.0-65535.65535.65535.65535" + newVersion="1.0.10.1"/> + </dependentAssembly></programlisting> + + <para>This redirects any reference to an older version of the assembly + MySql.Data to the version 1.0.10.1. </para> </section> |
