FrameworkGen - Configuring Entity Caching

Introduction

For those of you who are not aware, FrameworkGen is a .NET ORM that generates the data access persistence code for Windows and web applications. One of the features FrameworkGen was missing was the built in ability to cache entities. v4.0 of the tool now provides the ability to configure how entities are cached. This article will show you how to make use of the new caching functionality.

Background

I have been using FrameworkGen to generate C# class libraries and SQL stored procedures against SQL databases for a few years now on enterprise level projects. It has been my tool of choice because it produces separate class libraries for business components, data components and entities. The code that is generated is easy to work with and easy to understand.

In previous versions of FrameworkGen, if entity caching was required, you would need to code the caching of entities yourself within separate classes or possibly a Facade layer. FrameworkGen v4.0 makes this much simpler with the built in caching functionality provided by the CachingProvider class.

Caching Configuration

When entity caching is enabled in FrameworkGen (This can be enabled by selecting the AddEntityCachingSupport preference), the following app.config file will be created that sits within the solution items folder of the solution. The app.config file contains the following settings:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="Entities_CommandTimeout" value="30" />
    <add key="Entities_DataComponentsInversionOfControlFilePath" 
	value="C:\FrameworkGen\Working\SolutionItems\
		DataComponentsInversionOfControl.config" />
    <add key="Entities_EntityCachingEnabledDefault" value="false" />
    <add key="Entities_CacheDurationInMinutes" value="1440" />
    <add key="Entities_CachingProviderFullTypeName" 
	value="ElencySolutions.ESSurvey.BusinessComponents.CachingProvider" />
    <add key="Entities_SqlCacheDependenciesEnabled" value="false" />
    <add key="Entities_SqlCacheDependenciesDatabaseName" value="ESSurvey" />
  </appSettings>
  <connectionStrings>
    <add name="ESSurvey_Connection" 
	connectionString="server=TEST-PC\SQLEXPRESS;database=ESSurvey;
	User ID=sa;Password=v3ry53cur3!;Application Name=ElencySolutions.ESSurvey" 
	providerName="System.Data.SqlClient" />
  </connectionStrings>
  <system.web>
    <!-- the following section is only relevant if sql cache dependencies are enabled -->
    <caching>
      <sqlCacheDependency pollTime="10000" enabled="true">
        <databases>
          <add connectionStringName="ESSurvey_Connection" name="ESSurvey" />
        </databases>
      </sqlCacheDependency>
    </caching>
  </system.web>
</configuration>  

The settings that are relevant to caching are:

• Entities_EntityCachingEnabledDefault - This specifies whether caching is enabled on all business objects.
• Entities_CacheDurationInMinutes - This specifies the default cache duration in which entity objects should be stored in cache.
• Entities_CachingProviderFullTypeName - This allows the user to specify a caching provider that should be used for caching. Caching providers must implement the ICachingProvider interface.
• Entities_SqlCacheDependenciesEnabled - This specifies whether SQL cache dependencies should be used against tables for all business objects.
• Entities_SqlCacheDependenciesDatabaseName - This specifies the name of the database that should be used for SQL cache dependencies. This setting relates to the sqlCacheDependency element in the app.config.

Executing Cached Queries

If the app setting Entities_EntityCachingEnabledDefault has been set to true, you will be able to execute cache queries like the following:

Users users = new Users();

using (UserManager userManager = new UserManager())
{
    users = userManager.GetAll();
}

If the app setting Entities_EntityCachingEnabledDefault has been set to false, you can enable caching on your business object in the following ways:

1. Pass the caching enabled parameter into the business object:
   C#

   Users users = new Users();
   
   using (UserManager userManager = new UserManager(true))
   {
       users = userManager.GetAll();
   }

2. By setting the CachingEnabled property on the business object:
   C#

   Users users = new Users();
   
   using (UserManager userManager = new UserManager() { CachingEnabled = true })
   {
       users = userManager.GetAll();
   } 

3. By modifying the Initialise method in the generated business objects partial class to enable the caching.
   C#

   /// <summary>
   /// Business class for table 'User'.
   /// </summary>
   public sealed partial class UserManager
   {
       private bool _initialised;
       
       protected void Initialise()
       {
           if (_initialised)
   	    return;
   
   	_initialised = true;
           CachingEnabled = true;
       }
   }  

The cache duration can also be modified in the following 2 ways:

1. By setting the CacheDurationInMinutes property on the business object:
   C#

   Users users = new Users();
   
   using (UserManager userManager = new UserManager() { CacheDurationInMinutes = 60 })
   {
       users = userManager.GetAll();
   } 

2. By modifying the Initialise method in the generated business objects' partial class to change the cache duration:
   C#

   /// <summary>
   /// Business class for table 'User'.
   /// </summary>
   public sealed partial class UserManager
   {
       private bool _initialised;
       
       protected void Initialise()
       {
           if (_initialised)
   	    return;
   
   	_initialised = true;
           CacheDurationInMinutes = 60;
       }
   } 

Executing Cached Queries with SQL Cache Dependencies

Cached queries can also be configured to make use of SQL cache dependencies which can be useful in a load balanced/web farm environment.

A batch file 'SetupSqlCacheDependencies.bat' will be generated by FrameworkGen to enable SQL cache dependencies. This will create dependencies against all selected tables in the database. You will need to modify this so that only the tables you require SQL caching dependencies applied against are set up. The batch file content looks like the following:

@ECHO OFF

set SERVER=TestServer
set DATABASE=TestDatabase
set USERNAME=TestUser
set PASSWORD=TestPassword!

rem Enabling cache dependencies for database 'TestDatabase'.
"%WINDIR%\Microsoft.NET\Framework\v3.5\aspnet_regsql.exe" 
	-ed -S %SERVER% -d %DATABASE% -U %USERNAME% -P %PASSWORD%

rem Enabling cache dependencies for table 'Answer'.
"%WINDIR%\Microsoft.NET\Framework\v3.5\aspnet_regsql.exe" 
	-et -S %SERVER% -d %DATABASE% -U %USERNAME% -P %PASSWORD% -t Answer

If the app setting Entities_SqlCacheDependenciesEnabled has been set to true, you will be able to execute cache queries like the following:

Users users = new Users();

using (UserManager userManager = new UserManager())
{
    users = userManager.GetAll();
} 

If the app setting Entities_SqlCacheDependenciesEnabled has been set to false, you can enable SQL cache dependencies caching on your business object in the following ways:

1. By setting the SqlCacheDependenciesEnabled property on the business object:
   C#

   Users users = new Users();
   
   using (UserManager userManager = new UserManager() 
   	{ SqlCacheDependenciesEnabled = true })
   {
       users = userManager.GetAll();
   } 

2. By modifying the Initialise method in the generated business objects' partial class to enable the caching:
   C#

   /// <summary>
   /// Business class for table 'User'.
   /// </summary>
   public sealed partial class UserManager
   {
       private bool _initialised;
       
       protected void Initialise()
       {
           if (_initialised)
   	    return;
   
   	_initialised = true;
           SqlCacheDependenciesEnabled = true;
       }
   }

History

• 20/07/2010: Initial version
• 21/07/2010: Added extra information about setting cache duration