Developer guide
Embed, extend and test.
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 BeepDMIDataSource.UnitOfWorkReportDataProvider(beepdm-uow) wrapsIUnitOfWorkWrapper.ObjectsDataProviderbinds typed .NET objects ([ReportDataSource]/[ReportField]).CapabilityAdaptingDataProviderapplies filter/sort/top/distinct locally when a provider cannot push them down.FederatedJoinandReportDataServicecompose 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,
});
DesignerWorkbenchHostgates every edit and command and raisesDesignerEvent(Edited/Denied/CommandDenied).DesignerPresentationBuilderbuilds the host-neutral workspace descriptor; add-in panes implementIDesignerPaneContribution.DesignerLanguagePacks.CreateLocalizer(folder, culture)adds<culture>.jsonlanguage packs.- Themes:
DesignerThemes.CreateRegistry(); WPF usesWpfPaneTheming, WinFormsPaneTheming, 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/.