TX Text Control .NET Server

Architecture

Topic

Deploying the Document Viewer, hosting it next to the Document Editor or connecting a separate frontend all depend on how the viewer works at runtime: which parts run in the browser and on your server, how a document reaches the browser, how PDF documents are displayed and how the endpoints of the backend are protected.

Product Architecture gives the overview of all components; this page goes into the details of the viewer.

The Parts of the Viewer

The viewer consists of a frontend in the browser and a backend in your ASP.NET Core application:

Browser: tx-document-viewer web component, TXDocumentViewer object
        |
        |  HTTP requests to /TextControl
        v
Your ASP.NET Core application: TextControl controller
(package TXTextControl.Web.DocumentViewer or TXTextControl.Web.DocumentViewer.Classic)
        |
        |  in the same process
        v
TX Text Control engine: Core or Classic
  • The frontend is a web component with the element name tx-document-viewer. Each instance has its own encapsulated markup and styles, so a page can contain several viewers. The HTML helper of ASP.NET Core and the plain JavaScript setup create this component. The Angular and React components load the same viewer script from the backend and initialize the viewer in an element of their own. All of them share the JavaScript API, the TXDocumentViewer object.
  • The backend is a controller named TextControl that the viewer package adds to your application. Every request of the viewer goes to it, including the viewer's own scripts, which it serves at /TextControl/GetResource.
  • The engine loads the document and renders its pages in the process of your application. The viewer needs no separate backend process and no WebSocket connection, unlike the Document Editor.

How the backend is added depends on the application:

ApplicationWhat it needs
ASP.NET Core MVCNothing beyond the packages: the controller routing of the template is enough, as the ASP.NET Core tutorial shows
ASP.NET Core Web API for Angular, React or JavaScriptapp.UseTXDocumentViewer() in Program.cs and a CORS policy, as the Angular tutorial shows in "Configure Program.cs"
Blazor Web AppRegistered controllers and app.UseTXDocumentViewer(); the blog article Getting Started: Document Viewer for Blazor in ASP.NET Core shows the setup

A separate frontend sets its basePath to the URL of the backend, for example https://localhost:7275. Because frontend and backend run on different origins, the backend must allow cross-origin requests.

How a Document Reaches the Browser

  1. The page with the viewer loads, and the viewer component initializes. The pages of the document are loaded asynchronously afterward, so the viewer doesn't delay the loading of your page.
  2. The backend loads the document, from a file set with DocumentPath, from data set with DocumentData or from data that loadDocument sends at run time. Loading Documents describes the three ways.
  3. The engine renders the pages. Since version 32.0 SP3, the viewer loads documents with long polling: the server keeps the request open and streams the pages as it generates them. Users read and annotate the first pages while the rest of a long document is still processed. In the developer tools of the browser, these requests appear as fetch requests.

The blog article Document Viewer: Long Polling Support for Loading Documents shows this with a document of 196 pages.

Render Modes

The engine renders pages in one of four ways, set with DocumentViewerSettings.RenderMode, a value of ComponentRenderMode. The mode decides how sharp the pages look when users zoom in:

ValueRenders pages asNotes
AutoThe format and method the viewer chooses to balance performance and appearance; the defaultRecommended for most applications
BitmapImagesCan be less sharp when users zoom in; small text looks smooth at lower screen resolutions, such as Full HD
GlyphOutlinesVector graphics, with the text drawn from the outlines of its glyphs, so no fonts are needed on the clientSuits high screen resolutions such as 4K; small elements can be hard to read when scaled down
FontVector graphics with embedded text, drawn with the fonts available on the clientRequires the fonts of the document on the user's computer

The responses of Font are the smallest and those of Bitmap the largest. The following settings render all pages as vector graphics:

@Html.TXTextControl().DocumentViewer(settings => {
    settings.DocumentPath = "App_Data/template.docx";
    settings.Dock = DocumentViewerSettings.DockStyle.Fill;
    settings.RenderMode = ComponentRenderMode.GlyphOutlines;
}).Render()

The blog article Document Viewer: Setting the Rendering Mode compares the modes.

How PDF Documents Are Displayed

TX Text Control has no PDF renderer of its own. By default, the engine imports a PDF document and converts its content into a document of its own, which can look different from the original; for displaying PDF documents exactly as they are, the viewer can use PDF.js, the PDF renderer of Mozilla, in the browser instead. Load PDF Documents With PDF.js compares both and shows the settings.

Protect the Endpoints

Every request of the viewer goes to the TextControl controller, so protect its endpoints: the view passes an access token in the query string of BasePath, the base URL at which the viewer calls the controller, and a middleware registered before app.UseTXDocumentViewer() rejects requests without a valid token. Access Tokens shows the middleware and how the token is issued and passed from each frontend.

Engines

The backend uses the engine of the packages you install: TXTextControl.Web.DocumentViewer with TXTextControl.TextControl.Core.SDK for the Core engine on Windows and Linux, or TXTextControl.Web.DocumentViewer.Classic with TXTextControl.TextControl.ASP.SDK for the Classic engine on Windows. The Core engine doesn't load DOC documents, and it loads RTF documents since version 34.0. Supported File Formats lists the formats of each engine.

The Viewer and the Document Editor in One View

Both components can run in the same application and even in the same view: the viewer sends HTTP requests to its controller, while the editor keeps a WebSocket connection to its middleware and the separate backend process described in Architecture of the Document Editor. Because both packages define an Html.TXTextControl() helper, a view that uses both creates the viewer in code; Show the Editor and the Viewer in One View in the Integration Guide shows such a view.

Next Steps