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 DataMapper configuration. Each named value in the properties file becomes a shell variable that can be used in the DataMapper configuration file and your Data Map definition files (see Section 3). For example, if the "properties" file contains

<?xml version="1.0" encoding="utf-8" ?> 
<settings>
  <add key="username" value="albert" />
</settings>

then all elements in the DataMapper configuration can use the variable ${username} to insert the value "albert". For example:

<dataSource connectionString="user id=${username};" 

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

resource="properties.config"

url="c:\Web\MyApp\Resources\properties.config"
-or-
url="file://c:\Web\MyApp\Resources\properties.config"

embedded="Resources.properties.config, MyApp.Data"

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

resource="properties.config"

url="c:\Web\MyApp\Resources\properties.config"
-or-
url="file://c:\Web\MyApp\Resources\properties.config"

embedded="Resources.properties.config, MyApp.Data"

key="username"

value="mydbuser"

Under ADO.NET, a database system is accessed through a provider. A database system can use a custom provider or a generic ODBC provider. The iBATIS .NET DataMapper uses a pluggable approach to using providers. Each provider is represented by an XML descriptor element found in a file called providers.config. The iBATIS .NET DataMapper distribution includes a standard providers.config file with a set of thirteen prewritten provider elements:

	Note
	If you use SQL Server 2005, you can configure the provider to allow Multiple Active Result Set (allowMARS="true") and add MultipleActiveResultSets=true in your connection string.

The providers.config file can be found under \source\IBatisNet.DataMapper.Test\bin\Debug in the iBATIS .NET source distribution or in the root folder of the .NET DataMapper 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 by setting the "enabled" attribute to "true".

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 sqlMap.config file.

resource="${root}providers.config"

url="c:\Web\MyApp\Resources\providers.config"
-or-
url="file://c:\Web\MyApp\Resources\providers.config"

embedded="Resources.providers.config, MyApp.Data"

There are three default settings used by the framework.. The settings appropriate for one application may not be appropriate for another. The <settings> element lets you configure these options and optimizations for the DataMapper instance that is created from the XML document. Each <settings> attribute has a default, and you can omit the <settings> element or any of its attributes. The <settings> attributes and the behavior they control are described in the following table.

Example: cacheModelsEnabled=”true”
Default: true (enabled)

Example: useStatementNamespaces=”false”
Default: false (disabled)

Example: validateSqlMap=”false”
Default: false (disabled)

Example: useReflectionOptimizer=”true”
Default: true (enabled)

The <typeAlias> element lets you specify a shorter name in lieu of a fully-qualified classname. For example:

  <typeAlias alias="LineItem" type="NPetshop.Domain.Billing.LineItem, NPetshop.Domain" />

You can then refer to LineItem where you would normally have to spell-out the fully qualified class name.

	Note
	In the .NET implementation, zero or more <typeAlias> elements can appear in the Data Map definition file, within an enclosing <alias> element.

alias="Category"

type=
"IBatisNet.Test.Domain.Category, 
IBatisNet.Test"

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

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

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

The <typeHandler> element allows for the configuration and use of a Custom Type Handler (see the Custom Type Handler section). This extends the DataMapper's capabilities in handling types that are specific to your database provider, are not handled by your database provider, or just happen to be a part of your application design.

  <typeHandler type="guid" dbType="Varchar2" callback="GuidVarchar"/>

	Note
	The DataMapper for .NET allows for zero or more <typeAlias> elements to appear in the Data Map definition file, within an enclosing <alias> element.

type="guid"

dbType="Varchar2"

callback="GuidVarchar"

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

<provider name="OleDb1.1"  />

<!-- The ${properties} are defined in an external file, -->
<!-- but the values could also be coded inline. -->

<!-- Connecting to SQL Server -->
<database>
  <provider name="sqlServer1.1" />
  <dataSource name="NPetstore" default="true" 
       connectionString="data source=(local)\NetSDK;database=${database};
       user id=${username};password=${password};"/>
</database>

<!-- Connecting to Oracle -->
<database>
  <provider name="oracleClient1.0"/>
  <dataSource name="iBatisNet" 
       connectionString="Data Source=${datasource};User Id=${userid};Password=${password}"/>
</database>
 
<!-- Connecting to Access -->
<database>
  <provider name="OleDb1.1" />
  <dataSource name="NPetstore" default="true" 
       connectionString="Provider=Microsoft.Jet.OLEDB.4.0;Data Source=${database}"/>
</database>

<!-- Connecting to a MySQL database --> 
<database>
  <provider name="ByteFx" />
  <dataSource name="NPetstore" default="true" 
       connectionString="Host=${host};Database=${database};
       Password=${password};Username=${username}" />
</database>

<!-- Connecting to a PostgreSQL database --> 
<database>
  <provider name="PostgreSql0.7" />
  <dataSource name="NPetstore" default="true" 
       connectionString="Server=${server};Port=5432;User Id=${userid};Password=${password};
       Database=${database};" />
</database>

On a daily basis, most of your work will be with the Data Maps, which are covered by Section 3. The Data Maps define the actual SQL statements or stored procedures used by your application. The parameter and result objects are also defined as part of the Data Map. As your application grows, you may have several varieties of Data Map. To help you keep your Data Maps organized, you can create any number of Data Map definition files and incorporate them by reference in the DataMapper configuration. All of the definition files used by a DataMapper instance must be listed in the configuration file.

Example 4.3 shows <sqlMap> elements for loading a set of Data Map definitions. Note that the <sqlMap> elements are nested in a <sqlMaps> element. For more about Data Map definition files, see Section 3.

<!-- Relative path from the project root directory using a property variable -->
<sqlMaps>
  <sqlMap resource="${root}Maps/Account.xml"/>
  <sqlMap resource="${root}Maps/Category.xml"/>
  <sqlMap resource="${root}Maps/Product.xml"/>
</sqlMaps>

<!-- Embedded resources using [extendednamespace.]filename, assemblyname -->
<sqlMaps>
  <sqlMap embedded="Maps.Account.xml, MyApp.Data"/>
  <sqlMap embedded="Maps.Category.xml, MyApp.Data"/>
  <sqlMap embedded="Maps.Product.xml, MyApp.Data"/>
</sqlMaps>

<!-- Full URL with a property variable -->
<sqlMaps>
  <sqlMap url="C:/${projectdir}/MyApp/Maps/Account.xml"/>
  <sqlMap url="C:/${projectdir}/MyApp/Maps/Category.xml"/>
  <sqlMap url="C:/${projectdir}/MyApp/Maps/Product.xml"/>
</sqlMaps>

Tip

Since the application root directory location differs by project type (Windows, Web, or library), it is best to use a properties variable to indicate the relative path when using the <sqlMap> "resource" attribute. Having a variable defined in a properties file makes it easy to change the path to all your Data Mapper configuration resources in one location (note the ${projectdir} and ${root} variables in the example above).