Details of Creating a Database Object

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

You can create a Database object by using a factory or by directly constructing one. The factory uses configuration information to determine the connection string, ADO.NET data provider, and the appropriate Data Access Application Block Database-derived object to construct. Alternatively, you can directly construct a Database object by passing any required information to the object's constructor.

Use a factory when you want to use the configuration information stored in a location supported by Enterprise Library or when you want to use connection strings managed by ADO.NET. For example, use a factory to create a Database object constructed with connection string information stored in the <connectionStrings> section in the application configuration file. You can also use the factory to construct a Database object with a connection string that is stored in an alternative configuration source. You must configure your application to use a different default configuration source to allow the factory to create objects with connection strings stored in that source. Use a constructor when you are retrieving connection string information from some source other than your default configuration source.

The CreateDatabase method is a static method of the DatabaseFactory class. The factory creates the correct database class based on information in the configuration file and returns an object of a subtype of the base class type, Database, to the client code. Unless you need commands that are specific to a particular database type, such as SQL Server, you should keep the application database agnostic by using only the methods available on the base Database class. The specific Database-derived type that is created is transparent to the application code; because of this, it remains the same regardless of the type of database being used.

You can use the CreateDatabase method to specify that the type of database to be created is based on the default configuration. By changing the default configuration, the unmodified application can be run against different databases.

You can also use a named instance of a database, such as "Customers," within the application. The factory uses the ADO.NET connection string information in the configuration file to look up the information associated with that particular named instance to create the appropriate database type.

If you need to use commands that are specific to one database or another, you must specify, through downcasting, the database type you expect to be created by the factory.

Finally, you can bypass the application's configuration information and directly create a Database object of a Database object subtype. To do this, you must know the type of database you want to create, as well as the connection string and any other information required by the subtype.

Creating a Default Database

A call to the CreateDatabase method with no parameters indicates that the factory should create the default database. The configuration file determines which of the named instances is the default instance. You can use the Configuration Console to change the default instance.

The following code shows how to create a database object that has been marked as the default instance.

Database dbSvc = DatabaseFactory.CreateDatabase();

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

Note

If the configuration file does not specify a default instance and the client code calls the CreateDatabase method with no parameters, the application block will throw an exception.

Using Instances

Using instances, you can refer to a database in your application code by a logical name and change the database configuration information (such as location or connection string information) without recompiling your code.

The following example shows how to create a database with the name "Sales."

// Use a named database instance that refers to an arbitrary database type, 
// which is determined by configuration information.
Database myDb = DatabaseFactory.CreateDatabase("Sales");

'Usage
' Use a named database instance that refers to an arbitrary database type, 
' which is determined by configuration information.
Dim myDb As Database = DatabaseFactory.CreateDatabase("Sales")

Creating a Specific Database Type

If you must use methods that are specific to a particular database type, specify the database type when you create the database. The following code requests that the factory create a SqlDatabase object.

// Create a SQL database.
SqlDatabase dbSQL = DatabaseFactory.CreateDatabase("Sales") as SqlDatabase;

'Usage
' Create a SQL database.
Dim dbSQL As SqlDatabase = DirectCast(DatabaseFactory.CreateDatabase("Sales"), SqlDatabase)

Similarly, to create an Oracle database, use the OracleDatabase type.

Creating a Database Without Configuration

You can create a database object without using configuration data by supplying a connection string to the database class constructor. The following code shows how to create a SqlDatabase object.

// Assume your application contains the routine GetConnectionString. 
string myConnectionString = GetConnectionString();
  
SqlDatabase sqlDatabase = new SqlDatabase(myConnectionString);

'Usage
' Assume your application contains the routine GetConnectionString. 
Dim myConnectionString As String = GetConnectionString()

Dim db As SqlDatabase = New SqlDatabase(myConnectionString)  

The following code shows how to create a GenericDatabase object. You must supply the connection string and a DbProviderFactory object. In this case, the DbProviderFactory object is the OdbcFactory.

GenericDatabase db = new GenericDatabase(connectionString, OdbcFactory.Instance);

'Usage
Dim db As GenericDatabase = New GenericDatabase(connectionstring, OdbcFactory.Instance)  

Usage Notes

The DatabaseFactory object determines which Database object to create based on the ADO.NET DbProviderFactory object that is associated with the connection string. The connection string is located in the configuration file, in the <connectionStrings> section. By default, the application block creates Database objects of type SqlDatabase for data providers of type System.Data.SqlClient, objects of type OracleDatabase for data providers of type System.Data.OracleClient, and objects of type GenericDatabase for all other data provider types. The GenericDatabase class supports only the database provider functionality provided by ADO.NET. In particular, the data access overloads that support parameter discovery do not work. A GenericDatabase object can be used with any .NET managed provider, including the ODBC and OLE-DB providers that ship with the .NET Framework 2.0. You can override the mappings between data provider types and Database object types through the configuration settings in the configuration file. For more information, see Design of the Data Access Application Block.

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.