3.4. Configuration Elements

3.4. Configuration Elements
Prev	Chapter 3. Configuration	Next

The sections below describe the elements of the Data Access configuration document for .NET. The dao.config file can be validated by the DaoConfig.xsd schema provided with the distribution.

3.4.1. type Attributes

In general, when specifying a type attribute within a configuration file, a type attribute value must be a fully qualified type name following the format:

      type="[namespace.class], [assembly name],
            Version=[version], Culture=[culture],
            PublicKeyToken=[public token]"

For example:

      type="MyProject.Domain.LineItem, MyProject.Domain,
            Version=1.2.3300.0, Culture=neutral,
            PublicKeyToken=b03f455f11d50a3a"

The strongly typed name is desired, however, it is also legitimate to use the shorter style assembly type name:

      type="MyProject.Domain.LineItem, MyProject.Domain"

3.4.2. The <providers> Element

Under ADO.NET, a database system is accessed through a provider. A database system can use a custom provider or a generic ODBC provider. iBATIS.NET uses a pluggable approach to installing providers. Each provider is represented by an XML descriptor element. The list of providers you might want to use can be kept in a separate XML descriptor file. The iBATIS.NET distribution includes the standard providers.config file with a set of thirteen prewritten provider elements:

sqlServer1.0 - Microsoft SQL Server 7.0/2000 provider available with .NET Framework 1.0
sqlServer1.1 -Microsoft SQL Server 7.0/2000 provider available with .NET Framework 1.1
OleDb1.1 - OleDb provider available with .NET Framework 1.1
Odbc1.1 - Odbc provider available with .NET Framework 1.1
oracle9.2 - Oracle provider V9.2.0.401
oracle10.1 - Oracle provider V10.1.0.301
oracleClient1.0 - MS Oracle provider V1.0.5 available with .NET Framework 1.1
ByteFx - ByteFx MySQL provider V0.7.6.15073
MySql - MySQL provider V1.0.4.20163
SQLite3 - SQLite.NET provider V0.21.1869.3794
Firebird1.7 - Firebird SQL .NET provider V1.7.0.33200
PostgreSql0.7 - Npgsql provider V0.7.0.0
iDb2.10 - IBM DB2 iSeries provider V10.0.0.0

The providers.config file can be found under \source\IBatisNet.DataAccess.Test\bin\Debug in the iBATIS.NET source distribution or in the root folder of the .NET DataAccess binary distribution.

A provider may require libraries that you do not have installed,. Therefore, the provider element has an "enabled" attribute that allows you to disable unused providers. One provider can also be marked as the "default" and will be used if another is not specified by your configuration.

The standard providers.config file has sqlServer1.1 set as the default and the sqlServer1.0 provider disabled. Aside from sqlServer1.1, OleDb1.1, and Odbc1.1, all other providers are disabled by default. Remember to set the "enabled" attribute to "true" for the provider that you will be using.

	Important
	ByteFx is the recommended provider if you are using MySQL. You may download ByteFx from the MySQLNet SourceForge site (http://sf.net/projects/mysqlnet/). If the ByteFx license is acceptable to you, you may install it as a reference within your application and enable the ByteFx provider.

	Tip
	Be sure to review the `providers.config` file and confirm that the provider you intend to use is enabled! (Set the enabled attribute to true.)

Table 3.5. Expected default locations of the providers.config file

Windows, Library, or Test projects (using NUnit or equivalent)	With the assembly (.dll) files with the `app.config` file
Web projects	In the project base directory, with the `web.config` file

To use the file, you can copy it into your project at the expected default location, give a path to the file relative to the project root directory, specify a url (absolute path) to its location, or make it an embedded resource of your project. If you copy the file into the expected default location, the <providers> element is not required in your dao.config file.

3.4.2.1. <providers> attributes

The <providers> element can accept one of the following attributes to specify the location of the providers.config file.

Table 3.6. Attributes of the <providers> element

Attribute	Description
resource	Specify the file to be loaded from a relative path from the project root directory. Since the root directory is different depending on the project type, it is best to use a properties variable to indicate the relative path. Having that variable defined in a properties file makes it easy to change the path to all your DataAccess configuration resources in one location. resource="${root}providers.config"
url	Specify the providers.config to be loaded through an absolute path. url="`c:\Web\MyApp\`Resources\providers.config" or url="file://`c:\Web\MyApp\Resources\`providers.config"
embedded	Specify the providers.config file to be loaded as an embedded resource in an assembly. Syntax for the embedded attribute is '[extendednamespace.]filename, the name of the assembly which contains the embedded resource' embedded="Resources.providers.config, MyApp.Data"

3.4.3. The <context> Element

A DAO context is a grouping of related configuration information and DAO implementations for a specific database and provider.

Table 3.7. Attributes of the <context> element

Attribute	Description
id	Context id
default	Global setting to indicate if this is the default context

3.4.3.1. The <properties> Element

Sometimes the values we use in an XML configuration file occur in more than one element. Often, there are values that change when we move the application from one server to another. To help you manage configuration values, you can specify a standard properties file (with name=value entries) as part of a Data Access configuration. Each named value in the properties file becomes a shell variable that can be used throughout the Data Access configuration.

Properties are handy during building, testing, and deployment. Additionally, properties make it easy to reconfigure your application for multiple environments or to use automated tools for configuration such as NAnt.

The <properties> element can only accept one of the following attributes to specify the location of the properties file.

Table 3.8. Attributes of the <properties> element

Attribute	Description
resource	Specify the properties file name files to be loaded from the root directory of the application (relative path) resource="properties.config"
url	Specify the properties file to be loaded through an absolute path url="`c:\Web\MyApp\Resources\properties`.config" or url="file://`c:\Web\MyApp\Resources\properties`.config"
embedded	Specify the properties file to be loaded as an embedded resource in an assembly. Syntax for the embedded attribute is '[extendednamespace.]filename, the name of the assembly which contains the embedded resource' embedded="Resources.properties.config, MyApp.Data"

3.4.3.1.1. <property> element and attributes

You can also specify more than one properties file or add property keys and values directly into your dao.config file by using <property> elements. For example:

<properties>
 <property resource="myProperties.config"/>
 <property resource="anotherProperties.config"/>
 <property key="host" value="ibatis.com" />
</properties>

Table 3.9. Attributes of the <property> element

Attribute	Description
resource	Specify the properties file to be loaded from the root directory of the application resource="properties.config"
url	Specify the properties file to be loaded through an absolute path. url="`c:\Web\MyApp\Resources\properties`.config" or url="file://`c:\Web\MyApp\Resources\properties`.config"
embedded	Specify the properties file to be loaded as an embedded resource in an assembly. Syntax for the embedded attribute is '[extendednamespace.]filename, the name of the assembly which contains the embedded resource' embedded="Resources.properties.config, MyApp.Data"
key	Defines a property key (variable) name key="username"
value	Defines a value that will be used by the framework in place of the the specified property key/variable value="mydbuser"

3.4.3.2. The <database> Element

The <database> element encloses elements that configure the database system for use by the framework. These are the <provider> and <datasource> elements.

3.4.3.2.1. The <provider> Element

The <provider> element specifies a database provider from the providers.config file.

If the default provider is being used, the <provider> element is optional. Or, if several providers are available, one may be selected using the provider element without modifying the providers.config file.

<provider name="OleDb1.1" />

Table 3.10. Attributes of the <provider> element

Attribute	Description
name	Name used to uniquely identify the provider

3.4.3.2.2. The <dataSource> Element

The <datasource> element specifies the connection string for a specific database and provider.

Table 3.11. Attributes of the <dataSource> element

Attribute	Description
name	Name used to identify the data source
connectionString	The connection string to the database

3.4.3.3. The <daoSessionHandler> Element

The <daoSessionHandler> element specifies the component that manages transaction and connections for a session.

Table 3.12. Attributes of the <daoSessionHandler> element

Attribute	Description
id	Id used to uniquely identify the handler

3.4.3.3.1. The <property> Element

Some <daoSessionHandler> implementations such as iBATIS DataMapper SqlMaps and NHibernate need additional information for configuration. The <property> element is used to specify this information.

For iBATIS DataMapper SqlMaps, the method for locating and loading the SqlMap.config file is used in the "name" attribute. Depending on the chosen method, the corresponding filepath or fully-qualified resource and assembly name is used for the "value" attribute.

Table 3.13. Attributes of the <property> element for use with iBATIS DataMapper SqlMaps

Attribute	Description
name	Indicates the method used to locate and load the `SqlMap.config` file. The available options are "resource", "url", and "embedded" (as previously described for loading the providers and properties configuration files). name="resource"
value	Used to specify the filename, fullpath, or fully qualified resource and assembly name for the `SqlMap.config` file. value="MySqlMap.config"

For NHibernate, the "name" and "value" attributes are used to specify various NHibernate configuration details such as "hibernate.dialect", "hibernate.connection.provider", and "mapping".

Table 3.14. Attributes of the <property> element for use with NHibernate

Attribute	Description
name	The name of the property to configure. Example: name="hibernate.dialect"
value	The value of the property configuration. Example: value="NHibernate.Dialect.MsSql2000Dialect"

3.4.3.4. The <daoFactory> Element

The <daoFactory> element is a grouping of Dao interfaces and implementations.

3.4.3.4.1. The <dao> Element

The <dao> element specifies a Dao interface and one implementation of that interface.

Table 3.15. Attributes of the <dao> element

Attribute	Description
interface	The interface that the Dao must implement. Structure value must be : namespace-qualified name of the class, followed by a comma, followed by (at a bare minimum) the name of the assembly that contains the class. Example: interface= "IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test"
implementation	An implementation of the Dao interface. Structure value must be : namespace-qualified name of the class, followed by a comma, followed by (at a bare minimum) the name of the assembly that contains the class. Example: implementation= "IBatisNet.Test.Dao.Implementations.Ado.AccountDao, IBatisNet.Test"

Prev	Up	Next
3.3. The Configuration File (dao.config)	Home	Chapter 4. Session Handler Implementations and Configuration