Class LocalView<TEntity>

Namespace

Microsoft.EntityFrameworkCore.ChangeTracking

Assembly

Microsoft.EntityFrameworkCore.dll

A collection that stays in sync with entities of a given type being tracked by a DbContext. Call Local to obtain a local view.

public class LocalView<TEntity> : ICollection<TEntity>, IEnumerable<TEntity>, IEnumerable, INotifyCollectionChanged, INotifyPropertyChanged, INotifyPropertyChanging, IListSource where TEntity : class

Type Parameters

TEntity

The type of the entity in the local view.

Inheritance

object

LocalView<TEntity>

Implements

ICollection<TEntity>

IEnumerable<TEntity>

IEnumerable

INotifyCollectionChanged

INotifyPropertyChanged

INotifyPropertyChanging

IListSource

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This local view will stay in sync as entities are added or removed from the context. Likewise, entities added to or removed from the local view will automatically be added to or removed from the context.

Adding an entity to this collection will cause it to be tracked in the Added state by the context unless it is already being tracked.

Removing an entity from this collection will cause it to be marked as Deleted, unless it was previously in the Added state, in which case it will be detached from the context.

The collection implements INotifyCollectionChanged, INotifyPropertyChanging, and INotifyPropertyChanging such that notifications are generated when an entity starts being tracked by the context or is marked as Deleted or Detached.

Do not use this type directly for data binding. Instead call ToObservableCollection() for WPF binding, or ToBindingList() for WinForms.

See Local views of tracked entities in EF Core for more information and examples.

Constructors

LocalView(DbSet<TEntity>)

This is an internal API that supports the Entity Framework Core infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release. You should only use it directly in your code with extreme caution and knowing that doing so can result in application failures when updating to a new Entity Framework Core release.

[EntityFrameworkInternal]
public LocalView(DbSet<TEntity> set)

Parameters

set DbSet<TEntity>

Properties

Count

The number of entities of type TEntity that are being tracked and are not marked as Deleted.

public virtual int Count { get; }

Property Value

int

Remarks

See Local views of tracked entities in EF Core for more information and examples.

IsReadOnly

False, since the collection is not read-only.

public virtual bool IsReadOnly { get; }

Property Value

bool

Methods

Add(TEntity)

Adds a new entity to the DbContext. If the entity is not being tracked or is currently marked as deleted, then it becomes tracked as Added.

public virtual void Add(TEntity item)

Parameters

item TEntity

The item to start tracking.

Remarks

Note that only the given entity is tracked. Any related entities discoverable from the given entity are not automatically tracked.

See Local views of tracked entities in EF Core for more information and examples.

Clear()

Marks all entities of type TEntity being tracked by the DbContext as Deleted.

public virtual void Clear()

Remarks

Entities that are currently marked as Added will be marked as Detached since the Added state indicates that the entity has not been saved to the database and hence it does not make sense to attempt to delete it from the database.

See Local views of tracked entities in EF Core for more information and examples.

Contains(TEntity)

Returns true if the entity is being tracked by the context and has not been marked as Deleted.

public virtual bool Contains(TEntity item)

Parameters

item TEntity

The entity to check.

Returns

bool

true if the entity is being tracked by the context and has not been marked as Deleted.

Remarks

See Local views of tracked entities in EF Core for more information and examples.

CopyTo(TEntity[], int)

Copies to an array all entities of type TEntity that are being tracked and are not marked as Deleted.

public virtual void CopyTo(TEntity[] array, int arrayIndex)

Parameters

array TEntity[]

The array into which to copy entities.

arrayIndex int

The index into the array to start copying.

Remarks

See Local views of tracked entities in EF Core for more information and examples.

FindEntry(IEnumerable<IProperty>, IEnumerable<object?>)

Returns an EntityEntry<TEntity> for the first entity being tracked by the context where the value of the given property matches the given values. The entry provide access to change tracking information and operations for the entity.

public virtual EntityEntry<TEntity>? FindEntry(IEnumerable<IProperty> properties, IEnumerable<object?> propertyValues)

Parameters

properties IEnumerable<IProperty>

The properties to match.

propertyValues IEnumerable<object>

The values of the properties to match.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Remarks

This method is frequently used to get the entity with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property value.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

FindEntry(IEnumerable<string>, IEnumerable<object?>)

Returns an EntityEntry<TEntity> for the first entity being tracked by the context where the value of the given property matches the given values. The entry provide access to change tracking information and operations for the entity.

public virtual EntityEntry<TEntity>? FindEntry(IEnumerable<string> propertyNames, IEnumerable<object?> propertyValues)

Parameters

propertyNames IEnumerable<string>

The name of the properties to match.

propertyValues IEnumerable<object>

The values of the properties to match.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Remarks

This method is frequently used to get the entity with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property value.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

FindEntryUntyped(IEnumerable<object?>)

Finds an EntityEntry<TEntity> for the entity with the given primary key values in the change tracker, if it is being tracked. null is returned if no entity with the given key values is being tracked. This method never queries the database.

public virtual EntityEntry<TEntity>? FindEntryUntyped(IEnumerable<object?> keyValues)

Parameters

keyValues IEnumerable<object>

The values of the primary key for the entity to be found.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Remarks

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

FindEntry<TProperty>(IProperty, TProperty?)

Returns an EntityEntry<TEntity> for the first entity being tracked by the context where the value of the given property matches the given value. The entry provide access to change tracking information and operations for the entity.

public virtual EntityEntry<TEntity>? FindEntry<TProperty>(IProperty property, TProperty? propertyValue)

Parameters

property IProperty

The property to match.

propertyValue TProperty

The value of the property to match.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Type Parameters

TProperty

The type of the property value.

Remarks

This method is frequently used to get the entity with a given non-null foreign key, primary key, or alternate key value. Lookups using a key property like this are more efficient than lookups on other property value.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

FindEntry<TProperty>(string, TProperty?)

Returns an EntityEntry<TEntity> for the first entity being tracked by the context where the value of the given property matches the given value. The entry provide access to change tracking information and operations for the entity.

public virtual EntityEntry<TEntity>? FindEntry<TProperty>(string propertyName, TProperty? propertyValue)

Parameters

propertyName string

The name of the property to match.

propertyValue TProperty

The value of the property to match.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Type Parameters

TProperty

The type of the property value.

Remarks

This method is frequently used to get the entity with a given non-null foreign key, primary key, or alternate key value. Lookups using a key property like this are more efficient than lookups on other property value.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

FindEntry<TKey>(TKey)

Finds an EntityEntry<TEntity> for the entity with the given primary key value in the change tracker, if it is being tracked. null is returned if no entity with the given key value is being tracked. This method never queries the database.

public virtual EntityEntry<TEntity>? FindEntry<TKey>(TKey keyValue)

Parameters

keyValue TKey

The value of the primary key for the entity to be found.

Returns

EntityEntry<TEntity>

An entry for the entity found, or null.

Type Parameters

TKey

The type of the primary key property.

Remarks

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

See EF Core change tracking for more information and examples.

GetEntries(IEnumerable<IProperty>, IEnumerable<object?>)

Returns an EntityEntry for each entity being tracked by the context where the values of the given properties matches the given values. The entries provide access to change tracking information and operations for each entity.

public virtual IEnumerable<EntityEntry<TEntity>> GetEntries(IEnumerable<IProperty> properties, IEnumerable<object?> propertyValues)

Parameters

properties IEnumerable<IProperty>

The the properties to match.

propertyValues IEnumerable<object>

The values of the properties to match.

Returns

IEnumerable<EntityEntry<TEntity>>

An entry for each entity being tracked.

Remarks

This method is frequently used to get the entities with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property values.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

Note that modification of entity state while iterating over the returned enumeration may result in an InvalidOperationException indicating that the collection was modified while enumerating. To avoid this, create a defensive copy using ToList<TSource>(IEnumerable<TSource>) or similar before iterating.

See EF Core change tracking for more information and examples.

GetEntries(IEnumerable<string>, IEnumerable<object?>)

Returns an EntityEntry for each entity being tracked by the context where the values of the given properties matches the given values. The entries provide access to change tracking information and operations for each entity.

public virtual IEnumerable<EntityEntry<TEntity>> GetEntries(IEnumerable<string> propertyNames, IEnumerable<object?> propertyValues)

Parameters

propertyNames IEnumerable<string>

The name of the properties to match.

propertyValues IEnumerable<object>

The values of the properties to match.

Returns

IEnumerable<EntityEntry<TEntity>>

An entry for each entity being tracked.

Remarks

This method is frequently used to get the entities with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property values.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

Note that modification of entity state while iterating over the returned enumeration may result in an InvalidOperationException indicating that the collection was modified while enumerating. To avoid this, create a defensive copy using ToList<TSource>(IEnumerable<TSource>) or similar before iterating.

See EF Core change tracking for more information and examples.

GetEntries<TProperty>(IProperty, TProperty?)

Returns an EntityEntry<TEntity> for each entity being tracked by the context where the value of the given property matches the given value. The entries provide access to change tracking information and operations for each entity.

public virtual IEnumerable<EntityEntry<TEntity>> GetEntries<TProperty>(IProperty property, TProperty? propertyValue)

Parameters

property IProperty

The property to match.

propertyValue TProperty

The value of the property to match.

Returns

IEnumerable<EntityEntry<TEntity>>

An entry for each entity being tracked.

Type Parameters

TProperty

The type of the property value.

Remarks

This method is frequently used to get the entities with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property values.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

Note that modification of entity state while iterating over the returned enumeration may result in an InvalidOperationException indicating that the collection was modified while enumerating. To avoid this, create a defensive copy using ToList<TSource>(IEnumerable<TSource>) or similar before iterating.

See EF Core change tracking for more information and examples.

GetEntries<TProperty>(string, TProperty?)

Returns an EntityEntry<TEntity> for each entity being tracked by the context where the value of the given property matches the given value. The entries provide access to change tracking information and operations for each entity.

public virtual IEnumerable<EntityEntry<TEntity>> GetEntries<TProperty>(string propertyName, TProperty? propertyValue)

Parameters

propertyName string

The name of the property to match.

propertyValue TProperty

The value of the property to match.

Returns

IEnumerable<EntityEntry<TEntity>>

An entry for each entity being tracked.

Type Parameters

TProperty

The type of the property value.

Remarks

This method is frequently used to get the entities with a given non-null foreign key, primary key, or alternate key values. Lookups using a key property like this are more efficient than lookups on other property values.

By default, accessing Local will call DetectChanges() to ensure that all entities searched and returned are up-to-date. Calling this method will not result in another call to DetectChanges(). Since this method is commonly used for fast lookups, consider reusing the Local object for multiple lookups and/or disabling automatic detecting of changes using AutoDetectChangesEnabled.

Note that modification of entity state while iterating over the returned enumeration may result in an InvalidOperationException indicating that the collection was modified while enumerating. To avoid this, create a defensive copy using ToList<TSource>(IEnumerable<TSource>) or similar before iterating.

See EF Core change tracking for more information and examples.

GetEnumerator()

Returns an IEnumerator<T> for all tracked entities of type TEntity that are not marked as deleted.

public virtual IEnumerator<TEntity> GetEnumerator()

Returns

IEnumerator<TEntity>

An enumerator for the collection.

OnCollectionChanged(NotifyCollectionChangedEventArgs)

Raises the CollectionChanged event.

protected virtual void OnCollectionChanged(NotifyCollectionChangedEventArgs e)

Parameters

e NotifyCollectionChangedEventArgs

Details of the change.

OnPropertyChanged(PropertyChangedEventArgs)

Raises the PropertyChanged event.

protected virtual void OnPropertyChanged(PropertyChangedEventArgs e)

Parameters

e PropertyChangedEventArgs

Details of the property that changed.

OnPropertyChanging(PropertyChangingEventArgs)

Raises the PropertyChanging event.

protected virtual void OnPropertyChanging(PropertyChangingEventArgs e)

Parameters

e PropertyChangingEventArgs

Details of the property that is changing.

Remove(TEntity)

Marks the given entity as Deleted.

public virtual bool Remove(TEntity item)

Parameters

item TEntity

The entity to delete.

Returns

bool

true if the entity was being tracked and was not already Deleted.

Remarks

Entities that are currently marked as Added will be marked as Detached since the Added state indicates that the entity has not been saved to the database and hence it does not make sense to attempt to delete it from the database.

See Local views of tracked entities in EF Core for more information and examples.

Reset()

Resets this view, clearing any IBindingList created with ToBindingList() and any ObservableCollection<T> created with ToObservableCollection(), and clearing any events registered on PropertyChanged, PropertyChanging, or CollectionChanged.

public virtual void Reset()

ToBindingList()

Returns a BindingList<T> implementation that stays in sync with this collection. Use this for WinForms data binding.

public virtual BindingList<TEntity> ToBindingList()

Returns

BindingList<TEntity>

The binding list.

Remarks

See Local views of tracked entities in EF Core for more information and examples.

ToObservableCollection()

Returns an ObservableCollection<T> implementation that stays in sync with this collection. Use this for WPF data binding.

public virtual ObservableCollection<TEntity> ToObservableCollection()

Returns

ObservableCollection<TEntity>

The collection.

Remarks

See Local views of tracked entities in EF Core for more information and examples.

Events

CollectionChanged

Occurs when the contents of the collection changes, either because an entity has been directly added or removed from the collection, or because an entity starts being tracked, or because an entity is marked as Deleted.

public event NotifyCollectionChangedEventHandler? CollectionChanged

Event Type

NotifyCollectionChangedEventHandler

PropertyChanged

Occurs when a property of this collection (such as Count) changes.

public event PropertyChangedEventHandler? PropertyChanged

Event Type

PropertyChangedEventHandler

PropertyChanging

Occurs when a property of this collection (such as Count) is changing.

public event PropertyChangingEventHandler? PropertyChanging

Event Type

PropertyChangingEventHandler