Developer Guide

Quick Start

Get ScreamCode.Reporting up and running in minutes. Works with any ASP.NET Core 8 application — fresh project or existing app.

Version 1.2.2 — always use the latest version. All versions before 1.2.1 have critical bugs and are deprecated on NuGet.

Prerequisites

.NET 8.0 SDK
Any ASP.NET Core 8 application (new or existing)
Windows, Linux, or macOS

1. Install packages

dotnet add package ScreamCode.Reporting.Core --version 1.2.2
dotnet add package ScreamCode.Reporting.Admin --version 1.2.2
dotnet add package ScreamCode.Reporting.Pdf --version 1.2.2
dotnet add package ScreamCode.Reporting.Excel --version 1.2.2
dotnet add package ScreamCode.Reporting.Builder --version 1.2.2
dotnet add package ScreamCode.Reporting.Templates --version 1.2.2
dotnet add package ScreamCode.Reporting.Audit --version 1.2.2

2. Program.cs

The setup is identical for all project types — fresh ASP.NET Core app, existing MVC, existing Blazor, anything.

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;
using ScreamCode.Reporting.Audit.Extensions;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddScreamReporting(builder.Configuration)
    .AddPdf()
    .AddExcel()
    .AddBuilder()
    .AddTemplates()
    .AddAdmin()
    .AddAuditTrail(options =>
        options.UseSqlite("Data Source=reporting-audit.db"))
    .AddDataProvider<YourDataProvider>();

var app = builder.Build();

await app.Services.InitializeScreamReportingAsync();
await app.Services.EnsureAuditDatabaseAsync();
await app.Services.EnsureAdminDatabaseAsync(); // auto-creates Pages/_AdminHost.cshtml

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

// If your app does NOT already call MapBlazorHub() or MapRazorComponents():
app.MapBlazorHub();

app.UseScreamReportingAdmin();

app.Run();

If your app already calls MapBlazorHub() or MapRazorComponents(), skip the explicit app.MapBlazorHub() line — it is already registered.

3. Pages/_AdminHost.cshtml — created automatically

On first run, EnsureAdminDatabaseAsync() automatically creates Pages/_AdminHost.cshtml in your project directory. You will see this message in the console:

[ScreamCode.Reporting] Created Pages/_AdminHost.cshtml — please restart.

Restart the application once after first run. The portal will work from that point forward with no further changes.

The generated file looks like this:

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

Static files (admin.css, admin.js, chart.umd.min.js, screamreporting.js) and localization files are embedded in the Admin package — no manual copying needed.

4. appsettings.json

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

5. Implement IReportDataProvider

A data provider connects ScreamCode.Reporting to your application data.

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.ToString(),
            ["CustomerName"] = o.CustomerName,
            ["Total"] = (object?)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 generation)

cd publish
$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 →