comments

Author: tibitoth

src/AutSoft.Core/Exceptions/EntityNotFoundException.cs

@@ -12,11 +12,20 @@ public sealed class EntityNotFoundException : Exception
     /// </summary>
     /// <param name="message">Exception's message</param>
     /// <param name="innerException">Related tiggering exception</param>
-    private EntityNotFoundException(string message, Exception innerException)
+    private EntityNotFoundException(string message, Exception? innerException = null)
         : base(message, innerException)
     {
     }
 
+    /// <summary>
+    /// Foctory method which creates an <see cref="EntityNotFoundException"/> with a standard message.
+    /// </summary>
+    /// <typeparam name="T">Not found entity's type</typeparam>
+    /// <param name="id">Entity's id</param>
+    /// <returns>Returns <see cref="EntityNotFoundException"/> with a standard message.</returns>
+    public static EntityNotFoundException CreateForType<T>(long? id)
+        => new($"Cannot find entity of type {typeof(T).Name}" + (id.HasValue ? $" with id={id}" : string.Empty));
+
     /// <summary>
     /// Foctory method which creates an <see cref="EntityNotFoundException"/> with a standard message.
     /// </summary>
@@ -27,6 +36,15 @@ private EntityNotFoundException(string message, Exception innerException)
     public static EntityNotFoundException CreateForType<T>(Exception innerException, long? id)
         => new($"Cannot find entity of type {typeof(T).Name}" + (id.HasValue ? $" with id={id}" : string.Empty), innerException);
 
+    /// <summary>
+    /// Foctory method which creates an <see cref="EntityNotFoundException"/> with a standard message.
+    /// </summary>
+    /// <typeparam name="T">Not found entity's type</typeparam>
+    /// <param name="queryParameters">Search parameters which occur this error</param>
+    /// <returns>Returns <see cref="EntityNotFoundException"/> with a standard message.</returns>
+    public static EntityNotFoundException CreateForTypeCustomParams<T>(params object[] queryParameters)
+        => new($"Cannot find entity of type {typeof(T).Name} with params:" + string.Join("; ", queryParameters));
+
     /// <summary>
     /// Foctory method which creates an <see cref="EntityNotFoundException"/> with a standard message.
     /// </summary>

src/AutSoft.Linq/Models/OrderDirection.cs

@@ -1,7 +1,17 @@
 namespace AutSoft.Linq.Models;
 
+/// <summary>
+/// Order direction of a query
+/// </summary>
 public enum OrderDirection
 {
+    /// <summary>
+    /// Ascending order direction
+    /// </summary>
     Ascending = 0,
+
+    /// <summary>
+    /// Descending order direction
+    /// </summary>
     Descending = 1,
 }

src/AutSoft.Linq/Models/PageRequest.cs

@@ -1,9 +1,27 @@
 namespace AutSoft.Linq.Models;
 
+/// <summary>
+/// Common query parameters for a paged request (mostly for grids and lists)
+/// </summary>
 public class PageRequest
 {
+    /// <summary>
+    /// Gets or sets requested page's size, default is 50
+    /// </summary>
     public int PageSize { get; set; } = 50;
+
+    /// <summary>
+    /// Gets or sets requested page, 0 represents first page
+    /// </summary>
     public int Page { get; set; }
+
+    /// <summary>
+    /// Gets or sets order by based on this property's name
+    /// </summary>
     public string? OrderBy { get; set; }
+
+    /// <summary>
+    /// Gets or sets order direction, default is <see cref="OrderDirection.Ascending"/>
+    /// </summary>
     public OrderDirection OrderDirection { get; set; } = OrderDirection.Ascending;
 }

src/AutSoft.Linq/Models/PageResponse.cs

@@ -1,7 +1,18 @@
 namespace AutSoft.Linq.Models;
 
+/// <summary>
+/// Wraps a page of the requested objects
+/// </summary>
+/// <typeparam name="T">Type of requested objects</typeparam>
 public class PageResponse<T>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PageResponse{T}"/> class.
+    /// </summary>
+    /// <param name="results">List of objects of the current page</param>
+    /// <param name="currentPage">Current page's index (start's from 0)</param>
+    /// <param name="totalCount">Total object count on all pages</param>
+    /// <param name="pageCount">Total page count</param>
     public PageResponse(List<T> results, int currentPage, int totalCount, int pageCount)
     {
         Results = results;
@@ -10,9 +21,23 @@ public PageResponse(List<T> results, int currentPage, int totalCount, int pageCo
         PageCount = pageCount;
     }
 
+    /// <summary>
+    /// Gets or sets objects of the current page
+    /// </summary>
     public List<T> Results { get; set; }
 
+    /// <summary>
+    /// Gets or sets current page's index (start's from 0)
+    /// </summary>
     public int CurrentPage { get; set; }
+
+    /// <summary>
+    /// Gets or sets total page count
+    /// </summary>
     public int PageCount { get; set; }
+
+    /// <summary>
+    /// Gets or sets total object count on all pages
+    /// </summary>
     public int TotalCount { get; set; }
 }

src/AutSoft.Linq/Queryable/FirstAndSingleExtensions.cs

@@ -6,56 +6,38 @@
 
 namespace AutSoft.Linq.Queryable;
 
+/// <summary>
+/// Extensions methods for <see cref="IQueryable{T}"/> with extended functionality for Single and First methods/>
+/// </summary>
 public static class FirstAndSingleExtensions
 {
-    public static async Task<T> SingleEntityAsync<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate, long entityId)
+    /// <summary>
+    /// Similar to <see cref="EntityFrameworkQueryableExtensions.SingleOrDefaultAsync{TSource}(IQueryable{TSource}, CancellationToken)"/>
+    /// </summary>
+    /// <typeparam name="T">The type of the elements of <paramref name="source" />.</typeparam>
+    /// <param name="source">An <see cref="IQueryable{T}" /> to return the single element of.</param>
+    /// <param name="predicate">A function to test an element for a condition.</param>
+    /// <param name="entityId">Identifier of the requested element</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
+    /// <exception cref="EntityNotFoundException">Throws when no result found</exception>
+    public static async Task<T> SingleEntityAsync<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate, long entityId, CancellationToken cancellationToken = default)
     {
-        try
-        {
-            return await source.SingleAsync(predicate);
-        }
-        catch (InvalidOperationException e)
-        {
-            // Single throws an InvalidOperationException when no entities are found
-            throw EntityNotFoundException.CreateForType<T>(e, entityId);
-        }
+        return await source.SingleOrDefaultAsync(predicate, cancellationToken)
+            ?? throw EntityNotFoundException.CreateForType<T>(entityId);
     }
 
-    public static async Task<T> SingleEntityAsync<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate, params object[] queryParameters)
+    /// <summary>
+    /// Similar to <see cref="EntityFrameworkQueryableExtensions.SingleOrDefaultAsync{TSource}(IQueryable{TSource}, CancellationToken)"/>
+    /// </summary>
+    /// <typeparam name="T">The type of the elements of <paramref name="source" />.</typeparam>
+    /// <param name="source">An <see cref="IQueryable{T}" /> to return the single element of.</param>
+    /// <param name="predicate">A function to test an element for a condition.</param>
+    /// <param name="queryParameters">Query parameters of the requested element</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
+    /// <exception cref="EntityNotFoundException">Throws when no result found</exception>
+    public static async Task<T> SingleEntityAsync<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate, object[] queryParameters, CancellationToken cancellationToken = default)
     {
-        try
-        {
-            return await source.SingleAsync(predicate);
-        }
-        catch (InvalidOperationException e)
-        {
-            // Single throws an InvalidOperationException when no entities are found
-            throw EntityNotFoundException.CreateForTypeCustomParams<T>(e, queryParameters);
-        }
-    }
-
-    public static T SingleEntity<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate, params object[] queryParameters)
-    {
-        try
-        {
-            return source.Single(predicate);
-        }
-        catch (InvalidOperationException e)
-        {
-            // Single throws an InvalidOperationException when no entities are found
-            throw EntityNotFoundException.CreateForTypeCustomParams<T>(e, queryParameters);
-        }
-    }
-
-    public static async Task<T> FirstEntityAsync<T>(this IQueryable<T> source, Expression<Func<T, bool>> predicate)
-    {
-        try
-        {
-            return await source.FirstAsync(predicate);
-        }
-        catch (InvalidOperationException e)
-        {
-            throw EntityNotFoundException.CreateForType<T>(e, default);
-        }
+        return await source.SingleAsync(predicate, cancellationToken)
+            ?? throw EntityNotFoundException.CreateForTypeCustomParams<T>(queryParameters);
     }
 }

src/AutSoft.Linq/Queryable/NotSortableAttribute.cs

@@ -1,5 +1,8 @@
 namespace AutSoft.Linq.Queryable;
 
+/// <summary>
+/// Indicates if a property is not sortable by <see cref="OrderByExtensions"/>
+/// </summary>
 [AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
 public class NotSortableAttribute : Attribute
 {