# Virtual paging: large lists with virtual scrolling SQL Server does the paging. Each request reads only the rows the grid needs (100 at a time) with `OFFSET … FETCH`, and the search, sort and total count run in the same SQL. Nothing is kept in server memory, so it works the same for 1,000 or 1,000,000 rows and always shows the latest data. | Piece | File | What it does | |---|---|---| | Request / result | `HRM.BO/VirtualPaging/VirtualPaging.cs` | `VirtualPageRequest` (filters, columns, skip/take, search, sort) and `VirtualPageResult`, shared by every page | | Paging SQL | `HRM.DA/DA/VirtualPaging/VirtualPagingDA.cs` | Wraps a page's query with search, sort, `OFFSET/FETCH` and the totals | | Excel | `HRM.DA/DA/VirtualPaging/VirtualPagingExcel.cs` | Streams the rows from SQL Server straight into an `.xlsx` (Open XML SAX writer) | | Grid | `ClientApp/src/app/custom-components/virtual-grid/` (`VirtualGridModule`) | ``: virtual scrolling, search box, total, Export to Excel | ## A new page: 4 small steps (worked example: Discontinue Employee Details) **1. DA: the query.** An ordinary `SELECT` built with `MakeSQL`. Each column alias is a grid field name. No `ORDER BY` and no `WITH` (the query is used as a derived table). ```csharp internal static string GetDiscontinuedEmployeeQuery(DateTime fromDate, DateTime toDate, int payrollTypeID) { return SQLParser.MakeSQL(@" SELECT v.EMPLOYEENO AS employeeNo, v.NAME AS name, v.JOININGDATE AS joiningDate, ISNULL(v.BASICSALARY, 0) AS basicSalary FROM VW_EMPLOYEEBASIC v INNER JOIN EMPLOYEE e ON e.EMPLOYEEID = v.EmployeeId WHERE e.STATUS = %n AND e.PAYROLLTYPEID = %n AND e.ENDOFCONTRACTDATE >= %d AND e.ENDOFCONTRACTDATE < %d", (int)EnumEmployeeStatus.Discontinued, payrollTypeID, fromDate.Date, toDate.Date.AddDays(1)); } ``` **2. Service: one method** (canonical try/catch) + its line in the module's `I…Service` interface: ```csharp public VirtualPageResult GetDiscontinuedEmployeePage(VirtualPageRequest request, DateTime fromDate, DateTime toDate, int payrollTypeID) { VirtualPageResult result = null; TransactionContext tc = null; try { tc = TransactionContext.Begin(); string query = EmployeeDA.GetDiscontinuedEmployeeQuery(fromDate, toDate, payrollTypeID); result = VirtualPagingDA.GetPage(tc, query, request, "employeeNo,employeeId"); // fields that together are unique tc.End(); } catch (Exception e) { if (tc != null) tc.HandleError(); ExceptionLog.Write(e); throw new ServiceException(e.Message, e); } return result; } ``` **3. Controller: one endpoint** in the module's own controller. Read the page's filters from the request: ```csharp [HttpPost("getDiscontinueEmployeePage")] public ActionResult GetDiscontinueEmployeePage(VirtualPageRequest request) { try { CurrentUser currentUser = CurrentUser.GetCurrentUser(HttpContext.User); if (currentUser.UserType == EnumUserType.Employee) return StatusCode(StatusCodes.Status403Forbidden, "You are not allowed to see this report."); DateTime fromDate = request.GetDate("fromDate", "From Date"); // also GetInt / GetString DateTime toDate = request.GetDate("toDate", "To Date"); VirtualPageResult result = _EmployeeService.GetDiscontinuedEmployeePage(request, fromDate, toDate, currentUser.PayrollTypeID ?? 0); if (result.ExcelFile != null) // Export to Excel return File(result.ExcelFile, VirtualPageResult.ExcelContentType, "DiscontinueEmployeeDetails.xlsx"); return Ok(result); } catch (ArgumentException ex) { return BadRequest(ex.Message); } catch (Exception ex) { return StatusCode(StatusCodes.Status500InternalServerError, ex.Message); } } ``` **4. Screen**: import `VirtualGridModule`, then: ```html ``` ```ts columns: VirtualGridColumn[] = [ { field: 'employeeNo', title: 'Employee No', width: 110 }, { field: 'joiningDate', title: 'Joining Date', type: 'date' }, { field: 'basicSalary', title: 'Basic Salary', type: 'money' }, ]; preview() { this.grid.load({ fromDate: this.fromDate, toDate: this.toDate }); // any filters; Dates go as yyyy-MM-dd } ``` `field` = the column alias in the query. Column `type`: `text` (default), `number`, `money` (1,234.56), `date` (dd MMM yyyy), `datetime`. `sortable: false` turns sorting off for a column. ## How one request runs | User action | Request | SQL | |---|---|---| | Preview | `skip 0, take 100, countTotal true` | `COUNT` + first 100 rows, one round trip | | Scroll | `skip 100, 200, …` | next 100 rows only (no `COUNT`) | | Sort | `sortField`, `sortDir` | `ORDER BY` that column, then the unique field | | Search (after 400 ms) | `search`, `countTotal true` | `WHERE` every column `LIKE @vpSearch`, new `COUNT` | | Export to Excel | `exportExcel true` | every matching row, same search and sort, written row by row into an `.xlsx` on the server; the browser only downloads the file | ## Rules - **Speed**: the page query's `WHERE` must use an index (see `DiscontinueEmployeeReport_DB_Changes.sql`). Values computed in C# cannot be searched or sorted, so compute them in the query (see the department tiers and blood group in `GetDiscontinuedEmployeeQuery`). - **Safety**: the query is built by code with `MakeSQL` from typed values (dates, ints). The search text, skip and take are SQL parameters; field names must be plain identifiers and are bracketed. - **Access**: authorization in this app is menu-driven, so every page endpoint checks who may call it (self-service logins are refused above). - The key fields passed to `GetPage` must together be unique (`"employeeNo,employeeId"`: two employees can share an Employee No), so pages never overlap or skip rows. The first one is the default sort. ## Selected IDs (e.g. "employees picked on the screen") Send them as one filter (`employeeIds: "12,15,40"`), read them with `request.GetIntList("employeeIds")`, and pass them as an ID list. `GetPage` loads them into a temp table with a primary key (one parameter, any number of IDs, and a good plan); the query reads the temp table: ```csharp // DA WHERE e.PAYROLLTYPEID = %n AND e.EMPLOYEEID IN (SELECT ID FROM #empIds) // Service result = VirtualPagingDA.GetPage(tc, query, request, "employeeNo,employeeId", VirtualPagingDA.IdList("#empIds", employeeIds)); ``` Worked example: Employee Detail Information (`EmployeeController.GetEmpDetailInfoPage`, `EmployeeDA.GetEmpDetailInfoQuery`). Needs SQL Server 2016+ (`STRING_SPLIT`).