Skip to content

Report render lifecycle

Builds a report's xPression data XML (via the overridable Create) and renders it into document bytes through xPression, caching the rendered bytes so repeat calls avoid another round trip unless the caller requests an overwrite. This is the core rendering operation that Print and Save both depend on.

Field Value
Operation ID OP-06
Trigger Render invoked directly, or transitively via Print/Save
Inputs overwrite As Boolean = False, ReportPackage, OutputProfile, report XML from Create
Outputs Boolean success; populates ReportFile (private m_reportFile) as a side effect
Primary components ReportBase.Render, Create (overridable), clsSecurityPrincipal, clsPrint.previewDocument
Entry point Public Function Render(Optional overwrite As Boolean = False) As Boolean

Steps

  1. If a rendered file is already cached (m_reportFile is not Nothing) and the caller did not request overwrite, the operation skips re-rendering entirely — Create and xPression are not invoked again — and returns True immediately (BR-PRT-007).
  2. Otherwise (no cached file, or overwrite requested), calls the overridable Create(overwrite) to (re)build m_reportXml, which as a side effect clears m_Errors.
  3. Checks that m_reportXml is not Nothing and ReportPackage.Length > 0 before proceeding — a report can be rendered only when its XML document exists and a report package is assigned (BR-PRT-008).
  4. If the precondition fails: no rendering occurs, and the operation falls through to result = False (the initial default) without adding an entry to Errors — this differs from the exception-catch path in step 6.
  5. Resolves the default printer for the current clsSecurityPrincipal, selecting the Web platform when _environmentService.IsWeb is True and Windows otherwise, then sets xPrint.Printer to that value (BR-PRT-009).
  6. Calls xPrint.previewDocument(ReportPackage, m_reportXml.ToXpression, OutputProfile).

  7. The XML serialization consumed here is produced by ToXpression on the report's XDesignXDocument.

    Origin: The ToXpression serialization is implemented by Build xPression XML, which handles key propagation, XML escaping, and self-closing empty elements. - The preview call itself is the same operation documented as Preview a document, including its package-name normalization.

    Origin: The previewDocument call is implemented by Preview a document. 6. Assigns the returned bytes to m_reportFile and sets result = True. 7. If any exception occurs anywhere in steps 2–6, it is caught, appended to Errors as New ErrorDetail("An error occurred while rendering the report.", ex), and result remains False — the exception is never rethrown (BR-PRT-010).

Process flow

flowchart TD
    Start([Render called]) --> Cached{"reportFile set<br>AND not overwrite?"}
    Cached -->|Yes| Ok1(["Return True<br>(cached, BR-PRT-007)"])
    Cached -->|No| Create["Create() rebuilds XML"]
    Create --> Pre{"xml set AND<br>package set?"}
    Pre -->|No| Fail(["Return False<br>(no error added)"])
    Pre -->|Yes| Platform["Resolve platform<br>Web/Windows"]
    Platform --> DefPrinter["Get default printer"]
    DefPrinter --> Preview["previewDocument<br>(→OP-01, ToXpression→OP-11)"]
    Preview --> Store["Store ReportFile"]
    Store --> Ok2(["Return True"])
    Create -.->|exception anywhere| Err["Add ErrorDetail"]
    Pre -.->|exception anywhere| Err
    Platform -.->|exception anywhere| Err
    Preview -.->|exception anywhere| Err
    Err --> Fail2(["Return False"])

Failure and edge-case behavior

  • Exceptions never propagate out of Render; callers must inspect Errors rather than rely on a thrown exception (BR-PRT-010).
  • The precondition-failure path (step 3) is distinct from the exception-catch path (step 7): a failed precondition produces False silently with no ErrorDetail added, whereas an exception during rendering does add one. A caller inspecting only Errors could miss a precondition failure.
  • xPrint (via the IReport.xPrint read-only property) lazily constructs clsPrint with its parameterless constructor (New clsPrint()), which internally resolves AppGlobal.EnvironmentService rather than propagating ReportBase's own _environmentService — this directly affects the printer resolution performed in step 4.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • SAIF.Services.Printing/Reporting/ReportBase.vb
  • SAIF.Services.Printing/Reporting/IReport.vb