ASP.NET Core

Four NuGet packages connect a .NET application to DS Server. Two render the browser components in an ASP.NET Core MVC view, the Document Editor and the Document Viewer, and two call the Web API from C#: DocumentProcessing for documents and Admin for the administration of the server. Each package is listed below with its installation, its usage and the settings it accepts.

For a first application built step by step, follow the ASP.NET Core tutorials of Getting Started: Document Editor, Document Viewer and Document Processing.

Packages and Requirements

The packages are published on nuget.org, and each description says that version 5.0.0 is meant for DS Server 5.0.0. Besides the package, you need:

• A running DS Server that you can reach from the browser and from your server, or a trial token for the trial server https://trial.dsserver.io, described in Trial Token.
• A security profile with a client ID and a client secret, created in the admin portal as Creating Security Profiles shows. The Admin package needs the admin password instead.

Install a package with the .NET CLI in the folder of your project, or search for its name in the NuGet Package Manager of Visual Studio:

dotnet add package TXTextControl.DocumentServices.DocumentEditor

Authorization

The Document Editor and Document Viewer packages take the credentials of the security profile in OAuthSettings:

The packages provide the callback endpoint themselves. Register its address in the security profile under the authorized redirect URIs, as the security profile table lists them:

Replace https://your.app with the address of your application. With a trial token, leave out RedirectUri and set the service URL to https://trial.dsserver.io: the trial profile allows the client credentials grant type, which needs no redirect. Don't put the client secret into client-side code; in a Razor view, it stays on the server. Overview compares the ways of getting a token.

Document Editor

TXTextControl.DocumentServices.DocumentEditor renders the Document Editor, a word processor in the browser, from a Razor view. The editor's script and its document processing come from DS Server.

Usage

Add the editor to a view, such as Views/Home/Index.cshtml:

@using TXTextControl.DocumentServices.DocumentEditor

@Html.TXTextControl().DocumentEditor(settings => {
    settings.Width = "1000px";
    settings.Height = "600px";
    settings.ServiceUrl = "https://ds.example.com";
    settings.OAuthSettings.ClientId = "<client ID>";
    settings.OAuthSettings.ClientSecret = "<client secret>";
    settings.OAuthSettings.RedirectUri = "https://your.app/textcontrol/documenteditor/auth/callback";
}).Render()

The code works as follows:

• Html.TXTextControl() is the extension method of the package's HtmlHelperExtension class, and DocumentEditor creates the editor with the settings of the lambda expression.
• ServiceUrl is the address of your DS Server, the same one the browser uses.
• Render writes the HTML of the editor into the view. RenderAsync does the same asynchronously.

DocumentEditorSettings Properties

Enumerations

EditMode sets what the user can do with the text:

StreamType names the format of DocumentData:

CSSPosition has the values of the CSS position property: Static, Relative, Absolute, Fixed and Sticky. When Position isn't set, the package renders the editor's container with position:relative.

Once the editor is on the page, the browser controls it through the TXTextControl object of the Document Editor JavaScript API.

Document Viewer

TXTextControl.DocumentServices.DocumentViewer renders the Document Viewer, which displays documents, lets users annotate them and collects signatures.

Usage

Add the viewer to a view:

@using TXTextControl.DocumentServices.DocumentViewer

@await Html.TXTextControl().DocumentViewer(settings => {
    settings.DocumentData = "SGVsbG8gdGhlcmU=";
    settings.Dock = DocumentViewerSettings.DockStyle.Fill;
    settings.IsSelectionActivated = true;
    settings.ShowThumbnailPane = true;
    settings.BasePath = "https://ds.example.com";
    settings.OAuthSettings.ClientId = "<client ID>";
    settings.OAuthSettings.ClientSecret = "<client secret>";
    settings.OAuthSettings.RedirectUri = "https://your.app/textcontrol/documentviewer/auth/callback";
}).RenderAsync()

The viewer's URL of DS Server is BasePath, not ServiceUrl. DocumentData holds the document as a Base64-encoded string; the example shows the text "Hello there".

DocumentViewerSettings Properties

DockStyle, nested in DocumentViewerSettings, has two values: Window fills the browser window, and Fill, the default, docks the viewer to all edges of its container.

SignatureSettings Properties

A SignatureBox takes the name of the signature field in its constructor, such as new SignatureBox("txsign"), and has SigningRequired and a Style, SignatureBox.SignatureBoxStyle.Signature or SignatureBox.SignatureBoxStyle.Initials.

Once the viewer is on the page, the browser controls it through the TXDocumentViewer object of the Document Viewer JavaScript API.

DocumentProcessing

TXTextControl.DocumentServices.DocumentProcessing sends documents to the DocumentProcessing Web API and returns the results as byte arrays. It has no user interface and runs in any .NET 8 or .NET 10 application.

Usage

A controller action that converts a document to PDF:

using Microsoft.AspNetCore.Mvc;
using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

public class ConvertController : Controller
{
    public async Task<IActionResult> Index()
    {
        // Credentials of the security profile
        var oauthSettings = new OAuthSettings(
            "<client ID>",
            "<client secret>",
            "https://your.app/textcontrol/documentprocessing/auth/callback");

        var documentProcessing = new DocumentProcessing("https://ds.example.com", oauthSettings);

        byte[] document = await System.IO.File.ReadAllBytesAsync("App_Data/sample.docx");
        byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF);

        return File(pdf, "application/pdf", "sample.pdf");
    }
}

The code works as follows:

• OAuthSettings takes the client ID, the client secret and the redirect URI. With a trial token, pass only the client ID and the secret.
• The DocumentProcessing constructor takes the URL of DS Server and the OAuth settings. When OAuth is disabled on the server, the URL alone is enough. Use the constructor: in version 5.0.0 of the package, DocumentProcessing.CreateInstanceAsync requests an access token but doesn't send it with the requests that follow, so they fail with 401 when OAuth is enabled.
• Convert sends the document to DS Server and returns it in the format of the ReturnFormat value. An overload takes a third argument, flattenFormFields.

DocumentProcessing Methods

ReturnFormat has the values PDF, PDFA, DOC, DOCX, RTF, TX, TXT and HTML. RefreshAccessToken requests a new access token with the refresh token, which only the authorization code flow issues; with the client credentials grant type, it throws an exception. OAuthInfo returns the OAuth information in use, such as the GrantType and ExpiresIn, or null when OAuth isn't used. .NET API lists the classes of the package.

Admin

TXTextControl.DocumentServices.Admin calls the administration endpoints of DS Server, so that you can automate what the admin otherwise does in the admin portal. Its Admin class takes the URL of DS Server and the password of the admin user:

A SecurityProfile takes its name in the constructor, such as new SecurityProfile("My App"), and has an ID, a Name, a CreationDate, an optional ExpiryDate, AllowClientCredentialsGrantType and optional ClientCredentials, which hold the client ID, the Secret and the AuthorizedRedirectUris. A failed request throws a ServiceRequestException with the HTTP StatusCode. The Administration endpoints of the Web API describe the requests behind the methods.

Related Pages

• Overview: how the client libraries connect to DS Server and how to authorize them.
• Getting Started: the ASP.NET Core tutorials for the Document Editor, the Document Viewer and Document Processing.
• Web API: the endpoints the packages call.
• .NET API: the namespaces and classes of the .NET packages.