Developer Guide

Quick Start

Get ScreamCode.Reporting up and running in under 5 minutes.

Prerequisites

.NET 8.0 SDK
ASP.NET Core web application
Windows (for PDF generation via Chromium)

1. Install packages

dotnet add package ScreamCode.Reporting.Core
dotnet add package ScreamCode.Reporting.Admin
dotnet add package ScreamCode.Reporting.Pdf
dotnet add package ScreamCode.Reporting.Excel
dotnet add package ScreamCode.Reporting.Builder
dotnet add package ScreamCode.Reporting.Templates

2. Configure Program.cs

using ScreamCode.Reporting.Core.Extensions;
using ScreamCode.Reporting.Admin.Extensions;
using ScreamCode.Reporting.Pdf.Extensions;
using ScreamCode.Reporting.Excel.Extensions;
using ScreamCode.Reporting.Builder.Extensions;
using ScreamCode.Reporting.Templates.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddSignalR(options =>
{
    options.MaximumReceiveMessageSize = 10 * 1024 * 1024;
});

builder.Services
    .AddScreamReporting(builder.Configuration)
    .AddPdf()
    .AddExcel()
    .AddBuilder()
    .AddTemplates()
    .AddAdmin()
    .AddDataProvider<YourDataProvider>();

var app = builder.Build();

await app.Services.InitializeScreamReportingAsync();
await app.Services.EnsureAdminDatabaseAsync();

app.UseStaticFiles();
app.UseAntiforgery();
app.MapBlazorHub();

var adminPath = builder.Configuration["ScreamReporting:AdminPath"] ?? "reportadmin";
app.MapFallbackToPage($"/{adminPath}/{{**path}}", "/_Host");
app.MapFallbackToPage($"/{adminPath}", "/_Host");

app.Run();

3. Add _Host.cshtml

Create Pages/_Host.cshtml:

@page "/reportadmin/{**path}"
@namespace YourApp.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Reporting Admin</title>
    <base href="/" />
    <link rel="stylesheet" href="/admin.css" />
</head>
<body>
    <component type="typeof(YourApp.App)" render-mode="Server" />
    <script src="_framework/blazor.server.js"></script>
    <script src="/admin.js"></script>
    <script src="/screamreporting.js"></script>
</body>
</html>

4. Add appsettings.json

{
  "ScreamReporting": {
    "LicenseKey": "",
    "ApplicationName": "YourApp",
    "AdminPath": "reportadmin",
    "AdminAuth": {
      "Enabled": true,
      "Username": "admin",
      "Password": "your-secure-password"
    }
  }
}

5. Implement IReportDataProvider

public class OrdersDataProvider : IReportDataProvider
{
    private readonly AppDbContext _db;
    public OrdersDataProvider(AppDbContext db) => _db = db;

    public string EntityName => "orders";
    public string DisplayName => "Orders";

    public IReadOnlyList<ReportColumnDefinition> AvailableColumns =>
    [
        new() { Name = "Id", DisplayName = "Order ID", Type = "string" },
        new() { Name = "CustomerName", DisplayName = "Customer", Type = "string" },
        new() { Name = "Total", DisplayName = "Total", Type = "decimal" },
        new() { Name = "CreatedAt", DisplayName = "Date", Type = "datetime" }
    ];

    public IReadOnlyList<ReportFilterDefinition> AvailableFilters =>
    [
        new() { Name = "CreatedAt", DisplayName = "Date Range", Type = "daterange" },
        new() { Name = "CustomerName", DisplayName = "Customer", Type = "string" }
    ];

    public async Task<ReportTable> GetDataAsync(ReportBuilderRequest request, CancellationToken ct = default)
    {
        var query = _db.Orders.AsQueryable();
        if (request.Filters?.TryGetValue("CustomerName", out var name) == true)
            query = query.Where(o => o.CustomerName.Contains(name));

        var data = await query.Select(o => new Dictionary<string, object?>
        {
            ["Id"] = o.Id,
            ["CustomerName"] = o.CustomerName,
            ["Total"] = o.Total,
            ["CreatedAt"] = o.CreatedAt
        }).ToListAsync(ct);

        return new ReportTable { Columns = AvailableColumns.ToList(), Rows = data };
    }

    public async Task<int> GetCountAsync(ReportBuilderRequest request, CancellationToken ct = default)
        => await _db.Orders.CountAsync(ct);
}

6. Install Chromium (for PDF)

$env:NODE_SKIP_PLATFORM_CHECK = "1"
powershell -ExecutionPolicy Bypass -File playwright.ps1 install chromium

7. Open the portal

Navigate to https://yourapp.com/reportadmin and sign in with your configured credentials.

Next: Configuration

Configuration →