Get started

1Install the package

In your web project's folder:

dotnet add package MarkupReporter

2Register MarkupReporter

Add MarkupReporter to Program.cs. The Designer is only added in Development; in every other environment your app just renders PDFs, and the Designer's pages don't exist.

builder.Services.AddMarkupReporter(builder.Configuration.GetSection("MarkupReporter"));
if (builder.Environment.IsDevelopment())
    builder.Services.AddMarkupReporterDesigner();

var app = builder.Build();

app.MapStaticAssets();   // or app.UseStaticFiles(): the Designer's files
if (app.Environment.IsDevelopment())
    app.MapMarkupReporterDesigner();   // at /markupreporter

Then tell it where to keep your report templates, in appsettings.json:

"MarkupReporter": {
  "TemplatesFolder": "Reports"
}

The folder is relative to your project. The Designer saves into it, and your app loads templates from it.

3Set up your project file

Add this to your .csproj. It stops saving a report from restarting your app while you work (dotnet watch and Hot Reload would otherwise see the new files), and it publishes the compiled templates with your app:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);Reports\**</DefaultItemExcludes>
</PropertyGroup>
<ItemGroup>
  <Content Include="Reports\*.html" CopyToPublishDirectory="PreserveNewest" Watch="false" />
</ItemGroup>

Only the .html files are needed at runtime. Keep the .mrx design files in source control so you can edit them later.

4Design your first report

Run your app and open https://localhost:<port>/markupreporter. The Designer only answers on your own machine, in Development.

1. Start from a template. Pick the invoice, sales report or account statement starter, or a blank page.
2. Add your data. In the Data panel, click Add dataset and paste a JSON sample of the data your app will pass in. Name the dataset after the property you'll pass, for example invoice. You can also connect a SQL Server query while designing (see the configuration reference).
3. Bind fields. Select a text box and click + next to a field to insert it. For a table, click + on a field of the list to add a column.
4. Preview. Click Preview PDF to see the real PDF, rendered exactly as production will render it.
5. Save. Click Save and name it invoice. This writes Reports/invoice.mrx (the design) and Reports/invoice.html (the template your app renders).

5Render the PDF in your code

Inject IReportBuilder and call BuildAsync with the template name and your data. The top-level property names must match the dataset names in the design. Matching ignores case, so your existing C# classes work as they are.

Minimal API

app.MapGet("/invoices/{id}.pdf", async (
    int id, IReportBuilder reports, InvoiceService invoices) =>
{
    var invoice = await invoices.GetAsync(id);
    var report = await reports.BuildAsync("invoice", new { invoice });
    return Results.File(report.Pdf, "application/pdf", report.FileName);
});

Razor Pages

public class InvoiceModel(IReportBuilder reports, InvoiceService invoices)
    : PageModel
{
    public async Task<IActionResult> OnGetPdfAsync(int id, CancellationToken ct)
    {
        var invoice = await invoices.GetAsync(id);
        var report = await reports.BuildAsync(
            "invoice", new { invoice }, cancellationToken: ct);
        return File(report.Pdf, "application/pdf", report.FileName);
    }
}

Link to it with asp-page="/Invoice" asp-page-handler="Pdf" asp-route-id="@invoice.Id".

MVC controller

public class InvoicesController(IReportBuilder reports, InvoiceService invoices)
    : Controller
{
    [HttpGet("invoices/{id}/pdf")]
    public async Task<IActionResult> Pdf(int id, CancellationToken ct)
    {
        var invoice = await invoices.GetAsync(id);
        var report = await reports.BuildAsync(
            "invoice", new { invoice }, cancellationToken: ct);
        return File(report.Pdf, "application/pdf", report.FileName);
    }
}

report.FileName comes from the design's output file name. To change the file name or the culture used for numbers, dates and currency for one render, pass new ReportRenderOptions { FileName = "INV-1042.pdf", Culture = "en-GB" } as the third argument.

6Add your licence key

Without a key, PDFs are watermarked in Development and refused in every other environment. Once you buy a licence, your key arrives by email. Keep it out of source control:

On your machine

dotnet user-secrets set "MarkupReporter:LicenseKey" "<your licence key>"

On a server

Set an environment variable called MarkupReporter__LicenseKey (two underscores), or use your secret store, such as Azure Key Vault. Restart the app after adding the key; the watermark goes away. Keys are checked offline, so nothing is ever sent to us.

7Go to production

• A browser on the server. MarkupReporter finds Microsoft Edge, then Google Chrome, then Chromium in their standard locations. On Windows Server, Edge is usually already there. Outside Development it never downloads a browser, so make sure one is installed, or set Browser:ExecutablePath.
• Your templates. The .html files in your templates folder are published with your app (step 3).
• Your licence key, set as above.
• Linux containers: install the browser's runtime libraries, or start from an image that includes Chromium. If the app runs as root, set Browser:NoSandbox to true; better still, run as a non-root user.

The Designer doesn't exist in production, and MarkupReporter never runs report SQL there: your app loads its own data and passes it in.

8Configuration reference

All settings live in the MarkupReporter section of your configuration. Only TemplatesFolder and LicenseKey are usually needed.

Designing against SQL Server

SQL is used only while designing, for the list of fields and preview rows. Use a read-only database login, and keep its connection string in user secrets:

"ConnectionStrings": {
  "ReportingReadOnly": "Server=...;Database=...;User Id=report_reader;..."
},
"MarkupReporter": {
  "Designer": {
    "Connections": { "Reporting": "ReportingReadOnly" }
  }
}

9Troubleshooting

Still stuck? In the Designer, Help → Report a problem prepares an email with your versions filled in, or write to support@markupreporter.com.