Chapter 3. Configuration

3.1. Installation

There are three steps to using the iBATIS Data Access Objects (DAO) framework with your application for the first time.

  1. Setup the distribution
  2. Add assembly references
  3. Setup XML configuration documents

3.1.1. Setup the Distribution

The official site for iBATIS for .NET is our Apache site <>. The DataAccess framework is availabe in 2 types of distributions: a binary distribution that includes the required DataAccess assemblies and a source distribution that includes a VSN solution. To download either of the distributions, follow the link to the Downloads area on our web site, and select the either the binary or source distribution for the iBATIS .NET DataAccess V1.6.1 or later release (if you download the binary distribution, extract the files using a utility like WinZip or the extractor built into newer versions of Windows and skip ahead to the Add Assembly References section).

The source distribution includes a VSN solution and a number of C# projects. The distribution is in the form of a ZIP archive. You can extract the distribution using a utility like WinZip or the extractor built into newer versions of Windows. We suggest that you create an ibatisnet folder in your VSN project directory and extract the distribution there.

Under the distribution's source folder are eight folders that make up the iBATIS.NET distribution, as shown in the following table:

Table 3.1. Folders found in the iBATIS.NET source distribution

Folder nameDescription
External-BinDependency assemblies provided for your convenience.
IBatisNet.CommonAssembly of classes shared by DataAccess and DataMapper
IBatisNet.Common.TestTest project for IBatisNet.Common that can be used with NUnit
IBatisNet.DataAccessThe Data Access Objects framework
IBatisNet.DataAccess.ExtensionsContains a C# project for extensions to the DataAccess framework such as NHibernate support
IBatisNet.DataAccess.TestTest project for the DataAccess framework that can be used with NUnit
iBatisNet.DataMapperThe DataMapper framework (see seperate DataMapper Guide)
IBatisNet.DataMapper.TestTest project for the DataMapper that can be used with NUnit

You can load the IBatisNet.sln solution file into VSN and build the solution to generate the needed assemblies. There are seven projects in the solution, and all should succeed. The assemblies we need will be created under \source\IBatisNet.DataAccess\bin\Debug. The created assemblies are :

  1. IBatisNet.Common.dll
  2. iBatisNet.DataAccess.dll

The core DataAccess framework has external dependencies on

  1. Castle.DynamicProxy.dll (creating proxies)

The dependency is found in the External-Bin folder and can also be found in the bin\Debug folder after building the solution. In addition, the framework's IBatisNet.DataAccess.Extensions and IBatisNet.DataAccess.Test projects have dependencies on NHibernate.


If you will not be using NHibernate and have a problem building the solution due to that dependency, simply remove the IBatisNet.DataAccess.Extensions and IBatisNet.DataAccess.Test projects from the solution before building.

3.1.2. Add Assembly References

Switching to your own solution, open the project that will be using the iBATIS.NET DAO Framework. Depending on how your organize your solutions, this might not be the project for your Windows or Web application. It may be a library project that your application project references. You need to add two references to your project:

  1. IBatisNet.DataAccess.dll
  2. IBatisNet.Common.dll

Additionally, the DAO framework has the following external dependencies:

Table 3.2. Dependencies

NameDescriptionAssembly DLLs
Castle dynamic proxy proxy generatorCastle.DynamicProxy.dll

3.1.3. Setup XML configuration documents

You will need to add two or more XML file items to your Windows or Web application project (and Test project if you have one). These files are:

  • dao.config - The Data Access configuration file that is used to specify your DAOs, providers.config file location, and data source information.
  • providers.config - A file used by the framework to look up the definition of your selected database provider.
  • SqlMap.config and Data Map definition XML files - Required when using the iBATIS DataAccess framework in conjunction with the iBATIS DataMapper framework

The dao.config and providers.config files must be placed in a location where the framework can find them at runtime. Depending on the type of project you have, the default expected location of these 2 files will be different, as shown in Table 3.3. However, your project is not limited to using just these locations. The DataAccess framework provides other options for placing these files in locations that are more suitable for your project instead of using the default locations. These options are covered later in this guide.

Table 3.3. Where to place the dao.config file

Windows, Library, or Test projects (using NUnit or equivalent)Place with the assembly (.dll) files and the app.config file
Web projectsPlace in the project root, with the web.config file

3.1.4. Visual Studio.NET Integration

The configuration file (dao.config) is associated to a schema. The benefits of associating an XML document with a schema are to validate the document (which is done at runtime) and to use editing features such as IntelliSense/content completion assistance.

To allow association of the schemas in VS.NET XML editor to your configuration file, you should add the schema file (DaoConfig.xsd to either your VS.NET project or in your VS.NET installation directory. The VS.NET directory will be either

C:\Program Files\Microsoft Visual Studio 8\Xml\Schemas for VS.NET 2005


C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml for VS.NET 2003


C:\Program Files\Microsoft Visual Studio .NET\Common7\Packages\schemas\xml for VS.NET 2002

depending on your version of VS.NET. It is typically easier to place the file in the well known location under the VS.NET installation directory than to copy the XSD file for each project you create.

Once you have registered the schema with VS.NET you will be enough to get IntelliSense and validation of the configuration file from within VS.NET.

IntelliSense example

Figure 3.1. IntelliSense example