Idevs.Net.CoreLib 0.2.1

Idevs.Net.CoreLib

A comprehensive extension library for the Serenity Framework that provides enhanced functionality for data export, PDF generation, UI components, and more.

Features

• 📊 Excel Export: Advanced Excel generation with formatting, themes, and aggregation support
• 📄 PDF Export: HTML-to-PDF conversion using Puppeteer Sharp
• 🎨 UI Components: Extended form controls and formatters for Serenity
• 🔄 Service Registration: Automatic dependency injection with attributes
• 📐 Bootstrap Grid: Enhanced column width controls with Bootstrap 5 support
• 🌍 Localization: Enhanced text localization extensions

Installation

Install via NuGet Package Manager:

dotnet add package Idevs.Net.CoreLib

Or via Package Manager Console:

Install-Package Idevs.Net.CoreLib

Quick Start

1. Service Registration with Autofac (Recommended)

Idevs.Net.CoreLib now uses Autofac as the preferred dependency injection container. Add the following to your Program.cs:

using Idevs.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configure Autofac as the service provider and register Idevs services
builder.UseIdevsAutofac();

// Your other service registrations
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Your middleware configuration
app.UseRouting();
app.MapControllers();

app.Run();

1.1. Alternative Service Registration (Legacy)

For projects that cannot use Autofac, you can still use the traditional service collection approach:

// In ConfigureServices method or Program.cs
builder.Services.AddIdevsCorelibServices();

// Note: RegisterServices() is now obsolete and included in AddIdevsCorelibServices()

1.2. Advanced Autofac Configuration

For more advanced scenarios, you can customize the Autofac container:

// With custom container configuration
builder.UseIdevsAutofac(containerBuilder =>
{
    // Your custom registrations
    containerBuilder.RegisterType<MyCustomService>()
        .As<IMyCustomService>()
        .InstancePerLifetimeScope();
});

// With additional modules
builder.UseIdevsAutofac(new MyCustomModule(), new AnotherModule());

2. Chrome Setup for PDF Export

Important: For PDF export functionality, you need to download Chrome/Chromium:

// In Program.cs Main method (before starting the application)
public static void Main(string[] args)
{
    // Download Chrome if not already present
    ChromeHelper.DownloadChrome();
    
    CreateHostBuilder(args).Build().Run();
}

Usage Examples

Excel Export

public class OrderController : ServiceEndpoint
{
    private readonly IIdevsExcelExporter _excelExporter;
    
    public OrderController(IIdevsExcelExporter excelExporter)
    {
        _excelExporter = excelExporter;
    }
    
    [HttpPost]
    public IActionResult ExportToExcel(ListRequest request)
    {
        var orders = GetOrders(request); // Your data retrieval logic
        
        // Simple export
        var excelBytes = _excelExporter.Export(orders, typeof(OrderColumns));
        
        return IdevsContentResult.Create(
            excelBytes, 
            IdevsContentType.Excel, 
            "orders.xlsx"
        );
    }
    
    [HttpPost]
    public IActionResult ExportWithHeaders(ListRequest request)
    {
        var orders = GetOrders(request);
        var headers = new[]
        {
            new ReportHeader { HeaderLine = "Order Report" },
            new ReportHeader { HeaderLine = $"Generated: {DateTime.Now:yyyy-MM-dd}" },
            new ReportHeader { HeaderLine = "" } // Empty line
        };
        
        var excelBytes = _excelExporter.Export(orders, typeof(OrderColumns), headers);
        
        return IdevsContentResult.Create(excelBytes, IdevsContentType.Excel, "order-report.xlsx");
    }
}

PDF Export

public class ReportController : ServiceEndpoint
{
    private readonly IIdevsPdfExporter _pdfExporter;
    private readonly IViewPageRenderer _viewRenderer;
    
    public ReportController(IIdevsPdfExporter pdfExporter, IViewPageRenderer viewRenderer)
    {
        _pdfExporter = pdfExporter;
        _viewRenderer = viewRenderer;
    }
    
    [HttpPost]
    public async Task<IActionResult> GenerateReport(ReportRequest request)
    {
        // Render HTML from Razor view
        var model = GetReportData(request);
        var html = await _viewRenderer.RenderViewAsync("Reports/OrderReport", model);
        
        // Convert to PDF
        var pdfBytes = await _pdfExporter.ExportAsync(
            html,
            "<div style='text-align: center;'>Order Report</div>", // Header
            "<div style='text-align: center;'>Page <span class='pageNumber'></span></div>" // Footer
        );
        
        return IdevsContentResult.Create(pdfBytes, IdevsContentType.Pdf, "report.pdf");
    }
}

UI Components

// Enhanced column attributes
public class OrderColumns
{
    [DisplayName("Order ID"), ColumnWidth(ExtraLarge = 2)]
    public string OrderId { get; set; }
    
    [DisplayName("Customer"), FullColumnWidth]
    public string CustomerName { get; set; }
    
    [DisplayName("Order Date"), DisplayDateFormat, HalfWidth]
    public DateTime OrderDate { get; set; }
    
    [DisplayName("Amount"), DisplayNumberFormat("n2")]
    public decimal Amount { get; set; }
    
    [DisplayName("Status"), CheckboxFormatter(TrueText = "Completed", FalseText = "Pending")]
    public bool IsCompleted { get; set; }
}

Service Registration with Attributes

Idevs.Net.CoreLib supports both legacy attributes and enhanced standard attributes for service registration:

Legacy Attributes (Backward Compatibility)

[ScopedRegistration]
public class OrderService : IOrderService
{
    // Your service implementation
}

[SingletonRegiatration]
public class CacheService : ICacheService
{
    // Singleton service
}

[TransientRegistration]
public class EmailService : IEmailService
{
    // Transient service
}

Standard Attributes (Enhanced Features)

// Basic usage - auto-discovers I{ClassName} interface
[Scoped]
public class OrderService : IOrderService
{
    // Scoped service implementation
}

// Explicit service type specification
[Singleton(ServiceType = typeof(ICacheService))]
public class CacheService : ICacheService, IDisposable
{
    // Singleton service with explicit interface
}

// Named registrations (Autofac only)
[Transient(ServiceKey = "smtp")]
public class SmtpEmailService : IEmailService
{
    // SMTP email implementation
}

[Transient(ServiceKey = "sendgrid")]
public class SendGridEmailService : IEmailService
{
    // SendGrid email implementation
}

// Self-registration without interface
[Scoped(AllowSelfRegistration = true)]
public class UtilityService
{
    public void DoWork() { }
}

Attribute Comparison

Static Service Resolution

For scenarios where dependency injection is not feasible (e.g., static methods, legacy code integration), you can use the StaticServiceLocator:

// Initialize in your Program.cs (automatic with Autofac)
var app = builder.Build();
app.UseIdevsStaticServiceLocator(); // Automatically detects Autofac or traditional DI

// Use in static methods or legacy code
public static class LegacyHelper
{
    public static void ProcessData()
    {
        // Resolve services statically
        var excelExporter = StaticServiceLocator.Resolve<IIdevsExcelExporter>();
        var pdfExporter = StaticServiceLocator.Resolve<IIdevsPdfExporter>();
        
        // Use try resolve for optional services
        var optionalService = StaticServiceLocator.TryResolve<IOptionalService>();
        if (optionalService != null)
        {
            // Use the service
        }
        
        // Use scoped resolution for per-request services
        using var scope = StaticServiceLocator.CreateScope();
        var scopedService = scope.ServiceProvider.GetService<IScopedService>();
    }
    
    public static void ProcessDataWithCaching()
    {
        // Cache singleton services for better performance
        var cachedService = StaticServiceLocator.ResolveSingleton<IMySingletonService>();
    }
}

Important: Use StaticServiceLocator sparingly and prefer proper dependency injection whenever possible.

Configuration Options

Excel Export Customization

// Custom theme
var request = new IdevsExportRequest
{
    TableTheme = TableTheme.TableStyleMedium15,
    CompanyName = "My Company",
    ReportName = "Sales Report",
    PageSize = new PageSize(PageSizes.A4, PageOrientations.Landscape)
};

PDF Export Options

// Custom page settings in your CSS
@page {
    size: A4;
    margin: 1in;
}

// Or use PuppeteerSharp options directly
var pdfOptions = new PdfOptions
{
    Format = PaperFormat.A4,
    MarginOptions = new MarginOptions
    {
        Top = "1in",
        Right = "1in",
        Bottom = "1in",
        Left = "1in"
    },
    PreferCSSPageSize = true
};

Troubleshooting

PDF Export Issues

Problem: PDF generation fails with "Chrome not found" error Solution: Ensure Chrome is downloaded:

// Check if Chrome is available
if (!ChromeHelper.IsChromeDownloaded())
{
    ChromeHelper.DownloadChrome();
}

Problem: PDF export hangs or times out Solution: Ensure your HTML doesn't have external dependencies that can't be loaded:

<style>
  /* Your styles here */
</style>

Excel Export Issues

Problem: Column formatting not applied Solution: Use proper format attributes:

[DisplayNumberFormat("#,##0.00")] // For numbers
[DisplayDateFormat] // For dates (dd/MM/yyyy)
[DisplayPercentage] // For percentages

Problem: Large datasets cause memory issues Solution: Process data in chunks or use streaming:

// Process in smaller batches
const int batchSize = 10000;
for (int i = 0; i < totalRecords; i += batchSize)
{
    var batch = GetDataBatch(i, batchSize);
    // Process batch
}

Migration Guide

From v0.1.x to v0.2.0 (Current)

Autofac Integration (Recommended)

1. Update to Autofac: Replace service collection registration with Autofac:

// Old way (v0.1.x)
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddIdevsCorelibServices();

// New way (v0.2.0) - Recommended
var builder = WebApplication.CreateBuilder(args);
builder.UseIdevsAutofac();

2. Legacy Support: If you cannot use Autofac, the old way still works:

// Still supported for backward compatibility
builder.Services.AddIdevsCorelibServices();

// Note: RegisterServices() is now obsolete
// builder.Services.RegisterServices(); // Remove this line

Benefits of Autofac Integration

• Better Performance: Autofac provides superior dependency resolution performance
• Advanced Features: Support for decorators, interceptors, and advanced lifetime scopes
• Module System: Organized service registration through modules
• Attribute-Based Registration: Automatic service discovery and registration

From v0.0.x to v0.1.x

1. Service Registration: Replace manual service registration with AddIdevsCorelibServices():

// Old way
services.AddScoped<IViewPageRenderer, ViewPageRenderer>();
services.AddScoped<IIdevsPdfExporter, IdevsPdfExporter>();
services.AddScoped<IIdevsExcelExporter, IdevsExcelExporter>();

// New way
services.AddIdevsCorelibServices();

2. Chrome Setup: Add Chrome download to startup:

// Add this to Program.cs
ChromeHelper.DownloadChrome();

3. Static Service Provider: Migrate to StaticServiceLocator (recommended):

// Old way (still works but obsolete)
StaticServiceProvider.Provider = app.ApplicationServices;
var service = StaticServiceProvider.GetService<IMyService>();

// New way (recommended)
var app = builder.Build();
app.UseIdevsStaticServiceLocator(); // Automatic initialization
var service = StaticServiceLocator.Resolve<IMyService>();

// Or manual initialization
// StaticServiceLocator.Initialize(app.Services);

StaticServiceLocator Benefits

• Autofac Support: Works seamlessly with both Autofac and traditional DI
• Thread Safety: Improved thread-safe operations
• Better Error Handling: More descriptive error messages
• Scoped Resolution: Support for creating service scopes
• Performance: Caching options for singleton services
• Backward Compatibility: Automatic fallback when using StaticServiceProvider

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• @klomkling - Sarawut Phaekuntod

Changelog

See CHANGELOG.md for a detailed history of changes.

Made with ❤️ for the Serenity Framework community