Adding a New Application Block Database Provider

If the relational database system you are using does not already have an application block database provider, you can create your own. This is only necessary if the application block's GenericDatabase class does not meet the requirements of your application. (This assumes that there is an ADO.NET DbProviderFactory type for the database system you are using.) To create a new database provider, you must create a new database class that derives from the Database class. Additionally, if you want your client code to remain database-agnostic, you might have to write additional code to perform such tasks as type conversion.

Creating a New Database Class

To create a new Database class

1. Create a new class derived from the Database class.

2. Implement a constructor that allows the application block to instantiate your database class with a connection string and any other required information, such as package mappings for an Oracle database.

   Note

   The Database base class provides the implementation required to initialize your class with the connection string and DbProviderFactory.

3. Override the methods for parameter handling as required. For example, override the DeriveParameters method to support parameter discovery. You can also override the following methods:

   • UserParametersStartIndex. Override this method when the starting index of the stored procedure parameters in a command is not zero. For example, every SQL Server database stored procedure has a return value parameter (whether or not it is explicitly used) that is in addition to the other stored procedure parameters. This parameter is the first parameter in the Parameters collection of the ADO.NET DbCommand object (the starting index is zero). Therefore, the SqlDatabase class overrides the UserParametersStartIndex method to return a value of one as the starting index. By doing this, the index reflects the position of the first stored procedure parameter and effectively skips over the return value parameter.
   • BuildParameterName. Override this method to ensure appropriate parameter naming for stored procedure calls. Overrriding this method allows client code to pass parameter names without database-specific tokens. For example, the SqlDatabase class overrides this method to ensure that all parameter names begin with the "@" character. Consequently, client code can pass parameter names without the "@" character, allowing the client code to remain database-agnositic.
   • SameNumberOfParametersAndValues. Override this method to compare the number of parameters in a DbCommand object with the number of parameters in an array. For example, the parameter array for a SQL Server database includes the return value parameter. SQL generates this parameter for every stored procedure call, and it is not included in the DbCommand object's count. The SqlDatabase class overrides the SameNumberOfParametersAndValues method to perform the proper comparison between the number of command parameters and the number of parameter values.

4. Add functionality specific to your provider. For example, the SqlDatabase class provides the ExecuteXmlReader method. You will have to downcast to your database provider class type to access any custom methods. You can also override other methods to adapt their behavior to suit your situation. For example, you can modify the SQL command syntax before passing it to the ADO.NET classes.

For detailed information about how to integrate custom providers with the Enterprise Library configuration system and configuration tools see Creating Custom Providers for Enterprise Library.

Configuring Your Application to Use the New Provider

After your new database provider is complete, you must configure your application to use it. For instructions on configuring your application to use the custom provider, see Configuring Enterprise Library.

Recommendations for Creating a Database Provider

The following are some guidelines for creating and testing a database provider:

• You can only create a new database type if the ADO.NET DbProviderFactory subclass already exists for the database type that you want to create.
• Use an existing data provider as a model for your own. Use the SQL Server or Oracle data provider that ship with the Data Access Application Block as a basis for your own provider.
• Use the unit tests that are included in the Data Access Application Block assembly to verify that your provider works.
• Make sure that you test data type conversions and document anything that your provider does not support or supports differently. This documentation will be helpful to developers who want to build portable database applications.