> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/framework/reporting.md).

# Reporting

Ability to organize report descriptions, template resources and data loading, and identify report contracts and specific engines.

`Zongsoft.Reporting` provides reports, description information, resources, data models and data loading contracts. Businesses can use this to manage template sources and data supplies separately, but the final rendering, export and design functions still rely on specific reporting engines.

## What Responsibilities Are Involved in Report Generation

| link                    | Problem solved                                      | Corresponding abstraction                          |
| ----------------------- | --------------------------------------------------- | -------------------------------------------------- |
| Identify template       | What is the report name, source and description?    | `IReportDescriptor`                                |
| Open resource           | Get template content from a file or other location  | Describe objects, resources and resource resolvers |
| Create report instance  | Load template with specific engine                  | `IReport` implemented by engine                    |
| Provide data            | Mapping report models to business queries           | `IReportDataLoader`、`IReportDataModel`             |
| Rendering and exporting | Generate output that can be displayed or downloaded | Specific reporting engine                          |

The resource resolver returns report resources and cannot be directly used as a report instance factory. There are save, render or export methods in the interface, which does not mean that each adapter has implemented the corresponding methods.

## Integration Data Service

The default `ReportDataLoader` parses the object from the service container according to the data model's `Name` and requires that the object is a data service; then uses the model's `Schema` to initiate a select query. Therefore, the report model name must correspond to the service alias registered by the business, and cannot just fill in the database table name.

First complete the registration and separate query verification of [Data Services](/documentation/en/framework/data/services.md), and then connect the report model. The authorization, filter and query constraints of the service are still in effect, and the business data scope should not be bypassed through the report entry.

{% hint style="warning" %}
🚨 The default loader uses `Paging.Page(1)` and will not automatically traverse all pages. Before exporting a full report, you need to clarify the paging strategy, row limit, and resource consumption, and implement a data loader suitable for the report; otherwise, you may only get the first page of data.
{% endhint %}

## Templates and Resources Lifecycle

The file description object can open the template stream, but opening the file only proves that the resource is readable, but does not prove that the template format is supported by the target engine. Template formats, fonts, images, and external data sources should be checked along with the deployment.

Resource flows should be released by a clear layer. In particular, check whether the engine will close the stream passed in by the caller when opening the template to avoid subsequent processing from continuing to read the released resources. Before caching a report instance, you should also confirm that the engine instance can be shared and used concurrently across requests.

The `Key` file description object is based on the path and runtime hash and should not be treated as a report number that is stable across processes and versions. The persistent directory should use a stable identity defined by the business itself.

## Current Implementation Scope

The current default implementation of `ReportDataLocator` does not complete data positioning. Before use, you need to check the methods you plan to call one by one, instead of arranging a complete export pipeline based on the package name only.

Deploying `Zongsoft.Reporting` does not automatically provide the designer or a working report download interface. The app also needs to select an engine, meet its running and licensing conditions, load templates, connect to data, and handle output and errors.

## Recommended Acceptance Sequence

1. Use a fixed small template to verify resource lookup and engine loading.
2. Validate fields, groupings, sorting, and data permissions with a small amount of known data.
3. Check cross-page data, Chinese fonts, time zones and numerical formats.
4. Verify the download results against the output format supported by the actual implementation, and record the number of pages and total amount of data.
5. Then test concurrency, timeout, temporary file cleanup and resource release after failure.

Spreadsheet data exchange does not necessarily require a reporting engine. Just see [Spreadsheet and Template Extensions](/documentation/en/framework/externals/documents.md) when importing and exporting workbooks.

Source references: [Report module](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Reporting), [Default data loading](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Reporting/src/ReportDataLoader.cs).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/framework/reporting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.