Developer guide and code examples

Start with a complete working example, then choose the integration for your app. All commands below run from the repository root. Examples contain fictional data. The libraries are consumed from this checkout; no NuGet/pub.dev release is implied.

Choose an integration

Core and HTTP SDK object naming differ: Core Render(template, object) uses camelCase properties. The .NET HTTP SDK ReportInput.FromObjects preserves names by default. JSON and Dart map keys are exact. Match template fields to your data.

Desktop application

For the complete local Studio in a dedicated window, use the Desktop guide. It includes native project open/save, the owned engine, persistent Library, exports and desktop launchers. The current packaged build is Linux x64 only.

Run the engine directly

Requirements: .NET SDK 10. The sample references Core through the Pdf project; it requires no running server, Microsoft Office or browser.

dotnet run --project examples/EngineQuickStart -c Release

Expected: seven files in artifacts/engine-quickstart, with Chair 42.25 and Desk 125.00: PDF from objects, PDF from JSON, HTML, and Excel/Word in both modes. The complete source below can also be used in your own .NET console project after adding a project reference to src/NextgenReports.Pdf/NextgenReports.Pdf.csproj.

<!-- quickstart-source -->

using System.Text.Json;
using NextgenReports.Core;
using NextgenReports.Pdf;

// Run from the repository root. No Studio, database or browser is required.
var outputDirectory = Path.GetFullPath(args.FirstOrDefault() ?? "artifacts/engine-quickstart");
Directory.CreateDirectory(outputDirectory);
var template = TemplateJson.Parse("""
{
  "version": 1, "title": "Equipment register",
  "page": {"margin": 36, "footer": "Page {page} / {pages}"},
  "parameters": {"company": {"type": "string", "required": true}},
  "blocks": [
    {"type": "text", "text": "{{parameters.company}}", "style": {"size": 18, "bold": true}},
    {"type": "table", "source": "items", "columns": [
      {"field": "name", "title": "Equipment", "weight": 3},
      {"field": "amount", "title": "Amount", "weight": 1, "format": "N2"}
    ]}
  ]
}
""");
var parameters = JsonSerializer.SerializeToElement(new { company = "Example company" });
var pdf = new PdfExporter();
var engine = new ReportEngine(pdf);

// Core converts C# property names to camelCase: Items -> items, Name -> name.
var data = new { Items = new[] { new { Name = "Chair", Amount = 42.25m }, new { Name = "Desk", Amount = 125m } } };
var document = engine.Render(template, data, parameters);
using (var output = File.Create(Path.Combine(outputDirectory, "objects.pdf")))
    pdf.Export(document, output);

// JSON uses exact keys. The same template works with this equivalent snapshot.
var jsonDocument = engine.Render(template,
    """{"items":[{"name":"Chair","amount":42.25},{"name":"Desk","amount":125}]}""", parameters);
using (var output = File.Create(Path.Combine(outputDirectory, "json.pdf")))
    pdf.Export(jsonDocument, output);
using (var output = File.Create(Path.Combine(outputDirectory, "report.html")))
    new HtmlExporter().Export(document, output);

// Reuse one calculated document for both Office modes and formats.
foreach (var format in new[] { "xlsx", "docx" })
foreach (var mode in new[] { "editable", "pages" })
{
    using var output = File.Create(Path.Combine(outputDirectory, $"report-{mode}.{format}"));
    new OfficeExporter().Export(document, output, new(Format: format, Mode: mode));
}
Console.WriteLine($"Created 7 files in {outputDirectory}; {document.Pages.Count} page(s), Chair 42.25 and Desk 125.00.");

TemplateJson.Parse rejects unknown fields; ReportEngine.Inspect(template) provides static diagnostics. Render validates parameters/data and calculates pages. Exporters consume the resulting ReportDocument. Catch ReportException for report validation failures and pass a CancellationToken to Render/Export for cancellation. Handle ordinary file/transport failures in your host as well. Core does not fetch connections automatically. Scripts require an explicitly configured runtime; see TypeScript events.

Call the HTTP API

Start Studio in another terminal:

dotnet run --project src/NextgenReports.Studio -c Release --urls http://127.0.0.1:5274

This complete local-mode request writes a PDF containing Hello from HTTP:

curl --fail-with-body http://127.0.0.1:5274/api/render \
  -H 'Content-Type: application/json' \
  --data '{"template":{"version":1,"blocks":[{"type":"text","text":"{{data.message}}"}]},"data":{"message":"Hello from HTTP"},"parameters":{}}' \
  --output artifacts/http-example.pdf

Create artifacts first if you did not run the quick start. Use the same request with /api/preview for layout JSON. Errors use HTTP 400 Problem Details; parameterErrors identifies invalid fields. With server accounts enabled, use session cookies, login and CSRF; the SDK examples handle that workflow. Remote hosting requires HTTPS. See server operations.

Use the .NET HTTP SDK

Reference src/NextgenReports.Client/NextgenReports.Client.csproj. This example uses exact lowercase JSON keys, so it has no naming-policy ambiguity:

using System.Text.Json;
using NextgenReports.Client;

using var client = ReportClient.Create(new Uri("http://127.0.0.1:5274/"));
using var template = JsonDocument.Parse("""
{"version":1,"blocks":[{"type":"text","text":"{{data.message}}"}]}
""");
var input = ReportInput.FromObjects(template.RootElement,
    new { message = "Hello from the .NET SDK" });
var session = await client.GetSessionAsync();
// If session.Enabled, call LoginAsync with your host-supplied credentials first.
var file = await client.ExportAsync(input, ReportFormat.Pdf);
await File.WriteAllBytesAsync("sdk-report.pdf", file.Content);

Use one client per user session. Catch ReportApiException for HTTP/validation errors; handle cancellation and transport errors separately. The client never replays failed POSTs. Full login, JSON, refresh, export and error examples: .NET and Blazor integration.

Embed the Blazor viewer

Run the complete host with dotnet run --project examples/BlazorDemo --urls http://127.0.0.1:5277. The source includes startup configuration, login, input creation and downloads. For your host, register a scoped client per circuit, enable Interactive Server and include the library stylesheet as described in the Blazor setup guide.

@using NextgenReports.Client
@using NextgenReports.Blazor
@inject ReportClient Client

<ReportViewer Client="Client" Input="input" />

@code {
    private ReportInput input = ReportInput.FromObjects(
        System.Text.Json.JsonSerializer.SerializeToElement(new {
            version = 1,
            blocks = new[] { new { type = "text", text = "{{data.message}}" } }
        }), new { message = "Hello from Blazor" });
}

Assign a new input after edits. Navigation reuses generated pages; Download regenerates from the successful input snapshot. Viewer accounts cannot submit new report generation requests. WebAssembly/Auto are not implemented here.

Use Flutter and Dart

Add the repository-local package as in Flutter setup. For Flutter Web, serve the app from Studio's origin; Uri.base.resolve('/') uses that origin. Native Dart hosts use an explicit HTTPS server URL.

import 'package:nextgen_reports/nextgen_reports.dart';

final client = ReportClient(Uri.base.resolve('/'));
final input = ReportInput({
  'version': 1,
  'blocks': [{'type': 'text', 'text': '{{data.message}}'}],
}, {'message': 'Hello from Flutter'});

// Place this widget in your page's build method.
// In server mode, complete client.login(...) before displaying it.
final viewer = ReportViewer(client: client, input: input,
  onDownload: (file) async {
    // Integrate your app's save/share flow with file.content and file.fileName.
    // Complete browser implementation: examples/flutter_demo/lib/save_file_web.dart.
  });

// HTTP-only generation (inside an async function):
// final pdf = await client.export(input, ReportFormat.pdf);
// client.close(); // When the owner of the client is disposed.

The download callback above marks the host integration point; it does not save files by itself. The runnable Web demo includes the complete Blob download flow. Objects need toJson(); dates need explicit JSON conversion. Assign new input snapshots after edits and close the client when finished. Full code covers login, refresh, cancellation, errors, export options and platform limits in the Flutter setup guide. Android/iOS devices and native desktop GUI remain unverified.

Connect SQL, JSON files and application objects

Direct JSON/C# objects require no catalog. For external refresh, the host supplies source IDs, queries, connection environment variables or callbacks; the report stores bindings and a saved data snapshot. Supported providers: PostgreSQL, SQL Server, MySQL, MariaDB and SQLite, plus JSON files and .NET object callbacks.

[
  {
    "id": "sales",
    "label": "Sales",
    "provider": "postgresql",
    "connectionEnvironment": "REPORTS_DATABASE",
    "query": "SELECT id, region, amount FROM orders WHERE region=@region ORDER BY id",
    "parameters": {
      "region": {
        "type": "string"
      }
    }
  }
]

Save this host catalog outside the report and set NEXTGEN_DATA_SOURCES to its absolute path; set REPORTS_DATABASE in the host environment. Create the orders table/data in your own database. In Studio Connections choose sales, target items, empty array path, and bind source region to a string report parameter. Refresh, inspect and Apply snapshot before generating. No refresh occurs implicitly. See data sources for all five provider configurations, JSON file and object callback code, expected sample totals, limits and SQL Server's current live-verification limitation. Never put connection secrets in report parameters.

Export modes and expected results

Editable Office does not preserve original typed numbers/formulas or native Office charts. Exact pages supports page range and DPI. See Office export and page image export for API/CLI examples and limits.

Read and copy code examples

Code blocks use local syntax highlighting for C#, Dart, TypeScript, JSON, Razor markup and shell commands. Different colors identify keywords, strings, numbers, comments, types and properties. Select Copy code above a block to copy its original source without formatting. Highlighting works without an external CDN; JavaScript must be enabled. Razor examples highlight markup; embedded C# expressions may use the default text color.