Table of Contents

Class AdoNetAppender

Namespace
log4net.Appender
Assembly
log4net.dll

Appender that logs to a database.

public class AdoNetAppender : BufferingAppenderSkeleton, IBulkAppender, IAppender, IOptionHandler
Inheritance
AdoNetAppender
Implements
Inherited Members

Examples

An example of a SQL Server table that could be logged to:

CREATE TABLE [dbo].[Log] ( 
  [ID] [int] IDENTITY (1, 1) NOT NULL ,
  [Date] [datetime] NOT NULL ,
  [Thread] [varchar] (255) NOT NULL ,
  [Level] [varchar] (20) NOT NULL ,
  [Logger] [varchar] (255) NOT NULL ,
  [Message] [varchar] (4000) NOT NULL 
) ON [PRIMARY]

An example configuration to log to the above table:

Remarks

AdoNetAppender appends logging events to a table within a database. The appender can be configured to specify the connection string by setting the ConnectionString property. The connection type (provider) can be specified by setting the ConnectionType property. For more information on database connection strings for your specific database see http://www.connectionstrings.com/.

Records are written into the database either using a prepared statement or a stored procedure. The CommandType property is set to Text (System.Data.CommandType.Text) to specify a prepared statement or to StoredProcedure (System.Data.CommandType.StoredProcedure) to specify a stored procedure.

The prepared statement text or the name of the stored procedure must be set in the CommandText property.

The prepared statement or stored procedure can take a number of parameters. Parameters are added using the AddParameter(AdoNetAppenderParameter) method. This adds a single AdoNetAppenderParameter to the ordered list of parameters. The AdoNetAppenderParameter type may be subclassed if required to provide database specific functionality. The AdoNetAppenderParameter specifies the parameter name, database type, size, and how the value should be generated using a ILayout.

Constructors

AdoNetAppender()

Initializes a new instance of the AdoNetAppender class.

public AdoNetAppender()

Remarks

Public default constructor to initialize a new instance of this class.

Fields

m_parameters

The list of AdoNetAppenderParameter objects.

protected ArrayList m_parameters

Field Value

ArrayList

Remarks

The list of AdoNetAppenderParameter objects.

m_usePreparedCommand

Flag to indicate if we are using a command object

protected bool m_usePreparedCommand

Field Value

bool

Remarks

Set to true when the appender is to use a prepared statement or stored procedure to insert into the database.

Properties

AppSettingsKey

The appSettings key from App.Config that contains the connection string.

public string AppSettingsKey { get; set; }

Property Value

string

CommandText

Gets or sets the command text that is used to insert logging events into the database.

public string CommandText { get; set; }

Property Value

string

The command text used to insert logging events into the database.

Remarks

Either the text of the prepared statement or the name of the stored procedure to execute to write into the database.

The CommandType property determines if this text is a prepared statement or a stored procedure.

CommandType

Gets or sets the command type to execute.

public CommandType CommandType { get; set; }

Property Value

CommandType

The command type to execute.

Remarks

This value may be either Text (System.Data.CommandType.Text) to specify that the CommandText is a prepared statement to execute, or StoredProcedure (System.Data.CommandType.StoredProcedure) to specify that the CommandText property is the name of a stored procedure to execute.

The default value is Text (System.Data.CommandType.Text).

Connection

Gets or sets the underlying IDbConnection.

protected IDbConnection Connection { get; set; }

Property Value

IDbConnection

The underlying IDbConnection.

Remarks

AdoNetAppender creates a IDbConnection to insert logging events into a database. Classes deriving from AdoNetAppender can use this property to get or set this IDbConnection. Use the underlying IDbConnection returned from Connection if you require access beyond that which AdoNetAppender provides.

ConnectionString

Gets or sets the database connection string that is used to connect to the database.

public string ConnectionString { get; set; }

Property Value

string

The database connection string used to connect to the database.

Examples

Connection string for MS Access via ODBC:

        <pre><code class="lang-csharp">"DSN=MS Access Database;UID=admin;PWD=;SystemDB=C:\data\System.mdw;SafeTransactions = 0;FIL=MS Access;DriverID = 25;DBQ=C:\data\train33.mdb"</code></pre>

Another connection string for MS Access via ODBC:

        <pre><code class="lang-csharp">"Driver={Microsoft Access Driver (*.mdb)};DBQ=C:\Work\cvs_root\log4net-1.2\access.mdb;UID=;PWD=;"</code></pre>

Connection string for MS Access via OLE DB:

        <pre><code class="lang-csharp">"Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Work\cvs_root\log4net-1.2\access.mdb;User Id=;Password=;"</code></pre>

Remarks

The connections string is specific to the connection type. See ConnectionType for more information.

ConnectionStringName

The connectionStrings key from App.Config that contains the connection string.

public string ConnectionStringName { get; set; }

Property Value

string

Remarks

This property requires at least .NET 2.0.

ConnectionType

Gets or sets the type name of the IDbConnection connection that should be created.

public string ConnectionType { get; set; }

Property Value

string

The type name of the IDbConnection connection.

Examples

Use the OLE DB Provider. This is the default value.

        <pre><code class="lang-csharp">System.Data.OleDb.OleDbConnection, System.Data, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</code></pre>

Use the MS SQL Server Provider.

        <pre><code class="lang-csharp">System.Data.SqlClient.SqlConnection, System.Data, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</code></pre>

Use the ODBC Provider.

        <pre><code class="lang-csharp">Microsoft.Data.Odbc.OdbcConnection,Microsoft.Data.Odbc,version=1.0.3300.0,publicKeyToken=b77a5c561934e089,culture=neutral</code></pre>

        This is an optional package that you can download from 
        <a href="http://msdn.microsoft.com/downloads">http://msdn.microsoft.com/downloads</a> 
        search for <b>ODBC .NET Data Provider</b>.

Use the Oracle Provider.

        <pre><code class="lang-csharp">System.Data.OracleClient.OracleConnection, System.Data.OracleClient, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</code></pre>

        This is an optional package that you can download from 
        <a href="http://msdn.microsoft.com/downloads">http://msdn.microsoft.com/downloads</a> 
        search for <b>.NET Managed Provider for Oracle</b>.

Remarks

The type name of the ADO.NET provider to use.

The default is to use the OLE DB provider.

ReconnectOnError

Should this appender try to reconnect to the database on error.

public bool ReconnectOnError { get; set; }

Property Value

bool

true if the appender should try to reconnect to the database after an error has occurred, otherwise false. The default value is false, i.e. not to try to reconnect.

Remarks

The default behaviour is for the appender not to try to reconnect to the database if an error occurs. Subsequent logging events are discarded.

To force the appender to attempt to reconnect to the database set this property to true.

note

When the appender attempts to connect to the database there may be a delay of up to the connection timeout specified in the connection string. This delay will block the calling application's thread. Until the connection can be reestablished this potential delay may occur multiple times.

SecurityContext

Gets or sets the SecurityContext used to call the NetSend method.

public SecurityContext SecurityContext { get; set; }

Property Value

SecurityContext

The SecurityContext used to call the NetSend method.

Remarks

Unless a SecurityContext specified here for this appender the DefaultProvider is queried for the security context to use. The default behavior is to use the security context of the current thread.

UseTransactions

Should transactions be used to insert logging events in the database.

public bool UseTransactions { get; set; }

Property Value

bool

true if transactions should be used to insert logging events in the database, otherwise false. The default value is true.

Remarks

Gets or sets a value that indicates whether transactions should be used to insert logging events in the database.

When set a single transaction will be used to insert the buffered events into the database. Otherwise each event will be inserted without using an explicit transaction.

Methods

ActivateOptions()

Initialize the appender based on the options set

public override void ActivateOptions()

Remarks

This is part of the IOptionHandler delayed object activation scheme. The ActivateOptions() method must be called on this object after the configuration properties have been set. Until ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then ActivateOptions() must be called again.

AddParameter(AdoNetAppenderParameter)

Adds a parameter to the command.

public void AddParameter(AdoNetAppenderParameter parameter)

Parameters

parameter AdoNetAppenderParameter

The parameter to add to the command.

Remarks

Adds a parameter to the ordered list of command parameters.

CreateConnection(Type, string)

Creates an IDbConnection instance used to connect to the database.

protected virtual IDbConnection CreateConnection(Type connectionType, string connectionString)

Parameters

connectionType Type

The Type of the IDbConnection object.

connectionString string

The connectionString output from the ResolveConnectionString method.

Returns

IDbConnection

An IDbConnection instance with a valid connection string.

Remarks

This method is called whenever a new IDbConnection is needed (i.e. when a reconnect is necessary).

GetLogStatement(LoggingEvent)

Formats the log message into database statement text.

protected virtual string GetLogStatement(LoggingEvent logEvent)

Parameters

logEvent LoggingEvent

The event being logged.

Returns

string

Text that can be passed to a IDbCommand.

Remarks

This method can be overridden by subclasses to provide more control over the format of the database statement.

OnClose()

Override the parent method to close the database

protected override void OnClose()

Remarks

Closes the database command and database connection.

ResolveConnectionString(out string)

Resolves the connection string from the ConnectionString, ConnectionStringName, or AppSettingsKey property.

protected virtual string ResolveConnectionString(out string connectionStringContext)

Parameters

connectionStringContext string

Additional information describing the connection string.

Returns

string

A connection string used to connect to the database.

Remarks

ConnectiongStringName is only supported on .NET 2.0 and higher.

ResolveConnectionType()

Retrieves the class type of the ADO.NET provider.

protected virtual Type ResolveConnectionType()

Returns

Type

The Type of the ADO.NET provider

Remarks

Gets the Type of the ADO.NET provider to use to connect to the database. This method resolves the type specified in the ConnectionType property.

Subclasses can override this method to return a different type if necessary.

SendBuffer(IDbTransaction, LoggingEvent[])

Writes the events to the database using the transaction specified.

protected virtual void SendBuffer(IDbTransaction dbTran, LoggingEvent[] events)

Parameters

dbTran IDbTransaction

The transaction that the events will be executed under.

events LoggingEvent[]

The array of events to insert into the database.

Remarks

The transaction argument can be null if the appender has been configured not to use transactions. See UseTransactions property for more information.

SendBuffer(LoggingEvent[])

Inserts the events into the database.

protected override void SendBuffer(LoggingEvent[] events)

Parameters

events LoggingEvent[]

The events to insert into the database.

Remarks

Insert all the events specified in the events array into the database.