Class LinqOptions

Namespace

LinqToDB

Assembly

linq2db.dll

public sealed record LinqOptions : IOptionSet, IConfigurationID, IEquatable<LinqOptions>

Inheritance

object

LinqOptions

Implements

IOptionSet

IConfigurationID

IEquatable<LinqOptions>

Extension Methods

Utils.IsNullValue(object?)

DataOptionsExtensions.WithCacheSlidingExpiration(LinqOptions, TimeSpan?)

DataOptionsExtensions.WithCompareNulls(LinqOptions, CompareNulls)

DataOptionsExtensions.WithConcatenateOrderBy(LinqOptions, bool)

DataOptionsExtensions.WithDisableQueryCache(LinqOptions, bool)

DataOptionsExtensions.WithEnableContextSchemaEdit(LinqOptions, bool)

DataOptionsExtensions.WithGenerateExpressionTest(LinqOptions, bool)

DataOptionsExtensions.WithGuardGrouping(LinqOptions, bool)

DataOptionsExtensions.WithIgnoreEmptyUpdate(LinqOptions, bool)

DataOptionsExtensions.WithOptimizeJoins(LinqOptions, bool)

DataOptionsExtensions.WithParameterizeTakeSkip(LinqOptions, bool)

DataOptionsExtensions.WithPreferExistsForScalar(LinqOptions, bool)

DataOptionsExtensions.WithTraceMapperExpression(LinqOptions, bool)

Sql.IsDistinctFrom<T>(T, T)

Sql.IsNotDistinctFrom<T>(T, T)

SqlExtensions.In<T>(T, T, T)

SqlExtensions.In<T>(T, T, T, T)

SqlExtensions.In<T>(T, params T[])

SqlExtensions.In<T>(T, IEnumerable<T>)

SqlExtensions.In<T>(T, IQueryable<T>)

SqlExtensions.NotIn<T>(T, T, T)

SqlExtensions.NotIn<T>(T, T, T, T)

SqlExtensions.NotIn<T>(T, params T[])

SqlExtensions.NotIn<T>(T, IEnumerable<T>)

SqlExtensions.NotIn<T>(T, IQueryable<T>)

Constructors

LinqOptions()

public LinqOptions()

LinqOptions(bool, bool, bool, bool, bool, bool, CompareNulls, bool, bool, TimeSpan?, bool, bool, bool, bool, bool)

public LinqOptions(bool PreloadGroups = false, bool IgnoreEmptyUpdate = false, bool GenerateExpressionTest = false, bool TraceMapperExpression = false, bool ConcatenateOrderBy = false, bool OptimizeJoins = true, CompareNulls CompareNulls = CompareNulls.LikeClr, bool GuardGrouping = true, bool DisableQueryCache = false, TimeSpan? CacheSlidingExpiration = null, bool PreferApply = true, bool KeepDistinctOrdered = true, bool ParameterizeTakeSkip = true, bool EnableContextSchemaEdit = false, bool PreferExistsForScalar = false)

Parameters

PreloadGroups bool

Controls how group data for LINQ queries ended with GroupBy will be loaded:

• if true - group data will be loaded together with main query, resulting in 1 + N queries, where N - number of groups;
• if false - group data will be loaded when you call enumerator for specific group IGrouping<TKey, TElement>. Default value: false.

IgnoreEmptyUpdate bool

Controls behavior of linq2db when there is no updateable fields in Update query:

• if true - query not executed and Update operation returns 0 as number of affected records;
• if false - LinqToDBException will be thrown. Default value: false.

GenerateExpressionTest bool

Enables generation of test class for each LINQ query, executed while this option is enabled. This option could be useful for issue reporting, when you need to provide reproducible case. Test file will be placed to linq2db subfolder of temp folder and exact file path will be logged to data connection tracing infrastructure. See TraceSwitch for more details. Default value: false.

TraceMapperExpression bool

Enables logging of generated mapping expression to data connection tracing infrastructure. See TraceSwitch for more details. Default value: false.

ConcatenateOrderBy bool

Controls behavior, when LINQ query chain contains multiple OrderBy<TSource, TKey>(IQueryable<TSource>, Expression<Func<TSource, TKey>>) or OrderByDescending<TSource, TKey>(IQueryable<TSource>, Expression<Func<TSource, TKey>>) calls:

• if true - non-first OrderBy* call will be treated as ThenBy* call;
• if false - OrderBy* call will discard sort specifications, added by previous OrderBy* and ThenBy* calls. Default value: false.

OptimizeJoins bool

If enabled, linq2db will try to reduce number of generated SQL JOINs for LINQ query. Attempted optimizations:

• removes duplicate joins by unique target table key;
• removes self-joins by unique key;
• removes left joins if joined table is not used in query. Default value: true.

CompareNulls CompareNulls

If set to LikeClr nullable fields would be checked for IS NULL in Equal/NotEqual comparisons. If set to LikeSql comparisons are compiled straight to equivalent SQL operators, which consider nulls values as not equal. LikeSqlExceptParameters is a backward compatible option that works mostly as LikeSql, but sniffs parameters value and changes = into IS NULL when parameters are null. Comparisons to literal null are always compiled into IS NULL. This affects: Equal, NotEqual, Not Contains Default value: LikeClr.

public class MyEntity
{
    public int? Value;
}

db.MyEntity.Where(e => e.Value != 10)

from e1 in db.MyEntity
join e2 in db.MyEntity on e1.Value equals e2.Value
select e1

var filter = new [] {1, 2, 3};
db.MyEntity.Where(e => ! filter.Contains(e.Value))

Would be converted to next queries under LikeClr:

SELECT Value FROM MyEntity WHERE Value IS NULL OR Value != 10

SELECT e1.Value
FROM MyEntity e1
INNER JOIN MyEntity e2 ON e1.Value = e2.Value OR (e1.Value IS NULL AND e2.Value IS NULL)

SELECT Value FROM MyEntity WHERE Value IS NULL OR NOT Value IN (1, 2, 3)

GuardGrouping bool

Controls behavior of LINQ query, which ends with GroupBy call. - if true - LinqToDBException will be thrown for such queries; - if false - eager loading used. Default value: true.

More details.

DisableQueryCache bool

Used to disable LINQ expressions caching for queries. This cache reduces time, required for query parsing but have several side-effects:

- cached LINQ expressions could contain references to external objects as parameters, which could lead to memory leaks if those objects are not used anymore by other code

- cache access synchronization could lead to bigger latencies than it saves.

Default value: false.

It is not recommended to enable this option as it could lead to severe slowdown. Better approach will be to use NoLinqCache scope around queries, that produce severe memory leaks you need to fix.

More details.

CacheSlidingExpiration TimeSpan?

Specifies timeout when query will be evicted from cache since last execution of query. Default value is 1 hour.

PreferApply bool

Used to generate CROSS APPLY or OUTER APPLY if possible. Default value: true.

KeepDistinctOrdered bool

Allows SQL generation to automatically transform

SELECT DISTINCT value FROM Table ORDER BY date

Into GROUP BY equivalent if syntax is not supported Default value: true.

ParameterizeTakeSkip bool

Enables Take/Skip parameterization. Default value: true.

EnableContextSchemaEdit bool

If true, user could add new mappings to context mapping schems (MappingSchema). Otherwise, LinqToDBException will be generated on locked mapping schema edit attempt. It is not recommended to enable this option as it has performance implications. Proper approach is to create single MappingSchema instance once, configure mappings for it and use this MappingSchema instance for all context instances. Default value: false.

PreferExistsForScalar bool

If true, EXISTS operator will be generated instead of IN operator for scalar values.

SELECT Value FROM MyEntity e WHERE EXISTS(SELECT * FROM MyEntity2 e2 WHERE e2.Value = e.Value)

vs

SELECT Value FROM MyEntity e WHERE Value IN (SELECT Value FROM MyEntity2 e2)

Default value: false.

Properties

CacheSlidingExpiration

Specifies timeout when query will be evicted from cache since last execution of query. Default value is 1 hour.

public TimeSpan? CacheSlidingExpiration { get; init; }

Property Value

TimeSpan?

CacheSlidingExpirationOrDefault

public TimeSpan CacheSlidingExpirationOrDefault { get; }

Property Value

TimeSpan

CompareNulls

If set to LikeClr nullable fields would be checked for IS NULL in Equal/NotEqual comparisons. If set to LikeSql comparisons are compiled straight to equivalent SQL operators, which consider nulls values as not equal. LikeSqlExceptParameters is a backward compatible option that works mostly as LikeSql, but sniffs parameters value and changes = into IS NULL when parameters are null. Comparisons to literal null are always compiled into IS NULL. This affects: Equal, NotEqual, Not Contains Default value: LikeClr.

public class MyEntity
{
    public int? Value;
}

db.MyEntity.Where(e => e.Value != 10)

from e1 in db.MyEntity
join e2 in db.MyEntity on e1.Value equals e2.Value
select e1

var filter = new [] {1, 2, 3};
db.MyEntity.Where(e => ! filter.Contains(e.Value))

Would be converted to next queries under LikeClr:

SELECT Value FROM MyEntity WHERE Value IS NULL OR Value != 10

SELECT e1.Value
FROM MyEntity e1
INNER JOIN MyEntity e2 ON e1.Value = e2.Value OR (e1.Value IS NULL AND e2.Value IS NULL)

SELECT Value FROM MyEntity WHERE Value IS NULL OR NOT Value IN (1, 2, 3)

public CompareNulls CompareNulls { get; init; }

Property Value

CompareNulls

ConcatenateOrderBy

Controls behavior, when LINQ query chain contains multiple OrderBy<TSource, TKey>(IQueryable<TSource>, Expression<Func<TSource, TKey>>) or OrderByDescending<TSource, TKey>(IQueryable<TSource>, Expression<Func<TSource, TKey>>) calls:

• if true - non-first OrderBy* call will be treated as ThenBy* call;
• if false - OrderBy* call will discard sort specifications, added by previous OrderBy* and ThenBy* calls. Default value: false.

public bool ConcatenateOrderBy { get; init; }

Property Value

bool

Default

Gets default LinqOptions instance.

public static LinqOptions Default { get; set; }

Property Value

LinqOptions

DisableQueryCache

Used to disable LINQ expressions caching for queries. This cache reduces time, required for query parsing but have several side-effects:

- cached LINQ expressions could contain references to external objects as parameters, which could lead to memory leaks if those objects are not used anymore by other code

- cache access synchronization could lead to bigger latencies than it saves.

Default value: false.

It is not recommended to enable this option as it could lead to severe slowdown. Better approach will be to use NoLinqCache scope around queries, that produce severe memory leaks you need to fix.

More details.

public bool DisableQueryCache { get; init; }

Property Value

bool

EnableContextSchemaEdit

If true, user could add new mappings to context mapping schems (MappingSchema). Otherwise, LinqToDBException will be generated on locked mapping schema edit attempt. It is not recommended to enable this option as it has performance implications. Proper approach is to create single MappingSchema instance once, configure mappings for it and use this MappingSchema instance for all context instances. Default value: false.

public bool EnableContextSchemaEdit { get; init; }

Property Value

bool

GenerateExpressionTest

Enables generation of test class for each LINQ query, executed while this option is enabled. This option could be useful for issue reporting, when you need to provide reproducible case. Test file will be placed to linq2db subfolder of temp folder and exact file path will be logged to data connection tracing infrastructure. See TraceSwitch for more details. Default value: false.

public bool GenerateExpressionTest { get; init; }

Property Value

bool

GuardGrouping

Controls behavior of LINQ query, which ends with GroupBy call. - if true - LinqToDBException will be thrown for such queries; - if false - eager loading used. Default value: true.

More details.

public bool GuardGrouping { get; init; }

Property Value

bool

IgnoreEmptyUpdate

Controls behavior of linq2db when there is no updateable fields in Update query:

• if true - query not executed and Update operation returns 0 as number of affected records;
• if false - LinqToDBException will be thrown. Default value: false.

public bool IgnoreEmptyUpdate { get; init; }

Property Value

bool

OptimizeJoins

If enabled, linq2db will try to reduce number of generated SQL JOINs for LINQ query. Attempted optimizations:

• removes duplicate joins by unique target table key;
• removes self-joins by unique key;
• removes left joins if joined table is not used in query. Default value: true.

public bool OptimizeJoins { get; init; }

Property Value

bool

ParameterizeTakeSkip

Enables Take/Skip parameterization. Default value: true.

public bool ParameterizeTakeSkip { get; init; }

Property Value

bool

PreferExistsForScalar

If true, EXISTS operator will be generated instead of IN operator for scalar values.

SELECT Value FROM MyEntity e WHERE EXISTS(SELECT * FROM MyEntity2 e2 WHERE e2.Value = e.Value)

vs

SELECT Value FROM MyEntity e WHERE Value IN (SELECT Value FROM MyEntity2 e2)

Default value: false.

public bool PreferExistsForScalar { get; init; }

Property Value

bool

TraceMapperExpression

Enables logging of generated mapping expression to data connection tracing infrastructure. See TraceSwitch for more details. Default value: false.

public bool TraceMapperExpression { get; init; }

Property Value

bool

Methods

Equals(LinqOptions?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(LinqOptions? other)

Parameters

other LinqOptions

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.