Add async counterparts for Single(Key)/SingleOrDefault(Key)

Author: alex-kulakov

ChangeLog/7.2.1-dev.txt

@@ -0,0 +1 @@
+[main] Added Query.SingleAsync()/SingleOrDefaultAsync and QueryEndpoint.SingleAsync()/SingleOrDefaultAsync methods

Orm/Xtensive.Orm/Orm/Providers/ChainingSessionHandler.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2009-2020 Xtensive LLC.
+// Copyright (C) 2009-2026 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Alexander Nikolaev
@@ -138,6 +138,9 @@ public override EntityState FetchEntityState(Key key)
       return ChainedHandler.FetchEntityState(key);
     }
 
+    /// <inheritdoc/>
+    public override Task<EntityState> FetchEntityStateAsync(Key key, CancellationToken token = default) => ChainedHandler.FetchEntityStateAsync(key, token);
+
     /// <inheritdoc/>
     public override void FetchField(Key key, FieldInfo field)
     {

Orm/Xtensive.Orm/Orm/Providers/SessionHandler.Fetching.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2009-2020 Xtensive LLC.
+// Copyright (C) 2009-2026 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Denis Krjuchkov
@@ -36,7 +36,7 @@ partial class SessionHandler
     /// <param name="key">The key.</param>
     /// <param name="type">The type of the <see cref="Entity"/>.</param>
     /// <param name="descriptors">The descriptors of fields which values will be loaded.</param>
-    /// <param name="token">The token to cancel this operation</param>
+    /// <param name="token">The token to cancel this operation.</param>
     /// <returns>A <see cref="StrongReferenceContainer"/> which can be used to save
     /// a strong reference to a fetched <see cref="Entity"/>.</returns>
     public abstract Task<StrongReferenceContainer> PrefetchAsync(
@@ -57,7 +57,7 @@ public abstract Task<StrongReferenceContainer> PrefetchAsync(
     /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
     /// <param name="skipPersist">if set to <see langword="true"/> persist is not performed.</param>
-    /// <param name="token">The token to cancel this operation</param>
+    /// <param name="token">The token to cancel this operation.</param>
     /// <returns>A <see cref="StrongReferenceContainer"/> which can be used to save
     /// a strong reference to a fetched <see cref="Entity"/>.</returns>
     public abstract Task<StrongReferenceContainer> ExecutePrefetchTasksAsync(
@@ -79,6 +79,7 @@ public StrongReferenceContainer ExecutePrefetchTasks()
     /// <remarks>Multiple active operations in the same session instance are not supported. Use
     /// <see langword="await"/> to ensure that all asynchronous operations have completed before calling
     /// another method in this session.</remarks>
+    /// <param name="token">The token to cancel this operation.</param>
     /// <returns>A <see cref="StrongReferenceContainer"/> which can be used to save
     /// a strong reference to a fetched <see cref="Entity"/>.</returns>
     public Task<StrongReferenceContainer> ExecutePrefetchTasksAsync(CancellationToken token = default)
@@ -90,9 +91,21 @@ public Task<StrongReferenceContainer> ExecutePrefetchTasksAsync(CancellationToke
     /// Fetches an <see cref="EntityState"/>.
     /// </summary>
     /// <param name="key">The key.</param>
-    /// <returns>The key of fetched <see cref="EntityState"/>.</returns>
+    /// <returns>Fetched <see cref="EntityState"/> for given <paramref name="key"/>.</returns>
     public abstract EntityState FetchEntityState(Key key);
 
+    /// <summary>
+    /// Fetches an <see cref="EntityState"/>.
+    /// </summary>
+    /// <param name="key">The key.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>Fetched <see cref="EntityState"/> for given <paramref name="key"/>.</returns>
+    public virtual Task<EntityState> FetchEntityStateAsync(Key key, CancellationToken token = default)
+    {
+      var result = FetchEntityState(key);
+      return Task.FromResult(result);
+    }
+
     /// <summary>
     /// Fetches the field of an <see cref="Entity"/>.
     /// </summary>

Orm/Xtensive.Orm/Orm/Providers/SqlSessionHandler.Fetching.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2009-2020 Xtensive LLC.
+// Copyright (C) 2009-2026 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Denis Krjuchkov
@@ -44,17 +44,23 @@ public override Task<StrongReferenceContainer> ExecutePrefetchTasksAsync(bool sk
       return prefetchManager.ExecuteTasksAsync(skipPersist, token);
     }
 
-    /// <summary>
-    /// Fetches an <see cref="EntityState"/>.
-    /// </summary>
-    /// <param name="key">The key.</param>
-    /// <returns>The key of fetched <see cref="EntityState"/>.</returns>
+    /// <inheritdoc/>
     public override EntityState FetchEntityState(Key key)
     {
       var type = key.TypeReference.Type;
-      prefetchManager.Prefetch(key, type,
+      _ = prefetchManager.Prefetch(key, type,
         PrefetchHelper.GetCachedDescriptorsForFieldsLoadedByDefault(Session.Domain, type));
-      prefetchManager.ExecuteTasks(true);
+      _ = prefetchManager.ExecuteTasks(true);
+      return LookupState(key, out var result) ? result : null;
+    }
+
+    /// <inheritdoc/>
+    public override async Task<EntityState> FetchEntityStateAsync(Key key, CancellationToken token = default)
+    {
+      var type = key.TypeReference.Type;
+      _ = await prefetchManager.PrefetchAsync(key, type,
+        PrefetchHelper.GetCachedDescriptorsForFieldsLoadedByDefault(Session.Domain, type), token).ConfigureAwait(false);
+      _ = await prefetchManager.ExecuteTasksAsync(true).ConfigureAwait(false);
       return LookupState(key, out var result) ? result : null;
     }
 

Orm/Xtensive.Orm/Orm/Query.cs

@@ -1,4 +1,4 @@
-// Copyright (C) 2009-2020 Xtensive LLC.
+// Copyright (C) 2009-2026 Xtensive LLC.
 // This code is distributed under MIT license terms.
 // See the License.txt file in the project root for more information.
 // Created by: Dmitri Maximov
@@ -204,6 +204,21 @@ public static Entity Single(Key key)
       return Session.Demand().Query.Single(key);
     }
 
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <param name="key">The key to resolve.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
+    /// </returns>
+    /// <exception cref="KeyNotFoundException">Entity with the specified key is not found.</exception>
+    public static ValueTask<Entity> SingleAsync(Key key, CancellationToken token = default)
+    {
+      return Session.Demand().Query.SingleAsync(key, token);
+    }
+
     /// <summary>
     /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
     /// in the current <see cref="Session"/>.
@@ -213,7 +228,8 @@ public static Entity Single(Key key)
     /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
     /// <see langword="null"/>, if there is no such entity.
     /// </returns>
-    [CanBeNull] public static Entity SingleOrDefault(Key key)
+    [CanBeNull]
+    public static Entity SingleOrDefault(Key key)
     {
       return Session.Demand().Query.SingleOrDefault(key);
     }
@@ -222,18 +238,51 @@ [CanBeNull] public static Entity SingleOrDefault(Key key)
     /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
     /// in the current <see cref="Session"/>.
     /// </summary>
-    /// <typeparam name="T">Type of the entity.</typeparam>
     /// <param name="key">The key to resolve.</param>
+    /// <param name="token">The token to cancel this operation.</param>
     /// <returns>
     /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
     /// <see langword="null"/>, if there is no such entity.
     /// </returns>
+    [CanBeNull]
+    public static ValueTask<Entity> SingleOrDefaultAsync(Key key, CancellationToken token = default)
+    {
+      return Session.Demand().Query.SingleOrDefaultAsync(key, token);
+    }
+
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <typeparam name="T">Type of the entity.</typeparam>
+    /// <param name="key">The key to resolve.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
+    /// </returns>
+    /// <exception cref="KeyNotFoundException">Entity with the specified key is not found.</exception>
     public static T Single<T>(Key key)
       where T : class, IEntity
     {
       return Session.Demand().Query.Single<T>(key);
     }
 
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <typeparam name="T">Type of the entity.</typeparam>
+    /// <param name="key">The key to resolve.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
+    /// </returns>
+    /// <exception cref="KeyNotFoundException">Entity with the specified key is not found.</exception>
+    public static Task<T> SingleAsync<T>(Key key, CancellationToken token = default)
+      where T : class, IEntity
+    {
+      return Session.Demand().Query.SingleAsync<T>(key, token);
+    }
+
     /// <summary>
     /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="keyValues"/>
     /// in the current <see cref="Session"/>.
@@ -242,14 +291,31 @@ public static T Single<T>(Key key)
     /// <param name="keyValues">Key values.</param>
     /// <returns>
     /// The <see cref="Entity"/> specified <paramref name="keyValues"/> identify.
-    /// <see langword="null"/>, if there is no such entity.
     /// </returns>
+    /// <exception cref="KeyNotFoundException">Entity with the specified key is not found.</exception>
     public static T Single<T>(params object[] keyValues)
       where T : class, IEntity
     {
       return Session.Demand().Query.Single<T>(keyValues);
     }
 
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="keyValues"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <typeparam name="T">Type of the entity.</typeparam>
+    /// <param name="keyValues">Key values.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="keyValues"/> identify.
+    /// </returns>
+    /// <exception cref="KeyNotFoundException">Entity with the specified key is not found.</exception>
+    public static Task<T> SingleAsync<T>(object[] keyValues, CancellationToken token)
+      where T : class, IEntity
+    {
+      return Session.Demand().Query.SingleAsync<T>(keyValues, token);
+    }
+
     /// <summary>
     /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
     /// in the current <see cref="Session"/>.
@@ -258,13 +324,33 @@ public static T Single<T>(params object[] keyValues)
     /// <param name="key">The key to resolve.</param>
     /// <returns>
     /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
+    /// <see langword="null"/>, if there is no such entity.
     /// </returns>
-    [CanBeNull] public static T SingleOrDefault<T>(Key key)
+    [CanBeNull]
+    public static T SingleOrDefault<T>(Key key)
       where T : class, IEntity
     {
       return Session.Demand().Query.SingleOrDefault<T>(key);
     }
 
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="key"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <typeparam name="T">Type of the entity.</typeparam>
+    /// <param name="key">The key to resolve.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="key"/> identifies.
+    /// <see langword="null"/>, if there is no such entity.
+    /// </returns>
+    [CanBeNull]
+    public static Task<T> SingleOrDefaultAsync<T>(Key key, CancellationToken token)
+      where T : class, IEntity
+    {
+      return Session.Demand().Query.SingleOrDefaultAsync<T>(key, token);
+    }
+
     /// <summary>
     /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="keyValues"/>
     /// in the current <see cref="Session"/>.
@@ -273,13 +359,32 @@ [CanBeNull] public static T SingleOrDefault<T>(Key key)
     /// <param name="keyValues">Key values.</param>
     /// <returns>
     /// The <see cref="Entity"/> specified <paramref name="keyValues"/> identify.
+    /// <see langword="null"/>, if there is no such entity.
     /// </returns>
-    [CanBeNull] public static T SingleOrDefault<T>(params object[] keyValues)
+    [CanBeNull]
+    public static T SingleOrDefault<T>(params object[] keyValues)
       where T : class, IEntity
     {
       return Session.Demand().Query.SingleOrDefault<T>(keyValues);
     }
 
+    /// <summary>
+    /// Resolves (gets) the <see cref="Entity"/> by the specified <paramref name="keyValues"/>
+    /// in the current <see cref="Session"/>.
+    /// </summary>
+    /// <typeparam name="T">Type of the entity.</typeparam>
+    /// <param name="keyValues">Key values.</param>
+    /// <param name="token">The token to cancel this operation.</param>
+    /// <returns>
+    /// The <see cref="Entity"/> specified <paramref name="keyValues"/> identify.
+    /// <see langword="null"/>, if there is no such entity.
+    /// </returns>
+    public static Task<T> SingleOrDefault<T>(object[] keyValues, CancellationToken token)
+      where T : class, IEntity
+    {
+      return Session.Demand().Query.SingleOrDefaultAsync<T>(keyValues, token);
+    }
+
     #region Execute
 
     /// <summary>