Multiple enhancements

Author: CSharpBender

NHUnitExample/Controllers/TestController.cs

@@ -1,33 +1,33 @@
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
+using NHibernate.Util;
 using NHUnitExample.Entities;
 using System;
-using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
-using NHibernate.Util;
+using Microsoft.IdentityModel.Protocols.OpenIdConnect;
 using Color = NHUnitExample.Entities.Color;
 
 namespace NHUnitExample.Controllers
 {
     [Route("api/[controller]")]
     [ApiController]
-    public class TestController : ControllerBase
+    public class TestNHUnitController : ControllerBase
     {
-        private readonly ILogger<TestController> _logger;
+        private readonly ILogger<TestNHUnitController> _logger;
         private readonly IDbContext _dbContext;
 
-        public TestController(ILogger<TestController> logger, IDbContext dbContext)
+        public TestNHUnitController(ILogger<TestNHUnitController> logger, IDbContext dbContext)
         {
             _logger = logger;
             _dbContext = dbContext;
         }
 
         /// <summary>
         /// You need to setup the database before testing any other endpoint.
-        /// At every project start the DB schema is recreated: Check Startup.cs -> BuildSchema(Configuration config)
+        /// At every project start the DB schema is recreated: Check Startup.cs - BuildSchema(Configuration config)
         /// </summary>
         /// <param name="cancellationToken"></param>
         /// <returns></returns>
@@ -186,6 +186,33 @@ public async Task<IActionResult> GetAllForCustomer(CancellationToken cancellatio
             return Ok(customer);
         }
 
+
+        /// <summary>
+        /// A simple example for loading a list of entities by id with all the nested children.
+        /// It's similar to IRepository.Get(id), the only difference is that it expects a collection of ids
+        /// </summary>
+        /// <param name="token"></param>
+        /// <param name="customerIds"></param>
+        /// <returns></returns>
+        [HttpGet("/getAllForCustomerIds")]
+        public async Task<IActionResult> GetAllForCustomerIds(CancellationToken token, List<int> customerIds = null)
+        {
+            if (customerIds?.Count == 0)
+            {
+                customerIds = new List<int>() { 11, 12 };
+            }
+
+            //get the customer with all nested data and execute the above query too
+            var customer = await _dbContext.Customers.GetMany(customerIds) //returns a wrapper to configure the query
+                .Include(c => c.Addresses.Single().Country, //include Addresses in the result using the fastest approach: join, new query, batch fetch. Usage: c.Child1.ChildList2.Single().Child3 which means include Child1 and ChildList2 with ALL Child3 properties
+                    c => c.PhoneNumbers.Single().PhoneNumberType, //include all PhoneNumbers with PhoneNumberType
+                    c => c.Cart.Products.Single().Colors) //include Cart with Products and details about products
+                .Unproxy() //instructs the framework to strip all the proxy classes when the Value is returned
+                .ListAsync(token); //this is where the query(s) get executed
+
+            return Ok(customer);
+        }
+
         /// <summary>
         /// A simple example of projecting a query
         /// </summary>
@@ -275,14 +302,26 @@ public async Task<IActionResult> TestMultipleQueries(CancellationToken cancellat
             });
         }
 
+        /// <summary>
+        /// Increase price by 5 for all products that are cheaper than 100 without loading them in memory.
+        /// </summary>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
+        [HttpGet("/testConditionalUpdate")]
+        public async Task<IActionResult> TestConditionalUpdate(CancellationToken cancellationToken)
+        {
+            var productCount = _dbContext.Products.UpdateWhereAsync(p => p.Price < 100, p => new { Price = p.Price + 5 }, cancellationToken);
+            return Ok($"Updated {productCount} products.");
+        }
+
         /// <summary>
         /// Execute your own SQL script using: ExecuteListAsync, ExecuteScalarAsync, ExecuteNonQueryAsync
         /// </summary>
         /// <param name="cancellationToken"></param>
         /// <param name="customerId"></param>
         /// <returns></returns>
-        [HttpGet("/testSqlQuery")]
-        public async Task<IActionResult> TestSqlQuery(CancellationToken cancellationToken, int customerId = 11)
+        [HttpGet("/testScalarQuerySql")]
+        public async Task<IActionResult> TestScalarQuerySql(CancellationToken cancellationToken, int customerId = 11)
         {
             var sqlQuery = @"select Id as CustomerId,
                                     Concat(FirstName,' ',LastName) as FullName,
@@ -293,6 +332,34 @@ public async Task<IActionResult> TestSqlQuery(CancellationToken cancellationToke
             return Ok(customResult);
         }
 
+        /// <summary>
+        /// Execute your own SQL script to get all customers prices using ExecuteListAsync
+        /// </summary>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
+        [HttpGet("/testListQuerySql")]
+        public async Task<IActionResult> TestListQuerySql(CancellationToken cancellationToken)
+        {
+            var sqlQuery = @"select Id, FirstName, LastName, BirthDate  from ""Customer""";
+            var customers = await _dbContext.ExecuteListAsync<Customer>(sqlQuery, null, cancellationToken);
+            return Ok(customers);
+        }
+
+
+        /// <summary>
+        /// Execute your own SQL script to update product prices using ExecuteNonQueryAsync
+        /// </summary>
+        /// <param name="price"></param>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
+        [HttpGet("/testNonQuerySql")]
+        public async Task<IActionResult> TestNonQuerySql(CancellationToken cancellationToken, int price = 5)
+        {
+            var sqlQuery = @"update ""Product"" set price=price+1 where price< :productPrice";
+            await _dbContext.ExecuteNonQueryAsync(sqlQuery, new { productPrice = price }, cancellationToken);
+            return Ok();
+        }
+
 
         /// <summary>
         /// Execute a procedure or multiple queries which return multiple results.
@@ -316,9 +383,9 @@ public async Task<IActionResult> TestDataSetQuery(CancellationToken cancellation
                 typeof(SqlQueryCustomResult), //first result type
                 typeof(long));//second result type
 
-            //The results are returned in order in it's own collection.
+            //The results are returned in order in their own collection.
             var customer = (SqlQueryCustomResult)customResult[0].FirstOrDefault(); //we might not have any results
-            var customerCount = (long)customResult[1].First(); //the time must match: it will fail with int
+            var customerCount = (long)customResult[1].First(); //the type must match: it will fail with int
 
             return Ok(new
             {

NHUnitExample/NHUnitExample.csproj

@@ -5,6 +5,11 @@
     <!--<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>-->
   </PropertyGroup>
 
+  <PropertyGroup>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="FluentNHibernate" Version="2.1.2" />
     <PackageReference Include="Microsoft.AspNetCore.App" />

NHUnitExample/NHUnitExample.xml

@@ -13,9 +13,12 @@
 using NHibernate.Cfg;
 using NHibernate.Dialect;
 using NHibernate.Tool.hbm2ddl;
-using NHUnit;
 using Serilog;
 using Swashbuckle.AspNetCore.Swagger;
+using System;
+using System.IO;
+using System.Reflection;
+using Environment = NHibernate.Cfg.Environment;
 using ILoggerFactory = Microsoft.Extensions.Logging.ILoggerFactory;
 
 namespace NHUnitExample
@@ -55,9 +58,13 @@ public void ConfigureServices(IServiceCollection services)
                 {
                     Version = "v1",
                     Title = "FluentNHibernate Test",
-                    Description = "Test NHibernate & FluentNHibernate on .netcore",
+                    Description = "Test NHUnit with FluentNHibernate on .NET Core",
                     TermsOfService = "None"
                 });
+                // Set the comments path for the Swagger JSON and UI.
+                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+                c.IncludeXmlComments(xmlPath);
             });
 
             services.AddSingleton<ISessionFactory>(CreateSessionFactory());

NHUnitExample/Startup.cs

@@ -69,7 +69,7 @@ public DbContext(ISessionFactory sessionFactory) : base(sessionFactory) {
 
 ## Eager loading
 Using lambda expressions you can specify which child properties should be populated. The framework will determine the fastest approach to load the data: using join, future queries or by using batch fetching.
-Depending on the number of returned rows and the depth you might need to finetune your queries, but in most of the cases the framework takes the best decision.
+Depending on the number of returned rows and the depth you might need to finetune your queries, but in most cases the framework takes the best decision.
 
 ```csharp
 var customer = await _dbContext.Customers.Get(customerId) //returns a wrapper to configure the query
@@ -85,7 +85,7 @@ The expression `c.Addresses.Single().Country` will load all the nested child obj
 
 
 ## Unproxy
-You can use IUnitOfWork.Unproxy, ISingleEntityWrapper.Unproxy or IEntityListWrapper.Unproxy
+You can use Unproxy from IUnitOfWork, ISingleEntityWrapper, IMultipleEntityWrapper or IEntityListWrapper
 
 ```csharp
 var customer = await _dbContext.Customers
@@ -98,23 +98,46 @@ An unproxied object will contain the foreign key ids (One to One and Many to One
 For example in the above query the Cart property will be instantiated and popuplated with the Id field.
 
 
-## Multi Queries
+## Deferred Execution
 Using `Deferred()` you can execute multiple queries in a single server trip.
 Bellow is an example with 3 different queries that get executed in one server trip.
 
 ```csharp
 //product count future
 var prodCountP = _dbContext.WrapQuery(_dbContext.Products.All())
-                           .Count().Deferred();
+                           .Count()
+                           .Deferred();
 
 //most expensive 10 products future
 var expProdsP = _dbContext.WrapQuery(_dbContext.Products.All().OrderByDescending(p => p.Price).Take(10))
                           .Deferred();
 
 //get customer by id - executes all queries
-var customer = await _dbContext.Customers.Get(customerId).Deferred().ValueAsync();
-var prodCount = await prodCountP.ValueAsync(); //returns value
-var expProds = await expProdsP.ListAsync(); //returns value
+var customer = await _dbContext.Customers
+                               .Get(customerId)
+                               .Deferred()
+                               .ValueAsync();
+var prodCount = await prodCountP.ValueAsync(); //returns one value
+var expProds = await expProdsP.ListAsync(); //returns list
+```
+
+
+## Conditional Queries
+If you need to update or delete a set of records that meet a condition, you don't need to load them in memory. Just write an expression and it will be evaluated immediately.
+You should always run your commands inside a transaction with `BeginTransaction()` and `CommitTransactionAsync`.
+
+### UpdateWhereAsync
+Increase price by 5 for all products that are less than 100, without loading them in memory.
+
+```csharp
+await _dbContext.Products.UpdateWhereAsync(p => p.Price < 100, p => new { Price = p.Price + 5 });
+```
+
+### DeleteWhereAsync
+Delete products that are too cheap, without loading them in memory.
+
+```csharp
+await _dbContext.Products.DeleteWhereAsync(p => p.Price < 2);
 ```
 
 
@@ -128,11 +151,15 @@ IUnitOfWork exposes:
 
 
 ## Procedures/Queries
-In some rare cases you need to execute your own queries and NHUnit provides this functionality:
-- ExecuteListAsync
-- ExecuteScalarAsync
-- ExecuteNonQueryAsync
-- ExecuteMultipleQueries
+In some rare cases you need to execute your own queries/procedures and NHUnit provides this functionality:
+- ExecuteListAsync : return a list of values
+
+```csharp
+var sqlQuery = @"select Id, FirstName, LastName, BirthDate  from ""Customer""";
+var customers = await _dbContext.ExecuteListAsync<Customer>(sqlQuery, null, cancellationToken);
+```
+
+- ExecuteScalarAsync : return single value/object
 
 ```csharp
 var sqlQuery = @"select Id as CustomerId,
@@ -141,4 +168,32 @@ var sqlQuery = @"select Id as CustomerId,
                         from ""Customer""
                         where Id= :customerId";
 var customResult = await _dbContext.ExecuteScalarAsync<SqlQueryCustomResult>(sqlQuery, new { customerId = 11 });
+```
+
+- ExecuteNonQueryAsync : no value returned
+
+```csharp
+var sqlQuery = @"update ""Product"" set price=price+1 where price< :productPrice";
+await _dbContext.ExecuteNonQueryAsync(sqlQuery, new { productPrice = 5 }, cancellationToken);
+```
+
+- ExecuteMultipleQueriesAsync : return multiple result sets
+
+```csharp
+var sqlQuery = @"select Id as CustomerId,
+                        Concat(FirstName,' ',LastName) as FullName,
+                        BirthDate
+                 from ""Customer""
+                 where Id= :customerId;
+
+                select count(*) Count from ""Customer"";";
+var customResult = await _dbContext.ExecuteMultipleQueriesAsync(sqlQuery, //query
+    new { customerId }, //parameters: property name must be the same as the parameter
+    cancellationToken,
+    typeof(SqlQueryCustomResult), //first result type
+    typeof(long));//second result type
+
+//The results are returned in order in their own collection.
+var customer = (SqlQueryCustomResult)customResult[0].FirstOrDefault(); //we might not have any results
+var customerCount = (long)customResult[1].First(); //the type must match
 ```