Skip to content

PdfAPI.Core operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/. The library exposes thirteen behaviour-bearing operations, all static members of PdfAPI.Core.PdfClientService, plus document lifecycle operations on PdfAPI.Core.Document and parsing operations on PageRange/PdfTrackingMetadata. No operation delegates into a referenced library other than iTextSharp and the BCL; none reads or writes a database, so no SQL IDs or tables apply to any step.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules Tables SQL
Validate PDF bytes Guard that a byte array is a valid PDF before further processing ValidatePdf(byte[], string) called PDF bytes, optional file name Passes silently, or throws PdfException BR-01, BR-02, BR-03 — —
Validate a document Guard that a Document loads and contains valid PDF bytes ValidatePdf(Document, PdfOptions) called Document, PdfOptions Passes silently, source file possibly deleted, or throws PdfException BR-04, BR-05, BR-06, BR-07 — —
Test whether bytes are a PDF Report whether a byte array carries a PDF signature IsPdf(byte[]) called PDF bytes true / false BR-01, BR-02 — —
Read PDF version Extract the PDF version token from the document header Version(byte[]) called PDF bytes Version string or "" BR-01, BR-08 — —
Count pages Estimate the page count by scanning raw PDF markup GetPageCount(byte[]) called PDF bytes Integer page count BR-01, BR-09 — —
Detect form fields Report whether a PDF carries fillable AcroForm fields HasFormFields(byte[]) called PDF bytes true / false BR-01, BR-10 — —
Flatten form fields Bake AcroForm field values into page content, removing interactivity Flatten(byte[]) called PDF bytes Flattened bytes, or original bytes unchanged BR-01, BR-11 — —
Extract pages Produce a new PDF containing only the selected page ranges ExtractPages(DocumentRange) / ExtractPageRanges(PdfReader, DocumentRange) called DocumentRange (Document + PageRange[]) PdfResult wrapping a new Document BR-01, BR-12, BR-13, BR-14, BR-15, BR-16, BR-17, BR-18 — —
Load a document Materialise a Document's bytes from memory or disk Document.Load(string, bool) / Document.Load(byte[], string) / Document.CreateEmpty(string) called File path, or bytes + extension Loaded/created Document, or false/exception BR-05, BR-19, BR-20, BR-21 — —
Persist and remove a document Write a document to disk, or remove its backing file Document.Save(string) / Document.Delete() / Document.Dispose() called Destination directory, or none File written, or file removed / true/false BR-22, BR-23, BR-24 — —
Parse a page expression Convert a page expression string into an array of PageRange PageRange.Parse(string) called Page expression (e.g., "1-5,7,9-*,*") Array of PageRange BR-25, BR-26, BR-27, BR-28, BR-29, BR-30 — —
Create tracking metadata Compose a file-name tracking prefix encoding conversion and imaging intent PdfTrackingMetadata.Create(Guid, string, PdfConversionType, bool) called File id, application code, conversion type, imaging flag Populated PdfTrackingMetadata with FilePrefix BR-31, BR-32, BR-33, BR-34 — —
Parse tracking metadata Decode a file-name tracking prefix back into structured metadata PdfTrackingMetadata.Parse(string) called Tracking prefix string Populated PdfTrackingMetadata, or null BR-35, BR-36, BR-37 — —

Process flow diagram

The following diagram visualizes the primary operational flow: guard, then inspect/transform/extract.

flowchart TD
    Start([Caller invokes PdfClientService]) --> Guard["IsPdf / ValidatePdf<br>(BR-01, BR-02, BR-03)"]
    Guard -->|Invalid| Fail([Throws PdfException])
    Guard -->|Valid| Kind{"Which operation?"}
    Kind -->|Inspect| Inspect["Version / GetPageCount /<br>HasFormFields"]
    Kind -->|Transform| Transform["Flatten"]
    Kind -->|Extract| Extract["ExtractPages /<br>ExtractPageRanges"]
    Inspect --> Done([Return value])
    Transform --> Done
    Extract --> Result(["PdfResult: Succeeded"])

Failure and edge-case behavior

  • A null or non-PDF byte array causes ValidatePdf to throw PdfException (BR-03); other inspection operations (IsPdf) return false rather than throwing.
  • ValidatePdf(Document, PdfOptions) deletes the input file before checking the PDF signature, so a document that fails validation has already lost its on-disk copy (BR-07).
  • A page range wholly beyond the document end is silently skipped rather than raising an error (BR-12); a page-expression token that does not match the grammar is silently dropped (BR-26).
  • Document.Delete() swallows all exceptions and reports false rather than propagating a failure (BR-23).
  • PdfTrackingMetadata.Parse always returns ShouldBeImaged = false and ConversionType = Convert, regardless of the encoded prefix, due to a capture-group name mismatch (BR-37).

Sources

  • PdfAPI.Core\Services\PdfClientService.cs
  • PdfAPI.Core\Document.cs
  • PdfAPI.Core\Extract\DocumentRange.cs
  • PdfAPI.Core\Extract\PageRange.cs
  • PdfAPI.Core\PdfTrackingMetadata.cs