How to: Configure the OpenAccessContext via Config File

This article is relevant to entity models that utilize the deprecated Visual Studio integration of Telerik Data Access. The current documentation of the Data Access framework is available here.

Telerik Data Access allows you to configure the BackendConfiguration object by writing code that sets the values of the BackendConfiguration instance.

BackendConfiguration backend = new BackendConfiguration();
backend.Backend = "oracle";
backend.Runtime.AllowReadAfterDelete = true;
backend.SecondLevelCache.Enabled = true;
backend.SecondLevelCache.NumberOfObjects = 6000;
EntitiesModel dbContext = new EntitiesModel(backend);
Dim backend As New BackendConfiguration()
backend.Backend = "oracle"
backend.Runtime.AllowReadAfterDelete = True
backend.SecondLevelCache.Enabled = True
backend.SecondLevelCache.NumberOfObjects = 6000
Dim dbContext As New EntitiesModel(backend)

With this approach, there is an issue, in the case where you want to change the backend settings while the application is deployed.

For example, your web site load has increased and you would like to increase the connections available in the connection pool. Or there are performance issues and you would like to turn logging on so you can use the Telerik Data Access Profiler to profile your application. By configuring your backend in the code, the only way to change the configuration is to re-compile your application and re-deploy it.

There is a much more straightforward way to perform such configuration changes, by using XML entries in the app/web.config file. For example:

<configSections>
    <section name="openAccessConfiguration"
             type="Telerik.OpenAccess.Config.OpenAccessConfigSectionHandler, 
                   Telerik.OpenAccess"
             requirePermission="false" />
</configSections>
<openAccessConfiguration xmlns="http://www.telerik.com/OpenAcessConfiguration">
    <backendConfiguration name="OracleConfiguration" backend="oracle" connectionTimeout="134" 
                          driver="TestDriver" providerName="TestProvider">
        <runtime allowReadAfterDelete="true" checkObjectConsistencyOnCommit="true" 
                 classBehavior="insertOnly" />
        <secondLevelCache cacheQueryResults="true" numberOfObjectsPerQueryResults="123" 
                          enabled="true" />
        <logging downloaderEnabled="true" eventStoreCapacity="234" metricStoreCapacity ="345" />
        <connectionPool activeConnectionTimeout="456" maxActive="567" blockWhenFull="false" />
        <highLowKeyGenerator grabSize="678" start="789" />
    </backendConfiguration>
</openAccessConfiguration>

Configuring the BackendConfiguration Object in XML

Here are the steps that should be taken in order to take advantage of this approach:

You need to declare a new configuration section in the config file named openAccessConfiguration.

<?xml version="1.0" encoding="utf-8"?>
<configuration>  
    <configSections>
        <section name="openAccessConfiguration"
                 type="Telerik.OpenAccess.Config.OpenAccessConfigSectionHandler, 
                       Telerik.OpenAccess"
                 requirePermission="false" />
    </configSections>
    <connectionStrings>
        <add name="SofiaCarRental20Connection"
             connectionString="data source=.\sqlexpress;initial catalog=SofiaCarRental20;
                               integrated security=True"
             providerName="System.Data.SqlClient" />
    </connectionStrings>
</configuration>

Create the configuration with the root node called openAccessConfiguration.

<?xml version="1.0" encoding="utf-8"?>
<configuration>    
    <configSections>
        <section name="openAccessConfiguration"
                type="Telerik.OpenAccess.Config.OpenAccessConfigSectionHandler, 
                      Telerik.OpenAccess"
                requirePermission="false" />
    </configSections>
    <openAccessConfiguration xmlns="http://www.telerik.com/OpenAcessConfiguration">
        <backendConfiguration name="OracleConfiguration">
        </backendConfiguration>
    </openAccessConfiguration>
    <connectionStrings>
        <add name="SofiaCarRental20Connection"
            connectionString="data source=.\sqlexpress;initial catalog=SofiaCarRental20;
                              integrated security=True"
            providerName="System.Data.SqlClient" />
    </connectionStrings>
</configuration>

Declaring the XML namespace attribute xmlns=http://www.telerik.com/OpenAcessConfiguration is not mandatory. However, it is required if you want to have IntelliSense while writing the configuration entries.

Next, you need to define the backend configuration object inside the <backendConfiguration/> XML node and its sub-nodes.

One <openAccessConfiguration/> can have multiple <backendConfiguration/> sub-nodes. This is possible for the case where you want to use different backend configurations in different parts of the application. For example, you might want to have one backend configuration for accessing oracle database in the application and one backend configuration for accessing MsSql.

<openAccessConfiguration xmlns="http://www.telerik.com/OpenAcessConfiguration">
    <backendConfiguration name="MsSqlConfiguration"> //write the MsSql configuration here.
    </backendConfiguration>
    <backendConfiguration name="OracleConfiguration"> //write the Oracle configuration here.
    </backendConfiguration>
</openAccessConfiguration>

After the backend configuration has been configured in XML, you should call the static MergeBackendConfigurationFromConfigFile method that applies the configuration file entries to a BackendConfguration object. The MergeBackendConfigurationFromConfigFile method has three overloads that allow you to specify the merge mode and the name of the backend configuration that should be merged. For example:

BackendConfiguration fromCodeConfiguration = EntitiesModel.GetBackendConfiguration();
BackendConfiguration.MergeBackendConfigurationFromConfigFile(fromCodeConfiguration, 
    ConfigurationMergeMode.ConfigFileDefinitionWins, "XmlConfigName");
EntitiesModel dbContext = new EntitiesModel(fromCodeConfiguration);
Dim fromCodeConfiguration As BackendConfiguration = EntitiesModel.GetBackendConfiguration()
BackendConfiguration.MergeBackendConfigurationFromConfigFile(fromCodeConfiguration,  _
    ConfigurationMergeMode.ConfigFileDefinitionWins, "XmlConfigName")
Dim dbContext As New EntitiesModel(fromCodeConfiguration)

Using the above API will apply the backendConfiguration with name XmlConfigName from XML. If no such configuration is found, the default will not be applied, but an exception will be thrown instead.

There are three merge modes:

  • ConfigFileDefinitionWins - if a configuration property is explicitly set in code and in configuration file, the value from configuration file will be the one that will be used during runtime.
  • CompiledConfigurationWins - if a configuration property is explicitly set in code and in configuration file, the value set in code will be the one that will be used during runtime.
  • LoggingOnly - defines a mode in which the only settings read from configuration file will be the logging settings. If a logging setting is explicitly set in code and in configuration file, the value from the configuration file will be the one used by the runtime. The purpose of this merge mode is to allow you to dynamically switch logging on and off for profiling purposes.

See Also: