5.9 Using the Connector/NET Interceptor Classes

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.

Note

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");