Class Extensions

Extension methods for entities

Inheritance
Object
Extensions
Inherited Members
Object.Equals(Object)
Object.Equals(Object, Object)
Object.GetHashCode()
Object.GetType()
Object.MemberwiseClone()
Object.ReferenceEquals(Object, Object)
Object.ToString()
Namespace: MongoDB.Entities
Assembly: MongoDB.Entities.dll
Syntax
public static class Extensions

Methods

Collection<T>(T)

Gets the IMongoCollection for a given IEntity type.

TIP: Try never to use this unless really neccessary.

Declaration
public static IMongoCollection<T> Collection<T>(this T _)
    where T : IEntity
Parameters
Type Name Description
T _
Returns
Type Description
IMongoCollection<T>
Type Parameters
Name Description
T

Any class that implements IEntity

CollectionName<T>(T)

Gets the collection name for this entity

Declaration
public static string CollectionName<T>(this T _)
    where T : IEntity
Parameters
Type Name Description
T _
Returns
Type Description
String
Type Parameters
Name Description
T

Database<T>(T)

Gets the IMongoDatabase for the given entity type

Declaration
public static IMongoDatabase Database<T>(this T _)
    where T : IEntity
Parameters
Type Name Description
T _
Returns
Type Description
IMongoDatabase
Type Parameters
Name Description
T

The type of entity

DatabaseName<T>(T)

Gets the name of the database this entity is attached to. Returns name of default database if not specifically attached.

Declaration
public static string DatabaseName<T>(this T _)
    where T : IEntity
Parameters
Type Name Description
T _
Returns
Type Description
String
Type Parameters
Name Description
T

DeleteAllAsync<T>(IEnumerable<T>, IClientSessionHandle, CancellationToken)

Deletes multiple entities from the database

HINT: If these entities are referenced by one-to-many/many-to-many relationships, those references are also deleted.

Declaration
public static Task<DeleteResult> DeleteAllAsync<T>(this IEnumerable<T> entities, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities
IClientSessionHandle session
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<DeleteResult>
Type Parameters
Name Description
T

DeleteAsync<T>(T, IClientSessionHandle, CancellationToken)

Deletes a single entity from MongoDB.

HINT: If this entity is referenced by one-to-many/many-to-many relationships, those references are also deleted.

Declaration
public static Task<DeleteResult> DeleteAsync<T>(this T entity, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity
IClientSessionHandle session
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<DeleteResult>
Type Parameters
Name Description
T

Distinct<T>(IAggregateFluent<T>)

Adds a distinct aggregation stage to a fluent pipeline.

Declaration
public static IAggregateFluent<T> Distinct<T>(this IAggregateFluent<T> aggregate)
    where T : IEntity
Parameters
Type Name Description
IAggregateFluent<T> aggregate
Returns
Type Description
IAggregateFluent<T>
Type Parameters
Name Description
T

Any class that implements IEntity

DropAsync(IMongoCollection<JoinRecord>)

Drops a join collection

Declaration
public static Task DropAsync(this IMongoCollection<JoinRecord> collection)
Parameters
Type Name Description
IMongoCollection<JoinRecord> collection
Returns
Type Description
Task

ExistsAsync(IMongoDatabase, Int32)

Checks to see if the database already exists on the mongodb server

Declaration
public static async Task<bool> ExistsAsync(this IMongoDatabase db, int timeoutSeconds = 5)
Parameters
Type Name Description
IMongoDatabase db
Int32 timeoutSeconds

The number of seconds to keep trying
Returns
Type Description
Task<Boolean>

Fluent<T>(T, IClientSessionHandle, AggregateOptions)

An IAggregateFluent collection of sibling Entities.

Declaration
public static IAggregateFluent<T> Fluent<T>(this T _, IClientSessionHandle session = null, AggregateOptions options = null)
    where T : IEntity
Parameters
Type Name Description
T _
IClientSessionHandle session

An optional session if using within a transaction
AggregateOptions options

The options for the aggregation. This is not required.
Returns
Type Description
IAggregateFluent<T>
Type Parameters
Name Description
T

FullPath<T>(Expression<Func<T, Object>>)

Returns the full dotted path of a property for the given expression

Declaration
public static string FullPath<T>(this Expression<Func<T, object>> expression)
Parameters
Type Name Description
Expression<Func<T, Object>> expression
Returns
Type Description
String
Type Parameters
Name Description
T

Any class that implements IEntity

InitManyToMany<TChild>(IEntity, Expression<Func<Many<TChild>>>, Expression<Func<TChild, Object>>)

Initializes supplied property with a new Many-To-Many relationship.

Declaration
public static void InitManyToMany<TChild>(this IEntity parent, Expression<Func<Many<TChild>>> propertyToInit, Expression<Func<TChild, object>> propertyOtherSide)
    where TChild : IEntity
Parameters
Type Name Description
IEntity parent
Expression<Func<Many<TChild>>> propertyToInit

() = > PropertyName
Expression<Func<TChild, Object>> propertyOtherSide

x => x.PropertyName
Type Parameters
Name Description
TChild

InitOneToMany<TChild>(IEntity, Expression<Func<Many<TChild>>>)

Initializes supplied property with a new One-To-Many relationship.

Declaration
public static void InitOneToMany<TChild>(this IEntity parent, Expression<Func<Many<TChild>>> propertyToInit)
    where TChild : IEntity
Parameters
Type Name Description
IEntity parent
Expression<Func<Many<TChild>>> propertyToInit

() => PropertyName
Type Parameters
Name Description
TChild

InsertAsync<T>(T, IClientSessionHandle, CancellationToken)

Inserts a new entity into the colleciton.

Declaration
public static Task InsertAsync<T>(this T entity, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task
Type Parameters
Name Description
T

InsertAsync<T>(IEnumerable<T>, IClientSessionHandle, CancellationToken)

Inserts a batch of new entities into the collection.

Declaration
public static Task<BulkWriteResult<T>> InsertAsync<T>(this IEnumerable<T> entities, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

IsAccessibleAsync(IMongoDatabase, Int32)

Pings the mongodb server to check if it's still connectable

Declaration
public static async Task<bool> IsAccessibleAsync(this IMongoDatabase db, int timeoutSeconds = 5)
Parameters
Type Name Description
IMongoDatabase db
Int32 timeoutSeconds

The number of seconds to keep trying
Returns
Type Description
Task<Boolean>

Match<T>(IAggregateFluent<T>, Func<FilterDefinitionBuilder<T>, FilterDefinition<T>>)

Appends a match stage to the pipeline with a filter expression

Declaration
public static IAggregateFluent<T> Match<T>(this IAggregateFluent<T> aggregate, Func<FilterDefinitionBuilder<T>, FilterDefinition<T>> filter)
    where T : IEntity
Parameters
Type Name Description
IAggregateFluent<T> aggregate
Func<FilterDefinitionBuilder<T>, FilterDefinition<T>> filter

f => f.Eq(x => x.Prop, Value) & f.Gt(x => x.Prop, Value)
Returns
Type Description
IAggregateFluent<T>
Type Parameters
Name Description
T

Any class that implements IEntity

MatchExpression<T>(IAggregateFluent<T>, String)

Appends a match stage to the pipeline with an aggregation expression (i.e. $expr)

Declaration
public static IAggregateFluent<T> MatchExpression<T>(this IAggregateFluent<T> aggregate, string expression)
    where T : IEntity
Parameters
Type Name Description
IAggregateFluent<T> aggregate
String expression

{ $gt: ['$Property1', '$Property2'] }
Returns
Type Description
IAggregateFluent<T>
Type Parameters
Name Description
T

Any class that implements IEntity

NextSequentialNumberAsync<T>(T, CancellationToken)

Returns an atomically generated sequential number for the given Entity type everytime the method is called

Declaration
public static Task<ulong> NextSequentialNumberAsync<T>(this T _, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T _
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UInt64>
Type Parameters
Name Description
T

PagedSearch<T>(IAggregateFluent<T>)

Starts a paged search pipeline for this fluent pipeline

Declaration
public static PagedSearch<T, T> PagedSearch<T>(this IAggregateFluent<T> aggregate)
    where T : IEntity
Parameters
Type Name Description
IAggregateFluent<T> aggregate
Returns
Type Description
PagedSearch<T, T>
Type Parameters
Name Description
T

Any class that implements IEntity

PagedSearch<T, TProjection>(IAggregateFluent<T>)

Starts a paged search pipeline for this fluent pipeline

Declaration
public static PagedSearch<T, TProjection> PagedSearch<T, TProjection>(this IAggregateFluent<T> aggregate)
    where T : IEntity
Parameters
Type Name Description
IAggregateFluent<T> aggregate
Returns
Type Description
PagedSearch<T, TProjection>
Type Parameters
Name Description
T

Any class that implements IEntity
TProjection

The type of the resulting projection

Queryable<T>(T, AggregateOptions)

An IQueryable collection of sibling Entities.

Declaration
public static IMongoQueryable<T> Queryable<T>(this T _, AggregateOptions options = null)
    where T : IEntity
Parameters
Type Name Description
T _
AggregateOptions options
Returns
Type Description
IMongoQueryable<T>
Type Parameters
Name Description
T

SaveAsync<T>(T, IClientSessionHandle, CancellationToken)

Saves a complete entity replacing an existing entity or creating a new one if it does not exist. If ID value is null, a new entity is created. If ID has a value, then existing entity is replaced.

Declaration
public static Task SaveAsync<T>(this T entity, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task
Type Parameters
Name Description
T

SaveAsync<T>(IEnumerable<T>, IClientSessionHandle, CancellationToken)

Saves a batch of complete entities replacing existing ones or creating new ones if they do not exist. If ID value is null, a new entity is created. If ID has a value, then existing entity is replaced.

Declaration
public static Task<BulkWriteResult<T>> SaveAsync<T>(this IEnumerable<T> entities, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

SaveExceptAsync<T>(T, IEnumerable<String>, IClientSessionHandle, CancellationToken)

Saves an entity partially excluding the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with an IEnumerable. Property names must match exactly.

Declaration
public static Task<UpdateResult> SaveExceptAsync<T>(this T entity, IEnumerable<string> propNames, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity

The entity to save
IEnumerable<String> propNames

new List { "PropOne", "PropTwo" }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UpdateResult>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveExceptAsync<T>(T, Expression<Func<T, Object>>, IClientSessionHandle, CancellationToken)

Saves an entity partially excluding the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be excluded can be specified with a 'New' expression. You can only specify root level properties with the expression.

Declaration
public static Task<UpdateResult> SaveExceptAsync<T>(this T entity, Expression<Func<T, object>> members, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity

The entity to save
Expression<Func<T, Object>> members

x => new { x.PropOne, x.PropTwo }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UpdateResult>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveExceptAsync<T>(IEnumerable<T>, IEnumerable<String>, IClientSessionHandle, CancellationToken)

Saves a batch of entities partially excluding the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with an IEnumerable. Property names must match exactly.

Declaration
public static Task<BulkWriteResult<T>> SaveExceptAsync<T>(this IEnumerable<T> entities, IEnumerable<string> propNames, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities

The batch of entities to save
IEnumerable<String> propNames

new List { "PropOne", "PropTwo" }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveExceptAsync<T>(IEnumerable<T>, Expression<Func<T, Object>>, IClientSessionHandle, CancellationToken)

Saves a batch of entities partially excluding the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be excluded can be specified with a 'New' expression. You can only specify root level properties with the expression.

Declaration
public static Task<BulkWriteResult<T>> SaveExceptAsync<T>(this IEnumerable<T> entities, Expression<Func<T, object>> members, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities

The batch of entities to save
Expression<Func<T, Object>> members

x => new { x.PropOne, x.PropTwo }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveOnlyAsync<T>(T, IEnumerable<String>, IClientSessionHandle, CancellationToken)

Saves an entity partially with only the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with an IEnumerable. Property names must match exactly.

Declaration
public static Task<UpdateResult> SaveOnlyAsync<T>(this T entity, IEnumerable<string> propNames, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity

The entity to save
IEnumerable<String> propNames

new List { "PropOne", "PropTwo" }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UpdateResult>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveOnlyAsync<T>(T, Expression<Func<T, Object>>, IClientSessionHandle, CancellationToken)

Saves an entity partially with only the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with a 'New' expression. You can only specify root level properties with the expression.

Declaration
public static Task<UpdateResult> SaveOnlyAsync<T>(this T entity, Expression<Func<T, object>> members, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity

The entity to save
Expression<Func<T, Object>> members

x => new { x.PropOne, x.PropTwo }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UpdateResult>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveOnlyAsync<T>(IEnumerable<T>, IEnumerable<String>, IClientSessionHandle, CancellationToken)

Saves a batch of entities partially with only the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with an IEnumerable. Property names must match exactly.

Declaration
public static Task<BulkWriteResult<T>> SaveOnlyAsync<T>(this IEnumerable<T> entities, IEnumerable<string> propNames, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities

The batch of entities to save
IEnumerable<String> propNames

new List { "PropOne", "PropTwo" }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

Any class that implements IEntity

SaveOnlyAsync<T>(IEnumerable<T>, Expression<Func<T, Object>>, IClientSessionHandle, CancellationToken)

Saves a batch of entities partially with only the specified subset of properties. If ID value is null, a new entity is created. If ID has a value, then existing entity is updated.

TIP: The properties to be saved can be specified with a 'New' expression. You can only specify root level properties with the expression.

Declaration
public static Task<BulkWriteResult<T>> SaveOnlyAsync<T>(this IEnumerable<T> entities, Expression<Func<T, object>> members, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities

The batch of entities to save
Expression<Func<T, Object>> members

x => new { x.PropOne, x.PropTwo }
IClientSessionHandle session

An optional session if using within a transaction
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<BulkWriteResult<T>>
Type Parameters
Name Description
T

Any class that implements IEntity

SavePreservingAsync<T>(T, IClientSessionHandle, CancellationToken)

Saves an entity partially while excluding some properties. The properties to be excluded can be specified using the [Preserve] attribute.

Declaration
public static Task<UpdateResult> SavePreservingAsync<T>(this T entity, IClientSessionHandle session = null, CancellationToken cancellation = default(CancellationToken))
    where T : IEntity
Parameters
Type Name Description
T entity

The entity to save
IClientSessionHandle session
CancellationToken cancellation

An optional cancellation token
Returns
Type Description
Task<UpdateResult>
Type Parameters
Name Description
T

Any class that implements IEntity

SortByRelevance<T>(IEnumerable<T>, String, Func<T, String>, Nullable<Int32>)

Sort a list of objects by relevance to a given string using Levenshtein Distance

Declaration
public static IEnumerable<T> SortByRelevance<T>(this IEnumerable<T> objects, string searchTerm, Func<T, string> propertyToSortBy, int? maxDistance = null)
Parameters
Type Name Description
IEnumerable<T> objects

The list of objects to sort
String searchTerm

The term to measure relevance to
Func<T, String> propertyToSortBy

x => x.PropertyName [the term will be matched against the value of this property]
Nullable<Int32> maxDistance

The maximum levenstein distance to qualify an item for inclusion in the returned list
Returns
Type Description
IEnumerable<T>
Type Parameters
Name Description
T

Any object type

ToBatches<T>(IEnumerable<T>, Int32)

Extension method for processing collections in batches with streaming (yield return)

Declaration
public static IEnumerable<IEnumerable<T>> ToBatches<T>(this IEnumerable<T> collection, int batchSize = 100)
Parameters
Type Name Description
IEnumerable<T> collection

The source collection
Int32 batchSize

The size of each batch
Returns
Type Description
IEnumerable<IEnumerable<T>>
Type Parameters
Name Description
T

The type of the objects inside the source collection

ToDate(DateTime)

converts a System.DateTime instance to a Date instance.

Declaration
public static Date ToDate(this DateTime dateTime)
Parameters
Type Name Description
DateTime dateTime

the System.DateTime instance to convert
Returns
Type Description
Date

ToDate(Int64)

converts ticks to a Date instance.

Declaration
public static Date ToDate(this long ticks)
Parameters
Type Name Description
Int64 ticks

the ticks to convert
Returns
Type Description
Date

ToDocument<T>(T)

Creates an unlinked duplicate of the original IEntity ready for embedding with a blank ID.

Declaration
public static T ToDocument<T>(this T entity)
    where T : IEntity
Parameters
Type Name Description
T entity
Returns
Type Description
T
Type Parameters
Name Description
T

ToDocuments<T>(T[])

Creates unlinked duplicates of the original Entities ready for embedding with blank IDs.

Declaration
public static T[] ToDocuments<T>(this T[] entities)
    where T : IEntity
Parameters
Type Name Description
T[] entities
Returns
Type Description
T[]
Type Parameters
Name Description
T

ToDocuments<T>(IEnumerable<T>)

Creates unlinked duplicates of the original Entities ready for embedding with blank IDs.

Declaration
public static IEnumerable<T> ToDocuments<T>(this IEnumerable<T> entities)
    where T : IEntity
Parameters
Type Name Description
IEnumerable<T> entities
Returns
Type Description
IEnumerable<T>
Type Parameters
Name Description
T

ToDoubleMetaphoneHash(String)

Converts a search term to Double Metaphone hash code suitable for fuzzy text searching.

Declaration
public static string ToDoubleMetaphoneHash(this string term)
Parameters
Type Name Description
String term

A single or multiple word search term
Returns
Type Description
String

ToFuzzy(String)

converts a string value to a FuzzyString

Declaration
public static FuzzyString ToFuzzy(this string value)
Parameters
Type Name Description
String value

the string to convert
Returns
Type Description
FuzzyString

ToReference<T>(T)

Returns a reference to this entity.

Declaration
public static One<T> ToReference<T>(this T entity)
    where T : IEntity
Parameters
Type Name Description
T entity
Returns
Type Description
One<T>
Type Parameters
Name Description
T