Zongsoft.Reporting 7.2.0

Zongsoft.Reporting Reporting Plugin Library

English | 简体中文

Overview

Zongsoft.Reporting is the reporting plugin library for the Zongsoft open-source framework. It provides the infrastructure required for report development.

This package defines provider-neutral contracts for locating report definitions, resolving a vendor format, loading data, binding parameters, rendering, exporting, storing resources, and archiving results. It does not include a complete report designer or rendering engine; a provider adapter must implement those format-specific operations.

Reporting Vocabulary

Rendering produces the report's presentation format; exporting produces a selected interchange/output format. Exact options and supported formats belong to the provider.

Installation

dotnet add package Zongsoft.Reporting

Also install a reporting provider that implements IReportResourceResolver and the concrete IReport. Register its locators and repository with the application service container.

Definition Example

Open a template asynchronously through a descriptor and dispose the stream after use:

var descriptor = new FileReportDescriptor("templates/sales.rdlx");
await using var stream = await descriptor.OpenAsync(cancellation);

This package does not bundle a ready-to-run report definition. Supply a trusted template supported by your chosen provider, then use that provider's opening API to obtain IReport. The actual definition determines its format, data sources, and parameters.

Descriptors open templates; IReportResourceResolver.ResolveAsync parses assets such as images. Only call rendering and export operations implemented by the selected provider.

💡 Keep business queries behind IReportDataLoader. A template should name a data model and parameters, not embed deployment credentials or unrestricted ad-hoc access.

Asynchronous Data Loading

Call await loader.LoadAsync(report, model, cancellation) to obtain data. The returned object can be an asynchronous query result; the report provider must consume it asynchronously before passing ready data to a rendering API that requires an in-memory collection.

The current GrapeCity adapter is incompatible with this version's asynchronous loading, location, and storage contracts and cannot be used with it.

Template and resource lookup, repository creation/update/deletion, and report saving use cancellable Async methods. IReportArchiveLocator.OpenAsync returns ReportArchiveResult: default means no archive; a missing file path can still yield valid Archive metadata; callers own a non-null Stream and dispose it with await using.

Lifecycle and Limits

Callers own streams they open or pass unless a concrete provider documents otherwise. Rendering can be CPU-, memory-, and I/O-intensive; bound input size, row count, paging, output size, fonts/images, and execution time. Use a background job for long reports.

🚨 Treat report templates as active, privileged input when a provider supports expressions or scripts. Only load trusted definitions, constrain file/resource resolution, parameterize data access, sanitize exported filenames, and authorize both the definition and its underlying data.

The built-in ReportDataLocator is only a service placeholder in the current implementation and does not select a loader. Applications must provide a working locator/loader or a provider package; do not assume installing this contract package enables data-bound reports by itself.

Related Resources

• Public reporting contracts
• Zongsoft.Data
• Implementation guidance

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

Service scanning registers the built-in data loader/locator. A concrete report engine and an application data service are still required; the current locator is incomplete, as noted above.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft reporting]
nuget:Zongsoft.Reporting

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Reporting.plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.