HRM-10/HRM.DA/DA/VirtualPaging/README.md
2026-11-09 17:22:45 +06:00

6.6 KiB

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) <app-virtual-grid>: 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).

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:

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:

[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:

<app-virtual-grid #grid url="/Employee/getDiscontinueEmployeePage" [columns]="columns"
  exportFileName="DiscontinueEmployeeDetails.xlsx"></app-virtual-grid>
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:

// 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).