Skip to content

Commit

Permalink
Clarify documentation for setting state of single Entity
Browse files Browse the repository at this point in the history 
Fixes #10947
  • Loading branch information
@ajcvickers
ajcvickers committed Apr 12, 2018
1 parent 2d19f27 commit fa14b1c
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 9 deletions.
4 changes: 4 additions & 0 deletions src/EFCore/ChangeTracking/EntityEntry.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,10 @@ public EntityEntry([NotNull] InternalEntityEntry internalEntry)
/// Gets or sets that state that this entity is being tracked in.
/// </para>
/// <para>
/// This method sets only the state of the single entity represented by this entry. It does
/// not change the state of other entities reachable from this one.
/// </para>
/// <para>
/// When setting the state, the entity will always end up in the specified state. For example, if you
/// change the state to <see cref="EntityState.Deleted" /> the entity will be marked for deletion regardless
/// of its current state. This is different than calling <see cref="DbSet{TEntity}.Remove(TEntity)" /> where the entity
Expand Down
49 changes: 43 additions & 6 deletions src/EFCore/DbContext.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -698,9 +698,14 @@ await entry.SetEntityStateAsync(
}

/// <summary>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that
/// they will be inserted into the database when <see cref="SaveChanges()" /> is called.
/// <para>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that
/// they will be inserted into the database when <see cref="SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <typeparam name="TEntity"> The type of the entity. </typeparam>
/// <param name="entity"> The entity to add. </param>
Expand Down Expand Up @@ -765,6 +770,9 @@ public virtual async Task<EntityEntry<TEntity>> AddAsync<TEntity>(
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <typeparam name="TEntity"> The type of the entity. </typeparam>
/// <param name="entity"> The entity to attach. </param>
Expand Down Expand Up @@ -799,6 +807,9 @@ public virtual EntityEntry<TEntity> Attach<TEntity>([NotNull] TEntity entity)
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <typeparam name="TEntity"> The type of the entity. </typeparam>
/// <param name="entity"> The entity to update. </param>
Expand Down Expand Up @@ -829,6 +840,9 @@ public virtual EntityEntry<TEntity> Update<TEntity>([NotNull] TEntity entity)
/// they would be if <see cref="Attach{TEntity}(TEntity)" /> was called before calling this method.
/// This allows any cascading actions to be applied when <see cref="SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </remarks>
/// <typeparam name="TEntity"> The type of the entity. </typeparam>
/// <param name="entity"> The entity to remove. </param>
Expand Down Expand Up @@ -873,9 +887,17 @@ private EntityEntry<TEntity> SetEntityState<TEntity>(
}

/// <summary>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that they will
/// be inserted into the database when <see cref="SaveChanges()" /> is called.
/// <para>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that they will
/// be inserted into the database when <see cref="SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to add. </param>
/// <returns>
Expand All @@ -896,10 +918,16 @@ public virtual EntityEntry Add([NotNull] object entity)
/// be inserted into the database when <see cref="SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// <para>
/// This method is async only to allow special value generators, such as the one used by
/// 'Microsoft.EntityFrameworkCore.Metadata.SqlServerValueGenerationStrategy.SequenceHiLo',
/// to access the database asynchronously. For all other cases the non async method should be used.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to add. </param>
/// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
Expand Down Expand Up @@ -936,6 +964,9 @@ public virtual async Task<EntityEntry> AddAsync(
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to attach. </param>
/// <returns>
Expand Down Expand Up @@ -968,6 +999,9 @@ public virtual EntityEntry Attach([NotNull] object entity)
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to update. </param>
/// <returns>
Expand Down Expand Up @@ -996,6 +1030,9 @@ public virtual EntityEntry Update([NotNull] object entity)
/// they would be if <see cref="Attach(object)" /> was called before calling this method.
/// This allows any cascading actions to be applied when <see cref="SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </remarks>
/// <param name="entity"> The entity to remove. </param>
/// <returns>
Expand Down
23 changes: 20 additions & 3 deletions src/EFCore/DbSet`.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,14 @@ public virtual Task<TEntity> FindAsync([CanBeNull] object[] keyValues, Cancellat
=> throw new NotImplementedException();

/// <summary>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that they will
/// be inserted into the database when <see cref="DbContext.SaveChanges()" /> is called.
/// <para>
/// Begins tracking the given entity, and any other reachable entities that are
/// not already being tracked, in the <see cref="EntityState.Added" /> state such that they will
/// be inserted into the database when <see cref="DbContext.SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to add. </param>
/// <returns>
Expand All @@ -121,6 +126,9 @@ public virtual Task<TEntity> FindAsync([CanBeNull] object[] keyValues, Cancellat
/// 'Microsoft.EntityFrameworkCore.Metadata.SqlServerValueGenerationStrategy.SequenceHiLo',
/// to access the database asynchronously. For all other cases the non async method should be used.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to add. </param>
/// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
Expand Down Expand Up @@ -148,6 +156,9 @@ public virtual Task<EntityEntry<TEntity>> AddAsync(
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to attach. </param>
/// <returns>
Expand All @@ -171,6 +182,9 @@ public virtual Task<EntityEntry<TEntity>> AddAsync(
/// they would be if <see cref="Attach(TEntity)" /> was called before calling this method.
/// This allows any cascading actions to be applied when <see cref="DbContext.SaveChanges()" /> is called.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </remarks>
/// <param name="entity"> The entity to remove. </param>
/// <returns>
Expand Down Expand Up @@ -198,6 +212,9 @@ public virtual Task<EntityEntry<TEntity>> AddAsync(
/// An entity is considered to have its primary key value set if the primary key property is set
/// to anything other than the CLR default for the property type.
/// </para>
/// <para>
/// Use <see cref="EntityEntry.State"/> to set the state of only a single entity.
/// </para>
/// </summary>
/// <param name="entity"> The entity to update. </param>
/// <returns>
Expand Down

0 comments on commit fa14b1c

Please sign in to comment.