Resources
Data Access has been discontinued. Please refer to this page for more information.

Runtime Configuration

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.

The RuntimeConfiguration class allows you to configure runtime behavior properties, such as specifying concurrency control, controlling the data access kind for the persistent classes, etc. The Runtime Functionality can be configured in two ways:

The RuntimeConfiguration object is accessible through the Runtime property that is exposed by the BackendConfiguration class.

public partial class EntitiesModel
{
   static EntitiesModel()
   {
       BackendConfiguration.RuntimeConfiguration runtimeConfig = backend.Runtime;
   }
}

Partial Public Class EntitiesModel
    Shared Sub New()
        Dim runtimeConfig As BackendConfiguration.RuntimeConfiguration = backend.Runtime
    End Sub
End Class

The RuntimeConfiguration class exposes the following properties:

  • MediumTrust - if set to true, allows Telerik Data Access to work in a medium trust environment (ASP.NET). Under medium trust, some operations cannot be performed and the Telerik Data Access runtime must be made aware of this. This affects things where privileged operations are needed. Default value is False.
  • SupportConcurrentThreadsInScope - supports multiple threads accessing one OpenAccessContext, i.e., one OpenAccessContext maybe used from more than one thread at the same time. Enabling the support for concurrent threads will turn on additional synchronization, which can affect the performance. Default value is False.
  • CheckObjectConsistencyOnCommit - controls whether the consistency of the object graph in the local cache is ensured. If set to True, this makes sure that all birectional relationships (one-many and many-many) are in sync. This setting is useful when using managed collections. Since this is a time consuming operation it should be used for debugging purposes only. Default value is False.
  • ReadOnly - controls if write operations against the database are permitted. Default value is False.
  • LockTimeoutMSec - when Telerik Data Access cannot grant a lock to a transaction on a resource because another transaction already owns a conflicting lock on that resource, the first transaction becomes blocked waiting on the resources. The Lock Timeout settings allows Telerik Data Access to set a maximum time that a statement waits on a blocked resources.
  • LockSqlSuffix - gets or sets the SQL that is appended to a 'SELECT FOR UPDATE' statement which is used to obtain a write lock when using pessimistic concurrency control.
  • CloseDatabaseWithActiveTransactions - controls if closing a database with active transactions is allowed. Default value is True.
  • PerformanceCounter - controls if performance counters for the Second level cache and Second level cache cluster are enabled. Default value is False.
  • PerformanceCounterName - controls the name of the performance counter instance. Default value is "{ConnectionId}-{ProcessId}".
  • ParallelFetchingEnabled - controls parallel fetching of a sub collection. This makes use of Multiple Active Result Sets if the selected backend supports it. Default value is False.
  • AllowReadAfterDispose - controls if read operations on the already fetched instances are allowed after managing context disposal.
  • AllowReadAfterDelete - controls if read operations on the already deleted instances are allowed.
  • CacheReferenceType - specifies the type of the references maintained by the cache of the OpenAccessContext:
    • AUTO - specifies that references to fetched data are strongly held and references to user instances are weakly held.
    • STRONG - specifies that all references can't be reclaimed.
    • WEAK - specifies that a reference is maintained using a System.WeakReference allowing the garbage collector to reclaim the object.
  • ReturnNullForRowNotFound - controls if null is to be returned when an object references an object that does not exist in the database by foreign key. When false RownNotFoundException is being thrown. Default value is False.
  • RequirePersistentClasses - controls if the opening of a database requires persistent classes to be present. Default value is True.
  • Concurrency - controls which objects are locked when pessimistic concurrency control is used. The Commit operation will verify that modified objects have not been updated by another transaction meanwhile.
    • Optimistic (default) - concurrency control happens during transaction commit. Transaction conflicts will be detected during Transaction.Commit() and will cause Telerik.OpenAccess.Exceptions.OptimisticVerificationException. Transaction will verify that modified objects have not been updated by another transaction meanwhile. Only available with optimistic transactions.
    • Pessimistic Explicit - concurrency control happens during entire transaction. Transaction conflicts will be detected for all reading/modifying methods and will cause Telerik.OpenAccess.Exceptions.LockNotGrantedException to be thrown.
    • Pessimistic Locking All - all objects are write-locked when fetched from the data store. Concurrency control happens during entire transaction. Transaction conflicts will be detected for all reading/modifying methods and will cause Telerik.OpenAccess.Exceptions.LockNotGrantedException to be thrown.
    • Pessimistic Locking First - first object is write-locked when fetched from the data store. Concurrency control happens during entire transaction. Transaction conflicts will be detected for all reading/modifying methods and will cause Telerik.OpenAccess.Exceptions.LockNotGrantedException to be thrown.
  • CompiledQueryCacheSize - controls the maximum number of queries that are kept in the pre-compiled query cache. The pre-compiled query cache is the one that holds already computed translations from LINQ to the corresponding SQL expressions. This property controls the size of the compiled query cache. The default value is 0, which is internally translated to the default size of 1000. Negative numbers will lead to a size of 1000, too. The only reason to increase the value would be that you have more than 1000 different queries for which you need to store the compiled query information.
  • UseUTCForAutoSetValues - controls if the datetime values that are automatically set during commit will use UTC. Default value is False.

  • UseUTCForReadValues - controls if the datetime values that are read will be converted to use UTC. Default value is False.

  • NullsFirst - controls if the database will use the NULLS FIRST sorting option (when you order by a certain column the position of the records that have null in that column). Not all database servers support this option. (For SQL server it is the default behavior – in oracle nulls are at the end so you have to set it to true to have the same behavior as sql server). Default value is True.

  • LikeWithEscape - controls if the database will use the LIKE operator with the ESCAPE character set to backslash. Default value is True.
  • OnlyMetadata - controls if the context instance is created only to obtain the metadata information via the OpenAccessContext.Metadata property. Operations that need to connect to the database cannot be performed on the context if this property is set to True. Default value is False.
  • DefaultStreamBufferSize - controls the default buffer size for Stream fields. The default value is 4096.
  • PrepareCommands - controls the creation of prepared commands used to perform CRUD operations. Default value is True.

  • CommandTimeout - The command timeout determines the wait time before terminating the unfinished Telerik Data Access operations. The CommandTimeout property allows you adjust that time so that long-running database operations are allowed to finish their execution. By default, the value is 30 seconds. Once the timeout is exceeded SQLException will be thrown.

    Note that the execution of the long-running operations can be terminated before CommandTimeout is reached, due to exceeding LockTimeoutMSec and ActiveConnectionTimeout.

  • AllowCascadeDelete - in cases when a model contains classes in vertical inheritance or Multi-Table Entities, this setting notifies Telerik Data Access whether to issue additional DELETE statements targeting the derived classes when objects from base classes are deleted. The default value is False.

    Changing the state of AllowCascadeDelete requires you to synchronize the domain model and the database with the UpdateSchema() method. This will recreate the constraints with the appropriate setting for cascade delete. Skipping this process may lead to performance issues and DataStoreException during runtime.

  • StatementBatchingEnabled - enables you to specify if multiple INSERT, UPDATE or DELETE statements with the same structure should be executed as a Single Instruction Multiple Data operation. Enabling Statement Batching will improve performance in cases where the database server is harder to reach, for example, due to a higher latency network. The default value of the property is True.

    • StatementBatchingThreshold - through this property you can set or check the maximum number of similar statements which should not be batched. The default value is 1.

    • StatementBatchingSize - through this property you can set or check the maximum number of statements which a single batch can contain. The default value is 100.

      Note that INSERT statements for tables with auto-increment columns will not be batched.

      Currently, Statement Batching is supported for Microsoft SQL Server, Microsoft Azure, Oracle and Postgres and will not be applied when using other back-ends.

  • ReadWithoutTransactions - the property allows you to specify if the read operations should be executed within transactions on the database server. By default, they will not be wrapped within such and the value of the property is True. If another operation (insert/update/delete) had already started a transaction, a read operation would be executed as part of it. The allowed options are:

    • True - In case this value is set, the read operations will not start transactions on their own.
    • False - In case this value is set, the read operations will start transactions even if they are the only operations that will be executed through the given instance of the context.

Configuring the Runtime Functionality via Code

To configure the runtime functionality in the code, you need to extend your context class with another partial class with the same name and implement the CustomizeBackendConfiguration partial method. For example:

public partial class EntitiesModel
{
    static partial void CustomizeBackendConfiguration(ref BackendConfiguration config)
    {
        config.Runtime.MediumTrust = true;
        config.Runtime.SupportConcurrentThreadsInScope = true;
        config.Runtime.CheckSchemaConsistencyOnStartup = true;
        config.Runtime.CheckObjectConsistencyOnCommit = true;
        config.Runtime.ReadOnly = false;
        config.Runtime.LockTimeoutMSec = 7000;
        config.Runtime.LockSqlSuffix = "_";
        config.Runtime.CloseScopesWithActiveTransaction = true;
        config.Runtime.CloseDatabaseWithActiveTransactions = true;
        config.Runtime.PerformanceCounter = false;
        config.Runtime.PerformanceCounterName = "CounterName";
        config.Runtime.StatementBatchingEnabled = true;
        config.Runtime.StatementBatchingThreshold = 1;
        config.Runtime.StatementBatchingSize = 100;
        config.Runtime.InterceptDefaultFetchGroupFieldAccess = false;
        config.Runtime.AllowReadAfterDelete = false;
        config.Runtime.AllowReadAfterDispose = false;
        config.Runtime.Hyperdrive = false;
        config.Runtime.ClassBehavior = DataAccessKind.ReadWrite;
        config.Runtime.CacheReferenceType = CacheReferenceType.Strong;
        config.Runtime.ReturnNullForRowNotFound = true;
        config.Runtime.RequirePersistentClasses = false;
        config.Runtime.Concurrency = TransactionMode.PESSIMISTIC_EXPLICIT;
        config.Runtime.CompiledQueryCacheSize = 2000;
        config.Runtime.UseUTCForAutoSetValues = true;
        config.Runtime.UseUTCForReadValues = true;
        config.Runtime.NullsFirst = false;
        config.Runtime.LikeWithEscape = true;
        config.Runtime.OnlyMetadata = false;
        config.Runtime.DefaultStreamBufferSize = 4096;
        config.Runtime.PrepareCommands = false;
        config.Runtime.AllowCascadeDelete = true;
        config.Runtime.CommandTimeout = 30;
        config.Runtime.ReadWithoutTransactions = false;
    }
}

Partial Public Class EntitiesModel
    Private Shared Sub CustomizeBackendConfiguration(ByRef config As BackendConfiguration)
        config.Runtime.MediumTrust = True
        config.Runtime.SupportConcurrentThreadsInScope = True
        config.Runtime.CheckSchemaConsistencyOnStartup = True
        config.Runtime.CheckObjectConsistencyOnCommit = True
        config.Runtime.ReadOnly = False
        config.Runtime.LockTimeoutMSec = 7000
        config.Runtime.LockSqlSuffix = "_"
        config.Runtime.CloseScopesWithActiveTransaction = True
        config.Runtime.CloseDatabaseWithActiveTransactions = True
        config.Runtime.PerformanceCounter = False
        config.Runtime.PerformanceCounterName = "CounterName"
        config.Runtime.StatementBatchingEnabled = True
        config.Runtime.StatementBatchingThreshold = 1
        config.Runtime.StatementBatchingSize = 100
        config.Runtime.InterceptDefaultFetchGroupFieldAccess = False
        config.Runtime.AllowReadAfterDelete = False
        config.Runtime.AllowReadAfterDispose = False
        config.Runtime.Hyperdrive = False
        config.Runtime.ClassBehavior = DataAccessKind.ReadWrite
        config.Runtime.CacheReferenceType = CacheReferenceType.Strong
        config.Runtime.ReturnNullForRowNotFound = True
        config.Runtime.RequirePersistentClasses = False
        config.Runtime.Concurrency = TransactionMode.PESSIMISTIC_EXPLICIT
        config.Runtime.CompiledQueryCacheSize = 2000
        config.Runtime.UseUTCForAutoSetValues = True
        config.Runtime.UseUTCForReadValues = True
        config.Runtime.NullsFirst = False
        config.Runtime.LikeWithEscape = True
        config.Runtime.OnlyMetadata = False
        config.Runtime.DefaultStreamBufferSize = 4096
        config.Runtime.PrepareCommands = False
        config.Runtime.AllowCascadeDelete = True
        config.Runtime.CommandTimeout = 30
        config.Runtime.ReadWithoutTransactions = False
    End Sub
End Class

Configuring the Runtime Functionality via Config File

Another way to configure the runtime functionality is to define the configuration in the App/web config file. For example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="openAccessConfiguration"
             type="Telerik.OpenAccess.Config.OpenAccessConfigSectionHandler, Telerik.OpenAccess"
             requirePermission="false" />
  </configSections>
  <openAccessConfiguration>
    <backendConfiguration name="RuntimeConfiguration">
      <runtime mediumTrust="true"
               supportConcurrentThreadsInScope="true"
               checkSchemaConsistencyOnStartup="true"
               checkObjectConsistencyOnCommit="true"
               readOnly="false"
               lockTimeoutMSec="7000"
               lockSqlSuffix="_"
               closeScopesWithActiveTransaction="true"
               closeDatabaseWithActiveTransactions="true"
               performanceCounter="false"
               performanceCounterName="CounterName"
               statementBatchingEnabled="true"
               statementBatchingThreshold="1"
               statementBatchingSize="100"
               interceptDefaultFetchGroupFieldAccess="false"
               allowReadAfterDelete="false"
               allowReadAfterDispose="false"
               hyperdrive="false"
               classBehavior="ReadWrite"
               cacheReferenceType="Strong"
               returnNullForRowNotFound="true"
               requirePersistentClasses="false"
               concurrency="PESSIMISTIC_EXPLICIT"
               compiledQueryCacheSize="2000"
               useUTCForAutoSetValues="true"
               useUTCForReadValues="true"
               nullsFirst="false"
               likeWithEscape="true"
               onlyMetadata="false"
               allowCascadeDelete ="true"
               commandTimeout=30
               readWithoutTransactions = "false" />
    </backendConfiguration>
  </openAccessConfiguration>
  <connectionStrings>
  </connectionStrings>
</configuration>

Again, you need to extend your context class with another partial class with the same name and add the following static constructor:

public partial class EntitiesModel
{
   static EntitiesModel()
   {
       BackendConfiguration.MergeBackendConfigurationFromConfigFile(
           backend,
           ConfigurationMergeMode.ConfigFileDefinitionWins,
           "RuntimeConfiguration" );
   }
}

Partial Public Class EntitiesModel
    Shared Sub New()
        BackendConfiguration.MergeBackendConfigurationFromConfigFile(backend, ConfigurationMergeMode.ConfigFileDefinitionWins, "RuntimeConfiguration")
    End Sub
End Class

This will merge the settings from the config file to the backend static variable of the context class that holds the rest of the backend configuration.