Skip to content

Execute a single conversion (converter template)

This operation is the template-method core shared by all eight format converters: it owns stream disposal, timing, exception capture, and PdfResult assembly, while delegating the actual byte-level conversion to the subclass's ConvertItem hook.

Field Value
Operation ID OP-SFC-002
Trigger Called by Convert a source document to PDF
Inputs Source Stream, ConvertRequest
Outputs PdfResult
Primary components BaseConverter.Convert
Entry point PdfApi.SyncFusionCore\Convert\BaseConverter.cs

Steps

  1. Take ownership of the stream in a using block, guaranteeing disposal on every path.
  2. Call ConfigureConverter(request.Options) — the per-format configuration hook. All eight concrete converters implement this as an empty method, so the hook is currently inert.
  3. Create new PdfResult(ConversionType, request) and stamp PdfProcessorType = Syncfusion (BR-SFC-006).
  4. Start a Stopwatch.
  5. Call the subclass ConvertItem(stream, request) and wrap the returned bytes with Document.Load(bytes, "pdf") (PdfAPI.Core).
  6. The subclass hook is one of: Word document to PDF, Excel workbook to PDF, RTF document to PDF, Plain text to PDF, Raster image to PDF, TIFF to multi-page PDF, HTML to PDF, or PDF pass-through or PDF/A upgrade, depending on which converter constructed this BaseConverter instance.
  7. Set Status = Succeeded when Document?.File is non-null, otherwise Failed (BR-SFC-007); copy request.Options onto the result.
  8. If PDF pass-through or PDF/A upgrade returns null (no matching branch), this step marks the result Failed.
  9. Set OutputFormat to PdfA when request.Options.IsPdfa, otherwise Pdf (BR-SFC-008).
  10. Parse request.SourceSystemId with long.TryParse into result.ImageId; a non-numeric or null value yields 0 (BR-SFC-009).
  11. On any exception: record ex.Message in result.Message and set Status = Failed. No rethrow, no logging (BR-SFC-010).
  12. In finally, stop the stopwatch and store sw.Elapsed on the result; return the result.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start(["Convert called with<br>stream and ConvertRequest"]) --> Dispose["Take ownership of stream<br>in using block"]
    Dispose --> Configure["Call ConfigureConverter<br>currently a no-op hook"]
    Configure --> Init["Create PdfResult,<br>stamp Syncfusion processor"]
    Init --> StartTimer[Start Stopwatch]
    StartTimer --> Try{"ConvertItem throws?"}
    Try -->|No| WrapDoc["Wrap bytes with<br>Document.Load"]
    WrapDoc --> DocNull{"Document.File<br>non-null?"}
    DocNull -->|Yes| Succeed["Status = Succeeded"]
    DocNull -->|No| Fail1["Status = Failed"]
    Succeed --> SetFormat["Set OutputFormat<br>from Options.IsPdfa"]
    Fail1 --> SetFormat
    SetFormat --> ParseId["Parse SourceSystemId<br>to ImageId"]
    Try -->|Yes| Catch["Catch exception:<br>Status = Failed,<br>Message = ex.Message"]
    ParseId --> StopTimer["Stop Stopwatch,<br>store Elapsed"]
    Catch --> StopTimer
    StopTimer --> Result([Return PdfResult])

Failure and edge-case behavior

  • Every exception raised by ConvertItem is caught here; none of the eight format converters need their own exception handling to satisfy the caller's contract.
  • A converter that legitimately returns null bytes (only PDF pass-through or PDF/A upgrade, when neither branch applies) is treated the same as a failure, not as a distinct outcome.

Sources

  • PdfApi.SyncFusionCore\Convert\BaseConverter.cs