There are four steps to using iBATIS DataMapper with your application for the first time.
- Setup the distribution
- Add assembly references
- Visual Studio.NET Integration
- Add XML documents
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 name | Description |
|---|---|
| External-Bin | Dependency assemblies provided for your convenience. |
| IBatisNet.Common | Assembly of classes shared by DataAccess and DataMapper |
| IBatisNet.Common.Logging.Log4Net | Log4Net factory adapter classes |
| IBatisNet.Common.Test | Test project for IBatisNet.Common that can be used with NUnit |
| IBatisNet.DataAccess | The Data Access Objects framework (see separate DAO Guide) |
| IBatisNet.DataAccess.Extensions | Contains a C# project for extensions to the DataAccess framework such as NHibernate support |
| IBatisNet.DataAccess.Test | Test project for the DataAccess framework that can be used with NUnit |
| iBatisNet.DataMapper | The DataMapper framework |
| IBatisNet.DataMapper.Test | Test 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 :
IBatisNet.Common.dlliBatisNet.DataMapper.dll
The DataMapper has external dependencies on :
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]](images/tip.png) | 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. |
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:
- IBatisNet.DataMapper.dll
- IBatisNet.DataAccess.dll (optional)
- IBatisNet.Common.dll (implied)
- 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.
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 projects | In the application root, where the
Web.config file is located. |
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.
