Configuration

You can configure LightSpeed through code or through the configuration file (web.config or appname.exe.config depending on the type of application).  We discussed the core configuration options in the Basic Operations chapter.  In this section we will review other configuration options.

For a full list of configuration settings, see the Appendices.

How to Configure LightSpeed

In general, it is best to configure LightSpeed through the configuration file.  This ensures that all instance‑specific configuration is externalised from the code, so that the code can be easily moved between different environments.

As mentioned in the Basic Operations chapter, to use the configuration file you must declare and implement a lightSpeedContexts section.  You can then define particular configurations by adding elements to that section, using the add tag:

<configSections>
   <section name="lightSpeedContexts" 
              type="Mindscape.LightSpeed.Configuration.LightSpeedConfigurationSection, Mindscape.LightSpeed" />
</configSections>

<lightSpeedContexts>
  <add name="Test" /> <!-- We will add attributes here shortly -->
</lightSpeedContexts>

Individual configuration options are specified as attributes of the add tag.

A few settings are not available through the configuration file.  These settings can only be configured in code.  These are typically advanced settings such as custom strategy classes which do not need to change between environments.

Loading the Configuration

A configuration is represented by a LightSpeedContext object.  To load a LightSpeedContext from configuration, pass the name of the configuration file entry to the LightSpeedContext constructor:

private static readonly LightSpeedContext _context = new LightSpeedContext("Test");

You can still modify the context object in code by setting its properties, for example if you need to apply a setting which is not available through configuration.

Setting Up a LightSpeedContext in Code

You can create a blank LightSpeedContext using the default constructor:

private static readonly LightSpeedContext _context = new LightSpeedContext();

This will not load any settings from the configuration file.  You can then set up the context object by settings its properties.

You will usually use code-only setup only for prototypes and tests, because it leads to maintenance headaches when the code needs to be moved between environments.

Context Per Application, Not Context Per Request

In general, you should not create multiple instances of LightSpeedContext.  As shown above, create a single (static) instance, and share it across your entire application.  You will not usually modify a context object after initialisation, because your configuration will not change during a run.  So it is safe to share a context object even across a highly concurrent application such as a Web site.

By a single instance, we mean a single instance per database.  If your application talks to two databases – for example copying data between them – then of course you will need two contexts.  The point is that you should not create new contexts on every page or every screen: you should reuse the same context instance or instances throughout the lifetime of your application.

Preferring the singleton pattern is not just a matter of not creating superfluous objects – redundant contexts can affect performance, for example resulting in superfluous database queries to allocate entity Ids (see Identity Generation in the chapter Controlling the Database Mapping).

There are some cases where you may want to create multiple contexts. Generally we have found these would be either:

·         You are connecting to more than one data source, or

·         You are dealing with a multi-tenanted scenario and need to customize the connection string per tenant

Terminology

If you’re familiar with LINQ to SQL or the Entity Framework, you may associate the term ‘context’ with a domain model or database session, as in the LINQ to SQL DataContext.  A LightSpeedContext is not like a DataContext: it holds configuration settings, not database data.  The LightSpeed equivalent of a DataContext or ObjectContext is a unit of work.

Configuration Settings

There are a lot of configuration settings on LightSpeedContext, which are described in more detail in the relevant section and listed in the Appendices.  This section lists some of the most commonly used.

All of these (and the other) configuration settings have equivalent properties on the LightSpeedContext class.