How to embed Beep.Reports in an application, supply data, extend it and test it. The report file model is in REPORT_DEFINITION_SCHEMA.md; architecture is in SDD-beep-reports.md.

1. Packages and hosts

Need Packages / projects
Model, validation, stores Beep.Reports.Model
Engine and renderers Beep.Reports.Engine plus Beep.Reports.Rendering.*
Expressions and scripts Beep.Reports.Expressions, optional Beep.Reports.Scripting.Roslyn
Desktop viewer Beep.Reports.Viewer.Core + Viewer.Wpf or Viewer.WinForms
Web viewer Beep.Reports.Viewer.Blazor
Designer Beep.Reports.Designer.Core, Designer.Skia + Designer.Wpf, Designer.WinForms or Designer.Blazor
Data adapters Beep.Reports.Data (in-memory/objects), Data.BeepDM, Integration.BeepDM

The host matrix is in HOST_PARITY.md and PACKAGING.md. dotnet new starter hosts are beepreports-wpf, beepreports-winforms and beepreports-web (see PACKAGING.md).

2. Minimal run

var providers = new PluginRegistry<IReportDataProvider>();
providers.Register(new InMemoryDataProvider().AddTable("sales", "orders", fields, rows));
var expressions = ExpressionEngine.CreateDefault();
var engine = new ReportEngine(new ReportEngineOptions
{
    Validator = DefinitionValidator.CreateDefault(new ExpressionEngineValidator(expressions)),
    Data = new ReportDataService(providers),
    Expressions = expressions,
    PageStoreFactory = () => new InMemoryPageStore(),
    Measurer = new SkiaTextMeasurer(fontResolver),
    ItemLayouters = BuiltInItemLayouters.CreateRegistry(),
    Reporter = reporter,                 // IOperationReporter: log + audit + UI
});
var outcome = await engine.RunAsync(definition, context, progress, cancellationToken);

Outcome<T> carries success, typed diagnostics (code, severity, JSON pointer) and a correlation id; never inspect exceptions for expected failures. See DIAGNOSTICS.md and OPERATIONAL_SERVICES.md.

3. Data

IReportDataProvider is the engine contract: catalog, schema and a forward-only IReportRowReader. Adapters and the capability rules are in DATA_ADAPTERS.md:

  • BeepDmReportDataProvider (beepdm) wraps a BeepDM IDataSource.
  • UnitOfWorkReportDataProvider (beepdm-uow) wraps IUnitOfWorkWrapper.
  • ObjectsDataProvider binds typed .NET objects ([ReportDataSource] / [ReportField]).
  • CapabilityAdaptingDataProvider applies filter/sort/top/distinct locally when a provider cannot push them down.
  • FederatedJoin and ReportDataService compose sources and relations.

4. Designer embedding

All hosts share Designer.Core and Designer.Skia; the host only renders descriptors and forwards input. See EXTENSIONS.md, HOST_PARITY.md and ADR-011.

var workspace = new DesignerWorkspace(localizer, culture, toolbox, editors, shell, commands)
{
    HostsDesignSurface = true,
};
workspace.Show(report);
workspace.ApplyPolicy(new DesignerPolicy
{
    AllowedItemTypes = new HashSet<string> { "label", "field", "table" },
    AllowedShellCommands = new HashSet<string> { "undo", "redo", "save" },
    AllowScripts = false,
});
  • DesignerWorkbenchHost gates every edit and command and raises DesignerEvent (Edited/Denied/CommandDenied).
  • DesignerPresentationBuilder builds the host-neutral workspace descriptor; add-in panes implement IDesignerPaneContribution.
  • DesignerLanguagePacks.CreateLocalizer(folder, culture) adds <culture>.json language packs.
  • Themes: DesignerThemes.CreateRegistry(); WPF uses WpfPaneTheming, WinForms PaneTheming, Blazor CSS variables.

5. Output

Every format is an IReportRenderer plug-in. The renderer matrix is OUTPUT_FORMATS.md; import/export of report definitions is REPORT_FORMATS.md. Always write to a temporary stream and commit on success.

6. Extension points

docs/EXTENSIONS.md has the complete table and tested samples: item, renderer, function, data provider, designer pane, wizard, menu command, property editor, drop handler, backend, policy, collaboration transport, language pack. A new plug-in registers in the owning IPluginRegistry<T>; it never edits the engine.

7. Localization

No hard-coded user-visible text. Use ILocalizer, @str:key, Tr(); persist culture-invariant values. Language packs, catalogues, RTL/digit substitution and the resolution chain are in LOCALIZATION.md.

8. Tests and conventions

  • Build: dotnet build Beep.Reports.slnx -c Release (warnings are errors).
  • Test: dotnet test Beep.Reports.slnx -c Release (net10.0).
  • Architecture rules: tests/Beep.Reports.Architecture.Tests; never swallow exceptions.
  • Sample data and reports: samples/; test evidence: evidence/.