News, examples, tips, ideas and plans.
Thoughts around ORM, .NET and SQL databases.

Thursday, March 20, 2014

NonTransactionalReads in DataObjects.Net 5.0

NonTransactionalReads is a specific Session option that allows to read once fetched entities right from Session cache without the requirement to have an open transaction. This mode might be useful for desktop application that have only one Session instance for the entire lifetime of application or for services like auditing, logging, etc. that need to read persistent fields without having any idea of sessions, transactions, etc.

To demonstrate the approach, let's start with a sample. Here is the persistent class with one lazy loading field:
[HierarchyRoot]
public class Country : Entity
{
    [Field, Key]
    public int Id { get; private set; }

    [Field(Length = 30)]
    public string Name { get; set; }

    [Field(Length = 3)]
    public string Code { get; set; }

    [Field(LazyLoad = true)]
    public string Description { get; set; }

    public Country(Session session)
        : base(session) {}
}
Say, we want to have a cache of countries in our application. We create some countries on Domain start, e.g.:

var domainConfiguration = DomainConfiguration.Load("Default");
var domain = Domain.Build(domainConfiguration);

using (var session = domain.OpenSession())
using (var tx = session.OpenTransaction()) {
    new Country(session) {
        Code = "AND",
        Name = "Andorra",
        Description = "A tiny country in the middle of Europe"
    };
    new Country(session) {
        Code = "ATA",
        Name = "Antarctica",
        Description = "Icy paradise for penguins"
    };
    // other countries...
    tx.Complete();
}

To implement some sort of cache in earlier version of DataObjects.Net you would load countries in every transaction or avoid frequent loading of persistent objects from database by converting them into some kind of POCO and cache them.

In DataObjects.Net 5.0 you can do this in a more comfortable way using the new NonTransactionalReads flag.
// Configuring session
var options = new SessionConfiguration(SessionOptions.Default | SessionOptions.NonTransactionalReads);

var session = domain.OpenSession(options);
Dictionary<string, Country> cache;

// Loading cache with data in one transaction
using (var tx = session.OpenTransaction()) {
    cache = session.Query.All<Country>().ToDictionary(i => i.Code);
    tx.Complete();
}

// accessing data from another transaction
using (var tx2 = session.OpenTransaction()) {

    // cached objects are not being reloaded from database. they are consumed as is
    var antarctica = cache["ATA"];
    Console.WriteLine(antarctica.Name);

    // accessing a lazy loading field. session loads it on demand
    Console.WriteLine(antarctica.Description);

    tx2.Complete();
}

// disposing session. Data is not accessible anymore
session.Dispose();

What is more interesting, the same behavior can be achieved without using any transactions at all. Let's re-write the sample:
// Configuring session
var options = new SessionConfiguration(SessionOptions.Default | SessionOptions.NonTransactionalReads);

var session = domain.OpenSession(options);
Dictionary<string, Country> cache;

// Loading cache with data without any transaction
cache = session.Query.All<Country>().ToDictionary(i => i.Code);

// accessing data 
var antarctica = cache["ATA"];
Console.WriteLine(antarctica.Name);

// accessing a lazy loading field. session loads it on demand
Console.WriteLine(antarctica.Description);

// disposing session. Data is not accessible anymore
session.Dispose();

So, the key points of the NonTransactionalReads mode:
  1. No matter how data is loaded from database (with the help of transaction or not), it is accessible from outside the boundaries of the transaction, if any.
  2. Data is cached on Session level. As long as the Session is alive (not disposed), the data will be available from its cache.
  3. In case of accessing LazyLoad fields, Entity references and EntitySets, data is automatically fetched from database on demand.

Monday, March 17, 2014

DataObjects.Net 5.0 meets NLog & log4net

In the previous post we explained DataObjects.Net built-in logging capabilities. Now it is time to show how popular logging libraries like log4net and NLog can be integrated with it.

We would need the list of names of built-in logs:


  • Xtensive.Orm - logs Session & Transaction-related events and exceptions.
  • Xtensive.Orm.Building - logs events during the Domain building process.
  • Xtensive.Orm.Sql - logs SQL statements sent to database server.
  • Xtensive.Orm.Upgrade - logs events during database schema upgrade.

  • log4net

    1. Add DataObjects.Net logging provider for log4net. It will automatically add log4net.
    2. Set up log provider in Xtensive.Orm configuration section

       <Xtensive.Orm>
         <domains>
           <domain ... >
           </domain>
         </domains>
         <logging provider="Xtensive.Orm.Logging.log4net.LogProvider, Xtensive.Orm.Logging.log4net">
       </Xtensive.Orm>
      
    3. Configure log4net. Use the above-mentioned loggers' names, e.g.:

       <?xml version="1.0" encoding="utf-8" ?>
       <configuration>
         <configSections>
           ...
           <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>
         </configSections>
       
         <log4net>
           <appender name="ConsoleAppernder" type="log4net.Appender.ConsoleAppender">
             <layout type="log4net.Layout.PatternLayout">
               <conversionPattern value="%date [%thread] %-5level %logger %message%newline" />
             </layout>
           </appender>
         
           <logger name="Xtensive.Orm">
             <level value="ALL" />
             <appender-ref ref="ConsoleAppernder" />
           </logger>
         </log4net>
       </configuration>
      
      

    NLog

    1. Add DataObjects.Net logging provider for NLog. It will automatically add NLog.
    2. Set up log provider in Xtensive.Orm configuration section

       <Xtensive.Orm>
         <domains>
           <domain ... >
           </domain>
         </domains>
         <logging provider="Xtensive.Orm.Logging.NLog.LogProvider, Xtensive.Orm.Logging.NLog">
       </Xtensive.Orm>
      
    3. Configure NLog. Use the above-mentioned loggers' names, e.g.:

          <?xml version="1.0" encoding="utf-8" ?>
          <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      
            <targets>
              <target name="console" xsi:type="Console" />
            </targets>
      
            <rules>
              <logger name="Xtensive.Orm" minlevel="Debug" writeTo="console" />
            </rules>
          </nlog>
      


    Pretty simple, huh? You can even write your own log provider with ease. Just take a look at the implementation of these two in DataObjects.Net Extensions repository, default branch.

    Wednesday, March 05, 2014

    DataObjects.Net 5.0 built-in logging

    Yeah, we have to admit it - logging in DataObjects.Net 4.x was implemented quite odd and its API was not clear even to some of product developers, not to mention customers who were wondering whether the bloody logging works at all and how the hell it is supposed to be configured. Finally, these days are gone and starting from DataObjects.Net 5.0 we re-implemented the logging.

    So, what has changed? The answer is - almost all, including inconsistent loggers' names, tricky xml configuration and peculiar log formats. Imho, the best characteristic for the new logging will be "brain-dead obvious" "extremely simple".

    OK, let's dive into the details.

    Loggers

    These are named logs that record messages from specific parts of DataObjects.Net. There are 4 of them:


  • Xtensive.Orm - logs Session & Transaction-related events and exceptions.
  • Xtensive.Orm.Building - logs events during the Domain building process.
  • Xtensive.Orm.Sql - logs SQL statements sent to database server.
  • Xtensive.Orm.Upgrade - logs events during database schema upgrade.

  • Log writers


  • Console - writes messages to application's console window, if any. Useful for small & test projects.
  • DebugOnlyConsole - the same as Console but writes log data only when a project is run in Debug mode.
  • path_to_file - appends log messages to a specified file. If file is absent, it will be created. Useful for development & production environments. path_to_file can be either absolute or relative to the application location.
  • None - writes to /dev/null.

  • Configuration

    Configuration of built-in logging is made in application configuration file (app.config or web.config). Logger configuration takes 2 parameters: logger name as source and log writer name as target.

    Example: Logging everything to Console
      <Xtensive.Orm>
        <domains>
          <domain name="Default".../>
        </domains>
    
        <logging>
          <log source="Xtensive.Orm" target="Console"/>
          <log source="Xtensive.Orm.Building" target="Console"/>
          <log source="Xtensive.Orm.Sql" target="Console"/>
          <log source="Xtensive.Orm.Upgrade" target="Console"/>
        </logging>
      </Xtensive.Orm>
    
    
    Example: Logging everything to files
      <Xtensive.Orm>
        <domains>
          <domain name="Default".../>
        </domains>
    
        <logging>
          <log source="Xtensive.Orm" target="C:\Orm.log"/>
          <log source="Xtensive.Orm.Building" target="C:\Orm.Building.log"/>
          <log source="Xtensive.Orm.Sql" target="C:\Orm.Sql.log"/>
          <log source="Xtensive.Orm.Upgrade" target="C:\Orm.Upgrade.log"/>
        </logging>
      </Xtensive.Orm>
    
    

    To simplify things in case you want to write messages from all loggers into the same stream, you may want to use our magic asterisk, like this: Example: Logging everything to a file
      <Xtensive.Orm>
        <domains>
          <domain name="Default".../>
        </domains>
    
        <logging>
          <log source="*" target="C:\Orm.log"/>
        </logging>
      </Xtensive.Orm>
    
    
    In addition to the built-in log writers DataObjects.Net 5 is shipped with 2 extensions allowing to redirect logging output to NLog & log4net. Read about that in the second part.