MySQL Connector/NET Developer Guide
An interceptor is a software design pattern that provides a transparent way to extend or modify some aspect of a program, similar to a user exit. No recompiling is required. With MySQL Connector/NET, the interceptors are enabled and disabled by updating the connection string to refer to different sets of interceptor classes that you instantiate.
The classes and methods presented in this section do not apply to Connector/NET applications developed with the .NET Core 1.1 framework.
Connector/NET includes the following interceptor classes:
The
BaseCommandInterceptor
lets you perform additional operations when a program issues a
SQL command. For example, you can examine the SQL statement
for logging or debugging purposes, substitute your own result
set to implement a caching mechanism, and so on. Depending on
the use case, your code can supplement the SQL command or
replace it entirely.
The BaseCommandInterceptor
class has these
methods that you can override:
public virtual bool ExecuteScalar(string sql, ref object returnValue); public virtual bool ExecuteNonQuery(string sql, ref int returnValue); public virtual bool ExecuteReader(string sql, CommandBehavior behavior, ref MySqlDataReader returnValue); public virtual void Init(MySqlConnection connection);
If your interceptor overrides one of the
Execute...
methods, set the
returnValue
output parameter and return
true
if you handled the event, or
false
if you did not handle the event. The
SQL command is processed normally only when all command
interceptors return false
.
The connection passed to the Init
method is
the connection that is attached to this interceptor.
The
BaseExceptionInterceptor
lets you perform additional operations when a program
encounters an SQL exception. The exception interception
mechanism is modeled after the Connector/J model. You can code
an interceptor class and connect it to an existing program
without recompiling, and intercept exceptions when they are
created. You can then change the exception type and optionally
attach information to it. This capability lets you turn on and
off logging and debugging code without hardcoding anything in
the application. This technique applies to exceptions raised
at the SQL level, not to lower-level system or I/O errors.
You develop an exception interceptor first by creating a
subclass of the BaseExceptionInterceptor
class. You must override the
InterceptException()
method. You can also
override the Init()
method to do some
one-time initialization.
Each exception interceptor has 2 methods:
public abstract Exception InterceptException(Exception exception, MySqlConnection connection); public virtual void Init(MySqlConnection connection);
The connection passed to Init()
is the
connection that is attached to this interceptor.
Each interceptor is required to override
InterceptException
and return an exception.
It can return the exception it is given, or it can wrap it in
a new exception. We currently do not offer the ability to
suppress the exception.
Here are examples of using the FQN (fully qualified name) on the connection string:
MySqlConnection c1 = new MySqlConnection(@"server=localhost;pooling=false; commandinterceptors=CommandApp.MyCommandInterceptor,CommandApp"); MySqlConnection c2 = new MySqlConnection(@"server=localhost;pooling=false; exceptioninterceptors=ExceptionStackTraceTest.MyExceptionInterceptor,ExceptionStackTraceTest");
In this example, the command interceptor is called
CommandApp.MyCommandInterceptor
and exists in
the CommandApp
assembly. The exception
interceptor is called
ExceptionStackTraceTest.MyExceptionInterceptor
and exists in the ExceptionStackTraceTest
assembly.
To shorten the connection string, you can register your exception
interceptors in your app.config
or
web.config
file like this:
<configSections> <section name="MySQL" type="MySql.Data.MySqlClient.MySqlConfiguration,MySql.Data"/> </configSections> <MySQL> <CommandInterceptors> <add name="myC" type="CommandApp.MyCommandInterceptor,CommandApp" /> </CommandInterceptors> </MySQL> <configSections> <section name="MySQL" type="MySql.Data.MySqlClient.MySqlConfiguration, MySql.Data"/> </configSections> <MySQL> <ExceptionInterceptors> <add name="myE" type="ExceptionStackTraceTest.MyExceptionInterceptor,ExceptionStackTraceTest" /> </ExceptionInterceptors> </MySQL>
After you have done that, your connection strings can look like these:
MySqlConnection c1 = new MySqlConnection(@"server=localhost;pooling=false; commandinterceptors=myC"); MySqlConnection c2 = new MySqlConnection(@"server=localhost;pooling=false; exceptioninterceptors=myE");