Introduction to the Data Access Application Block

The Enterprise Library Data Access Application Block simplifies development tasks that implement common data access functionality. Applications can use this application block in a variety of situations, such as reading data for display, passing data through application layers, and submitting changed data back to the database system. The application block includes support for both stored procedures and in-line SQL. Common housekeeping tasks, such as managing connections and creating and caching parameters, are encapsulated in the application block's methods. In other words, the Data Access Application Block provides access to the most often used features of ADO.NET in simple-to-use classes; this boosts developer productivity.

ADO.NET 2.0 provides classes such as the DbCommand class and the DbConnection class; these classes help to abstract the data provider from any particular database implementation. The Data Access Application Block takes advantage of these classes and provides a model that further supports encapsulation of database type-specific features, such as parameter discovery and type conversions. Because of this, applications can be ported from one database type to another without modifying the client code. The Data Access Application Block includes an abstract base class that defines a common interface and that provides much of the implementation needed by the data access methods available in ADO.NET 2.0.

The application block also includes classes that are specific to Microsoft SQL Server and Oracle. These classes perform operations that are particular to the database type. The code for applications written for one type of database, such as SQL Server, looks much the same as the code for applications written for another type of database, such as Oracle.

Another feature of the Data Access Application Block is that application code can refer to particular databases by an ADO.NET connection string name, such as "Customer" or "Inventory." The application code can specify a named instance of a database and pass this parameter to the DatabaseFactory.CreateDatabase method. Each named database has its connection information stored in a configuration file. By changing the settings in the configuration file, developers can use their applications with different database configurations without recompiling their code.

The Data Access Application Block provides the following benefits:

• It uses the functionality provided by ADO.NET 2.0 and with it, you can use ADO.NET functionality along with the application block's functionality.
• It reduces the need to write boilerplate code to perform standard tasks.
• It helps maintain consistent data access practices, both within an application and across the enterprise.
• It reduces difficulties in changing the database type.
• It relieves developers from learning different programming models for different types of databases.
• It reduces the amount of code that developers must write when they port applications to different types of databases.

Common Scenarios

Developers often write applications that use databases. Because it is so common, developers may find themselves repeatedly writing the same code for each application. In addition, these applications may need to work with different types of databases. Although the tasks are the same, the code must be adapted to suit the programming model of each database. The Data Access Application Block solves these problems by providing the logic to perform the most common data access tasks. Developers only need to do the following:

• Create the database object.
• Supply the parameters for the command, if they are needed.
• Call the appropriate method(s). These methods are optimized for performance. They are also portable.

The Data Access Application Block works transparently with SQL Server and Oracle databases.

Example Application Code

The following code shows how to call a stored procedure that returns a DataSet.

Database db = DatabaseFactory.CreateDatabase();

DbCommand dbCommand = db.GetStoredProcCommand("GetProductsByCategory");

// Retrieve products from category 7.
db.AddInParameter(dbCommand, "CategoryID", DbType.Int32, 7);
 
DataSet productDataSet = db.ExecuteDataSet(dbCommand); 

'Usage
Dim db As Database = DatabaseFactory.CreateDatabase()

Dim dbCommand As DbCommand = db.GetStoredProcCommand("GetProductsByCategory")

' Retrieve products from the category 7.
db.AddInParameter(dbCommand, "CategoryID", DbType.Int32, 7)

Dim productDataSet As DataSet = = db.ExecuteDataSet(dbCommand)

Audience Requirements

This guide is intended for software architects and software developers. To benefit fully from this guide, you should have an understanding of the following technologies:

• Microsoft Visual Studio 2005 development system (any of the following editions):
  • Visual Studio 2005 Professional Edition
  • Visual Studio 2005 Team System Edition
  • Visual Studio 2005 Standard Edition
• .NET Framework version 2.0
• Microsoft SQL Server or Oracle databases

Migrating From Enterprise Library – June 2005

The January 2006 release of the Data Access Application Block uses features that are available in ADO.NET 2.0. Most of the changes to the application block are internal and will not affect your client code. However, there are changes that require you to modify your existing applications and configuration data.

The most significant change is that the Data Access Application Block DBCommandWrapper class has been removed. The new ADO.NET 2.0 DbCommand class provides similar functionality, and the application block was changed to use this new platform class. You will need to modify your applications to accommodate the following changes:

• The Database methods that created and returned a DBCommandWrapper object in the June 2005 release now return a DbCommand object.
• The data access methods of the Database class now accept a DbCommand object instead of a DBCommandWrapper.
• Methods that were available on the DBCommand class but are not available in the new DbCommand class have been moved to the Database class. These methods now take a DbCommand object as a parameter. These methods are SetParameterValue, GetParameterValue, AddParameter, AddInParameter, and AddOutParameter.

Here is an example of code for previous versions of the Data Access Application Block.

Database db = DatabaseFactory.CreateDatabase();

DBCommandWrapper dbCommand = db.GetStoredProcCommandWrapper("GetProductsByCategory");
 
dbCommand.AddInParameter("CategoryID", DbType.Int32, Category);

DataSet productDataSet = db.ExecuteDataSet(dbCommand);

'Usage
Dim db As Database = DatabaseFactory.CreateDatabase()

Dim dbCommand As DBCommandWraper = db.GetStoredProcCommandWrapper("GetProductsByCategory")

dbCommand.AddInParameter("CategoryID", DbType.Int32, Category)

Dim customerproductDataSet As DataSet = db.ExecuteDataSet(dbCommand)

This code should be modified to look like the following example.

Database db = DatabaseFactory.CreateDatabase();

DbCommand dbCommand = db.GetStoredProcCommand("GetProductsByCategory"); 

db.AddInParameter(dbCommand, "CategoryID", DbType.Int32, Category);

DataSet productDataSet = db.ExecuteDataSet(dbCommand);

'Usage
Dim db As Database = DatabaseFactory.CreateDatabase()

Dim dbCommand As DbCommand = db.GetStoredProcCommand("GetProductsByCategory")

db.AddInParameter(dbCommand, "CategoryID", DbType.Int32, Category)

Dim customerproductDataSet As DataSet = db.ExecuteDataSet(dbCommand)

Avoid using database-specific tokens with stored procedure parameter names. The Database-derived classes for specific providers include code to adjust parameter names as required. Notice that these code examples do not include the "@" character when supplying stored procedure parameter names to a SQL Server database. For example, the AddInParameter method uses CategoryID as a parameter and not @CategoryID. For more information, see Creating Portable Database Applications.

The Database class GetConnection method has been replaced with the CreateConnection method. The CreateConnection method returns a DbConnection object. The DbConnection class is new in ADO.NET 2.0.

The application block no longer maintains connection string configuration information. The application block now obtains connection strings from the ADO.NET configuration settings available through the System.Configuration.ConfigurationManager class.

The GenericDatabase class is a new application block class. It does not provide any database-specific functionality. The CreateDatabase method creates an instance of the new GenericDatabase class when it does not recognize the ADO.NET ProviderType object.

The DB2-specific DB2Database class no longer exists. Each Database-derived class in the application block (other than GenericDatabase) uses a specific ADO.NET provider. There is no DB2-specific ADO.NET 2.0 provider. However, the GenericDatabase class can be used with any managed ADO.NET provider, including the OLE-DB and ODBC providers which can be used to access many different kinds of databases.

ADO.NET no longer supports the Oracle data types DbType.Guid and DbType.Boolean. To replace these data types, use the Oracle type of Raw(16) and Numeric, and map them to the Guid or Bit data type. Using the DbType.Guid data type or the DbType.Boolean data type may make your application less portable.

Configuration data is treated differently in Enterprise Library – January 2006 than in earlier releases. This affects all application blocks, including the Data Access Application Block. You must perform the following tasks when you migrate your application to Enterprise Library – January 2006:

• Migrate existing configuration information. Enterprise Library – June 2005 version stored the Data Access Application Block configuration data in a location separate from the application configuration file. By default, this location was the DataAccessConfiguration.config file. With this release, the default location for application block configuration data is the application configuration file. For a description of how to migrate your existing configuration information for use with Enterprise Library – January 2006, see Migration Information.
• Migrate custom database providers. You must update any custom database providers to reflect how Enterprise Library – January 2006 passes configuration information to providers.

New Features

With the Enterprise Library – January 2006, you can create an instance of a Database-derived class directly by using a constructor and by supplying a connection string (a provider type is also required for the GenericDatabase class).

System Requirements

To run the Data Access Application Block, you need the following:

• Microsoft Windows 2000, Windows XP Professional, or Windows Server 2003 operating system
• Microsoft .NET Framework 2.0
• Microsoft Visual Studio 2005 development system (any of the following editions):
  • Microsoft Visual Studio 2005 Standard Edition
  • Microsoft Visual Studio 2005 Professional Edition
  • Microsoft Visual Studio 2005 Team Edition for Software Developers
  • Microsoft Visual Studio 2005 Team Edition for Software Testers
  • Microsoft Visual Studio 2005 Team Edition for Software Architects
  • Microsoft Visual Studio 2005 Team Suite
• A database server running a database that is supported by a .NET Framework 2.0 data provider. This includes SQL Server 2000 or later and Oracle 9i. The database server can also run a database that is supported by the .NET Framework 2.0 data providers for OLE DB or ODBC.

Data Access Application Block Dependencies

The Data Access Application Block depends on other code included in the Enterprise Library:

• Core library functionality. The Enterprise Library Core provides services, such as instrumentation and configuration, and is a shared dependency of all Enterprise Library application blocks. The core library functionality is contained in the assembly Microsoft.Practices.EnterpriseLibrary.Common.dll.
• The ObjectBuilder subsystem. The ObjectBuilder subsystem performs all the repetitive and necessary tasks for creating and disposing object instances, while still providing a high level of flexibility. Enterprise Library uses the ObjectBuilder subsystem for tasks such as injecting configuration into block classes and connecting instrumentation classes to application blocks. The ObjectBuilder subsystem is contained in the assembly Microsoft.Practices.ObjectBuilder.dll.

The Data Access Application Block uses ADO.NET for the management of connection strings. The application block provides a DatabaseFactory class that uses configuration information to create a database object. This configuration information consists of both the ADO.NET-managed connection strings and other application block configuration information.

Generally, you should manage connection strings using configuration data. Alternatively, you can create a database object in your application by using a constructor and supplying it with a connection string and the database type.

The recommended way to modify the Data Access Application Block configuration information is to use the Enterprise Library Configuration Console.

Data Access Application Block Documentation

In addition to the introduction, the documentation contains the following sections:

• Developing Applications with the Data Access Application Block. This section is divided into several subsections. Entering Configuration Information describes how to configure the application block. Adding Application Code describes how to prepare your application to use the Data Access Application Block. The next subsection, Key Scenarios, demonstrates how to use the application block to perform the most typical data access operations. The last subsection, Details of Development Tasks, includes in-depth information about creating database objects, creating commands, handling parameters, and handling exceptions.
• Design of the Data Access Application Block. This section describes the decisions that went into designing the application block and the rationale behind those decisions.
• Extending and Modifying the DataAccess Application Block. This section describes how to extend the application block by adding your own database provider and gives suggestions for modifying the source code.
• Deployment and Operations. This section describes how to deploy and update the application block assemblies and also contains information about configuration and SQL Server security.
• QuickStarts. This section describes how to install and configure the QuickStart application and contains a series of walkthroughs that demonstrate how to incorporate common data access operations into an application.

More Information

For more information, see the following resources:

• **Application Architecture for .NET: Designing Applications and Services
• ****.NET Data Access Architecture Guide
• INFO: Microsoft Guide for Designing Data Tier Components and Passing Data Through Tiers
• **Improving Web Application Security: Threats and Countermeasures
• **Improving .NET Application Performance and Scalability