141 lines
6.6 KiB
Markdown
141 lines
6.6 KiB
Markdown
# 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).
|
|
|
|
```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
|
|
<app-virtual-grid #grid url="/Employee/getDiscontinueEmployeePage" [columns]="columns"
|
|
exportFileName="DiscontinueEmployeeDetails.xlsx"></app-virtual-grid>
|
|
```
|
|
```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`).
|