Setup Your Configuration For Nvigorate

Table of Contents [Hide/Show]

Where does the configuration go?
End Result
Connection String
MapConfiguration
   Only What You Need To Know
   Getting Technical
LogConfiguration
   So Why Would I Use Nvigorate's LogManager?
   Only What You Need To Know

Edit

Where does the configuration go?

The first important thing about Nvigorate configuration is knowing where to put the configuration blocks. If you're building a proper n-tier application and all database access is through a service layer, then the MapConfiguration section should only go in the .config of your service host.

Alternately, for things like the LogManager configuration block, you can place that in multiple .config files depending on whether or not you want to use Nvigorate's logging at multiple tiers of the application.

Edit

End Result

Whether you just want the xml config to get started or not, it's helpful to see the the entire thing and then talk about each piece separately.


<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="MapConfiguration" 
         type="Nvigorate.Relational.Mapping.Index.MapConfigurationSection, Nvigorate, Version=0.8.0.0, Culture=neutral, PublicKeyToken=e95d15436b84113a" />
    <section name="LogManager" 
         type="Nvigorate.Logging.LogManagerSection, Nvigorate, Version=0.8.0.0, Culture=neutral, PublicKeyToken=e95d15436b84113a" />
  </configSections>

  <connectionStrings>
    <add
      name="demo"
      connectionString="Data Source=localhost;Initial Catalog=nvigorateDemo;Integrated Security=True"
      providerName="Nvigorate.Data.MSSQL9Provider, Nvigorate"/>    
  </connectionStrings>

  <MapConfiguration>
    <scanTargets>
      <scan namespace="Nvigorate.Demo.Domain.Maps" />
    </scanTargets>
  </MapConfiguration>

  <LogManager application="Nvigorate.Test">
    <logAdapters>
      <add type="Nvigorate.Test.Aspect.TestLogAdapter, Nvigorate.Test">
        <config>
          <connectionName>demo</connectionName>
          <errorLevel>2</errorLevel>
        </config>
      </add>
    </logAdapters>
  </LogManager>

</configuration>

Edit

Connection String

There's important things about Nvigorate connection strings:
- the name of the connection string correlates to the RepositoryName used in mappings (more on this later).
- you need to use the Provider attribute to tell Nvigorate which IDatabaseProvider implementation it should use to communicate with the database.


<connectionStrings>
     <add
      name="demo"
      connectionString="Data Source=localhost;Initial Catalog=nvigorateDemo;Integrated Security=True"
      providerName="Nvigorate.Data.MSSQL9Provider, Nvigorate"/>
</connectionStrings>

Edit

MapConfiguration

Edit

Only What You Need To Know

The MapConfigruation block is what tells Nvigorate where to search for fluent maps. In order to use it, you first have to include it in the config sections of your .config file like this:


<configSections>
    <section 
        name="MapConfiguration" 
        type="Nvigorate.Relational.Mapping.Index.MapConfigurationSection, Nvigorate, 
              Version=0.8.0.0, Culture=neutral,
              PublicKeyToken=e95d15436b84113a" 
    />

 ...

The MapConfiguration section can then be used to identify the namespaces to scan for FluentMaps. In our demo application, I've placed all my fluent maps in the same assembly as my domain model, however, I've put them in a separate namespace:


<MapConfiguration>
  <scanTargets>
    <scan namespace="Nvigorate.Demo.Domain.Maps" />
  </scanTargets>
</MapConfiguration>

Edit

Getting Technical

Nvigorate's central repository for all it's relational maps is called MapIndex. The first time MapIndex is created it checks for this configuration and loads maps from xml or FluentMaps as specified by the scan tags and then keeps those maps in memory for the lifetime of the application.

XML maps, though technically supported, are very likely going to be deprecated because of how difficult it is to use some of the more advanced mapping features that Nvigorate offers.

Advanced
You can tell MapIndex to cache what it loads as a binary dump to disk so that next time it loads it just pulls up the binary. There are risks to this however and a more in depth discussion on that capability is warranted.

Edit

LogConfiguration

The log manager in Nvigorate is a pretty simple creature. Essentially you have a single LogManager and based on how you configure it you can have one or more log adapters which will handle the incoming messages specific to their individual configurations and implementations. Why not use Log4Net? While I hate to blaspheme, I've heard a lot of complaints in the past and honestly, I just wanted something super simple to use and customize and that's what the logging in Nvigorate is: simple in use and extensibility.

Edit

So Why Would I Use Nvigorate's LogManager?

LogManager does a little data collection for you in building the the metadata for the exception. It will collect the machine name, user name, application (from configruation), assembly, class name, and method in which the exception occurred. So all that is collected by the LogManager and then passed on to every adapter including any custom adapter you choose to develop against the ILogAdapter interface.

The primary reason I think you should use LogManager is that all of Nvigorate currently logs exceptions to LogManager. If you don't configure it, no harm done, but you won't get any of Nvigorate's ORM exceptions which can be life savers because if you're getting exceptions when interacting with the database, the exceptions include all the T-SQL and parameter values in addition to the underlying SqlException.

If your team is already having a lot of success with Log4Net and you're industrious, you could always choose to make a Log4Net adapter OR you could pester me until I do it.

Edit

Only What You Need To Know

The log adapter I'll be demonstrating is the DatabaseLogAdapter. Why? Because it's so easy to use that it will even detect the absence of the required schema and create it for you on the fly.

First you'll need to add the LogManager section with the configSections (just like we did for MapConfiguration above):


 <configSections>
   <section 
       name="LogManager" 
       type="Nvigorate.Logging.LogManagerSection, Nvigorate, 
             Version=0.8.0.0, Culture=neutral, 
             PublicKeyToken=e95d15436b84113a" />

...

Next you simply tell the LogManager the name of the application it's Logging for and add and configure the logAdapters you want to use:


<LogManager application="Nvigorate.Demo.Services">
  <logAdapters>
    <add type="Nvigorate.Logging.DatabaseLogAdapter, Nvigorate, 
               Version=0.8.0.0, Culture=neutral, PublicKeyToken=e95d15436b84113a">
      <config>
        <connectionName>Config</connectionName>
        <errorLevel>2</errorLevel>
      </config>
    </add>
  </logAdapters>
</LogManager>

Notice the two configuration values specific to the DatabaseLogAadapter are the connectionName which is the name of the connection string to use from the section of your .config and the errorLevel that you want this log adapter to respond to. Error level is pretty arbitrary and is decided when you make a call to the LogManager. The following are examples of calls to LogManager:


LogManager.LogError(Exception ex); // assumes a Severities.Low

LogManager.LogError(Exception ex, Severities.Moderate);

LogManager.LogError(Exception ex, Severities.High, "An error totally happened {0}", parameterValue);

As you can see, it's a very simple API. I've already had it pointed out that logging isn't just an exception concern and I plan to address that eventually.

If you don't already have it, you'll need the schema for the database in this demo which is available here
OR you can go on to creating the Database Schema representation in your source using the template here.