Proposal: Reusable Paginated Grid Package for ERP Crystal Projects

This document outlines the technical design for packaging the server-side grid filtering, state helper, and SQL generation utilities into reusable NuGet packages. This eliminates copy-pasting and ensures a single point of maintenance across other projects.

1. Architectural Strategy

Since the grid utilities cross different boundaries (Frontend vs. Backend), a single package would introduce unwanted dependencies (e.g., forcing an API project to pull in MudBlazor or Blazored.LocalStorage).

We propose splitting the logic into two targeted NuGet packages:

graph TD
    classDef package fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px;
    classDef app fill:#f1f8e9,stroke:#8bc34a,stroke-width:2px;

    CorePkg[ErpCrystal.GridPagination.Core
NuGet Package]:::package
    WebPkg[ErpCrystal.GridPagination.Web
NuGet Package]:::package

    CorePkg --> Dapper[Dapper]
    WebPkg --> CorePkg
    WebPkg --> MudBlazor[MudBlazor]
    WebPkg --> LocalStorage[Blazored.LocalStorage]

    ApiProj[Backend API Solutions]:::app
    WebProj[Blazor Web Solutions]:::app

    ApiProj --> CorePkg
    WebProj --> WebPkg

A. ErpCrystal.GridPagination.Core (Models & API)

• Target Framework: .NET Standard 2.0 or .NET 10.0
• Dependencies: Dapper (>= 2.0.123)
• Contents:
  • [Models] FilterCondition.cs
  • [Models] FilterMetadata.cs
  • [Models] PaginatedGridState.cs
  • [Models] PaginatedGridResult.cs
  • [API Repositories] PaginatedGridSqlGenerator.cs

B. ErpCrystal.GridPagination.Web (Blazor Frontend)

• Target Framework: .NET 10.0 (Razor Class Library)
• Dependencies:
  • ErpCrystal.GridPagination.Core (Local Dependency)
  • MudBlazor (>= 6.9.0)
  • Blazored.LocalStorage (>= 4.5.0)
• Contents:
  • [Web Helpers] PaginatedGridStateHelper.cs
  • [Web Helpers] PaginatedGridFilterHelper.cs

2. Package Creation Workflow

To package these classes:

1. Initialize the Projects: Create a new Class Library for Core, and a Razor Class Library (RCL) for Web.
2. Move Code Files: Copy the corresponding .cs files into each library.
3. Configure Project Files (.csproj): Add NuGet package properties.

Example .csproj Configuration (ErpCrystal.GridPagination.Core.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <Version>1.0.0</Version>
    <Authors>ERP Crystal Team</Authors>
    <Description>Shared models and backend SQL generators for server-side paginated grids.</Description>
    <PackageId>ErpCrystal.GridPagination.Core</PackageId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Dapper" Version="2.0.123" />
  </ItemGroup>
</Project>

4. Pack the Libraries: Run the command:

   dotnet pack -c Release
   This generates .nupkg files in bin/Release/.

3. Hosting & Distribution Options

To share the packages securely across different developers and project repositories, choose one of these hosting solutions:

Accessing Local Folder Feed (nuget.config):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="ErpCrystalLocalFeed" value="D:\SharedNuGetPackages" />
  </packageSources>
</configuration>

4. Maintenance & Versioning Best Practices

• Semantic Versioning (SemVer):
  • Increment Patch (1.0.1) for bug fixes.
  • Increment Minor (1.1.0) for backward-compatible features (e.g. supporting a new SQL operator type).
  • Increment Major (2.0.0) for breaking changes (e.g. changing method signatures).
• CI/CD Automation: Use GitHub Actions or Azure DevOps Pipelines to automatically build, pack, version, and publish the NuGet package whenever code changes are merged to the main branch of the packaging repository.