4.2. Installing the DataMapper for .NET

There are four steps to using iBATIS DataMapper with your application for the first time.

  1. Setup the distribution
  2. Add assembly references
  3. Visual Studio.NET Integration
  4. Add XML documents

4.2.1. Setup the Distribution

The official site for iBATIS DataMapper for .NET is our Apache site <http://ibatis.apache.org/>. The DataMapper is availabe in 2 types of distributions: a binary distribution that includes the required DataMapper 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 DataMapper 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 DataMapper 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 Table 4.1.

Table 4.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.Logging.Log4NetLog4Net factory adapter classes
IBatisNet.Common.TestTest project for IBatisNet.Common that can be used with NUnit
IBatisNet.DataAccessThe Data Access Objects framework (see separate DAO Guide)
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
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.DataMapper\bin\Debug. The created assemblies are :

  1. IBatisNet.Common.dll
  2. iBatisNet.DataMapper.dll

The DataMapper has external dependencies on :

  1. Castle.DynamicProxy.dll (creating proxies)

This dependencies can be found in the External-Bin folder and/or in the bin\Debug folder after building the solution.

[Tip]Tip

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

4.2.2. Add Assembly References

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

  1. IBatisNet.DataMapper.dll
  2. IBatisNet.DataAccess.dll (optional)
  3. IBatisNet.Common.dll (implied)
  4. Castle.DynamicProxy.dll (implied)

If you are using the Mapper singleton (see section 4.4.1), then the only reference you will need is to the DataMapper assembly. The Common and Castle.DynamicProxy assemblies are needed at runtime, but Visual Studio.NET will resolve the dependencies for you. If you are using the Data Access Objects framework, then you will need a reference to the DataAccess assembly too. So, start with the first, and add the others only if needed.

If you have built the IBatisNet solution as described in Section 4.2.1, the three assemblies (IBatisNet.DataMapper.dll, IBatisNet.Common.dll, and Castle.DynamicProxy.dll) that you will need should be in the bin/Debug folder of the IBatisNet.DataMapper project.

4.2.3. Add XML File Items

After adding the assembly references, you will need to add three types of XML files to your Windows, Web application, or library project (and Test project if you have one). These files are:

  • providers.config - A file used by the DataMapper to look up the definition of your selected database provider.
  • SqlMap.xml - A Data Map file that contains your SQL queries. Your project will contain one or more of these files with names such as Account.xml or Product.xml.
  • SqlMap.config - The DataMapper configuration file that is used to specify the locations of your SqlMap.xml files and providers.config file. It is also used to define other DataMapper configuration options such as caching. You will need to include one SqlMap.config file for each data source that your project has.

As expected, the SqlMap.config and providers.config files must be placed where the DataMapper 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 4.2. However, your project is not limited to using just these locations. The DataMapper 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 4.2. Default locations for the sqlMap.config and providers.config files

Windows, Library, or Test projects (using NUnit or equivalent)This would be the binary folder (such as /bin/debug) with the assembly (.dll) files and the App.config file
Web projectsIn the application root, where the Web.config file is located.


4.2.4. Visual Studio.NET Integration

Each configuration file (SqlMap.config, mappping file, providers.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 yours configuration files, you should add the schema files (SqlMap.xsd, SqlMapConfig.xsd, providers.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

or

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

or

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 4.1. IntelliSense example