# ASP.NET Core

> Use the DocumentEditor, DocumentViewer, DocumentProcessing and Admin NuGet packages in ASP.NET Core: OAuthSettings, Razor view settings and C# methods.

- **Product:** DS Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** DS Server > Client-Side Libraries > ASP.NET Core
- **5385 words**
- **Web URL:** https://docs.textcontrol.com/ds-server/client-libraries/aspnet-core/
- **LLMs URL:** https://docs.textcontrol.com/ds-server/client-libraries/aspnet-core/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/ds-server/client-libraries/aspnet-core/llms-full.txt

---

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](https://docs.textcontrol.com/ds-server/getting-started/document-editor/aspnet-core/llms-full.txt), [Document Viewer](https://docs.textcontrol.com/ds-server/getting-started/document-viewer/aspnet-core/llms-full.txt) and [Document Processing](https://docs.textcontrol.com/ds-server/getting-started/document-processing/aspnet-core/llms-full.txt).

### Packages and Requirements

| Package | Version | Target frameworks | Dependencies |
|---|---|---|---|
| [TXTextControl.DocumentServices.DocumentEditor](https://www.nuget.org/packages/TXTextControl.DocumentServices.DocumentEditor/) | 5.0.0 | .NET 8, .NET 10 | `Microsoft.AspNetCore.Html.Abstractions`, `Microsoft.AspNetCore.Mvc.ViewFeatures`, `Microsoft.AspNetCore.WebUtilities`, `Newtonsoft.Json` |
| [TXTextControl.DocumentServices.DocumentViewer](https://www.nuget.org/packages/TXTextControl.DocumentServices.DocumentViewer/) | 5.0.0 | .NET 8, .NET 10 | The `Microsoft.AspNetCore.App` framework, `Newtonsoft.Json` |
| [TXTextControl.DocumentServices.DocumentProcessing](https://www.nuget.org/packages/TXTextControl.DocumentServices.DocumentProcessing/) | 5.0.0 | .NET 8, .NET 10 | The `Microsoft.AspNetCore.App` framework, `Newtonsoft.Json` |
| [TXTextControl.DocumentServices.Admin](https://www.nuget.org/packages/TXTextControl.DocumentServices.Admin/) | 5.0.0 | .NET 8, .NET 10 | None |

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](https://docs.textcontrol.com/ds-server/getting-started/trial-token/llms-full.txt).
- **A security profile** with a client ID and a client secret, created in the admin portal as [Creating Security Profiles](https://docs.textcontrol.com/ds-server/administration/security-profiles/llms-full.txt) 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:

```bash
dotnet add package TXTextControl.DocumentServices.DocumentEditor
```

### Authorization

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

| Property | Type | Description |
|---|---|---|
| `ClientId` | string | The client ID of the security profile |
| `ClientSecret` | string | The client secret of the security profile |
| `RedirectUri` | string | The OAuth redirect URI in your application that DS Server sends the authorization code to |

The packages provide the callback endpoint themselves. Register its address in the security profile under the authorized redirect URIs, as the [security profile table](https://docs.textcontrol.com/ds-server/administration/security-profiles/llms-full.txt) lists them:

| Package | Redirect URI to register |
|---|---|
| DocumentEditor | `https://your.app/textcontrol/documenteditor/auth/callback` |
| DocumentViewer | `https://your.app/textcontrol/documentviewer/auth/callback` |
| DocumentProcessing | `https://your.app/textcontrol/documentprocessing/auth/callback` |

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](https://docs.textcontrol.com/ds-server/client-libraries/overview/#authorize-a-library) 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*:

```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

| Property | Description |
|---|---|
| `Width` | The width of the editor as a CSS length, such as `"100%"` or `"20em"` |
| `Height` | The height of the editor as a CSS length |
| `Position` | The CSS position of the editor, a `CSSPosition` value |
| `ServiceUrl` | The URL of DS Server |
| `OAuthSettings` | Optional. The OAuth credentials, see [Authorization](#authorization) |
| `DocumentData` | The document to load, as a byte array. Text formats such as HTML or RTF must be UTF-8 |
| `DocumentFileFormat` | The format of `DocumentData`, a `StreamType` value |
| `JsonData` | The JSON data source that the **Reporting** tab offers as merge fields |
| `EditMode` | Whether the text can be edited or only read, an `EditMode` value |
| `Culture` | The culture of the editor, a `CultureInfo`; it affects formats such as dates and times |
| `UICulture` | The culture of the user interface, a `CultureInfo`; it selects the language of the strings |
| `FormattingPrinter` | The name of a printer whose text dimensions and capabilities are used to format the document |
| `ReconnectTimeout` | The time in seconds after which the editor stops trying to reconnect after the connection is lost |
| `UserNames` | The names of the users who may edit the editable regions assigned to them |
| `CustomQueryParams` | Custom query parameters |
| `WebSocketProtocols` | Additional WebSocket sub-protocols passed to every WebSocket the editor opens, for example for your own authentication |

#### Enumerations

`EditMode` sets what the user can do with the text:

| Value | Description |
|---|---|
| `Edit` | The text can be edited and formatted without restrictions |
| `ReadAndSelect` | The text is displayed and can be selected |
| `ReadOnly` | The text is displayed only and can't be selected |
| `UsePassword` | A dialog box asks for a password that protects the edit mode; combine it with `ReadAndSelect` using the bitwise OR operator |

`StreamType` names the format of `DocumentData`:

| Value | Format |
|---|---|
| `HTMLFormat` | HTML |
| `RichTextFormat` | RTF |
| `PlainText` | Unicode text; a paragraph ends with the control characters 13 and 10 |
| `InternalUnicodeFormat` | The TX Text Control format |
| `MSWord` | Microsoft Word, DOC |
| `XMLFormat` | XML |
| `AdobePDF` | PDF; only the text is imported |
| `WordprocessingML` | Microsoft Word, DOCX |
| `SpreadsheetML` | Microsoft Excel, XLSX |

`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](https://docs.textcontrol.com/ds-server/reference/javascript/txtextcontrol/llms-full.txt).

### 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:

```cshtml
@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

| Property | Description |
|---|---|
| `BasePath` | The URL of DS Server |
| `OAuthSettings` | The OAuth credentials, see [Authorization](#authorization) |
| `DocumentData` | The document to display, as a Base64-encoded string |
| `DocumentPath` | The document name the viewer displays |
| `DocumentLoadSettings` | How the document is loaded, a `DocumentLoadSettings` object: `LoadEmbeddedComments`, whether comments in the document are loaded as annotations (`true` by default), and `PDFJS`, the `WorkerSourcePath` and `LibrarySourcePath` of PDF.js |
| `Dock` | How the viewer is docked, a `DockStyle` value |
| `ToolbarDocked` | Whether the toolbar is docked |
| `IsSelectionActivated` | Whether text can be selected |
| `ShowThumbnailPane` | Whether the pane of page thumbnails is visible when the viewer opens |
| `View` | The device-specific view, a `ViewMode` value: `Mobile` or `Desktop` |
| `RenderMode` | How the pages are rendered, a `ComponentRenderMode` value: `Auto`, `Font`, `GlyphOutlines` or `Bitmap` |
| `FormattingPrinter` | The name of a printer whose text dimensions and capabilities are used to format the document |
| `UserNames` | The names of the users who have access to editable regions |
| `ResourceManager` | The resource manager for the strings of the viewer |
| `SignatureSettings` | The settings of a signature process, a `SignatureSettings` object |
| `CustomQueryParams` | Custom query parameters, a `Dictionary<string, string>` |

`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

| Property | Description |
|---|---|
| `ShowSignatureBar` | Whether the signature bar is shown |
| `OwnerName` | The name of the document owner |
| `SignerName` | The name of the signer |
| `SignerInitials` | The initials of the signer |
| `SignatureBoxes` | The boxes to sign, an array of `SignatureBox` objects |
| `SignatureBoxName` | Obsolete: the name of the signature box; use `SignatureBoxes` |
| `DefaultSignatureFont` | The default font of text-based signatures, a `SignatureFontSettings` object with the font `Family` |
| `UniqueId` | A unique ID of the document envelope |
| `RedirectUrlAfterSignature` | The URL the viewer redirects to after a successful signature |
| `CustomSigning` | Whether your own code handles the signing process |

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](https://docs.textcontrol.com/ds-server/reference/javascript-document-viewer/txdocumentviewer/llms-full.txt).

### 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:

```csharp
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

| Method | Web API endpoint | Returns |
|---|---|---|
| `Convert` | [POST /documentprocessing/document/convert](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-convert/post/llms-full.txt) | The document in another format |
| `Merge` | [POST /documentprocessing/document/merge](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-merge/post/llms-full.txt) | The documents merged from a template and JSON data, as an array of byte arrays. The overloads without the `append` argument send `append=false`, one document per record, while the Web API's default is `true` |
| `FindAndReplace` | [POST /documentprocessing/document/findandreplace](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-findandreplace/post/llms-full.txt) | The document with text replaced |
| `Append` | [POST /documentprocessing/document/append](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-append/post/llms-full.txt) | One document combined from several |
| `Thumbnails` | [POST /documentprocessing/document/thumbnails](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-thumbnails/post/llms-full.txt) | An image of each page, as PNG, JPG, BMP, GIF or SVG; the longest overload also sends `maxImageResolution`, 96 by default |
| `Info` | [POST /documentprocessing/document/info](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-info/post/llms-full.txt) | A `DocumentInfo` with the properties, merge fields and merge blocks of the document |
| `InstalledPrinters` | [GET /documentprocessing/document/installedprinters](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-installedprinters/get/llms-full.txt) | The printers installed on the DS Server machine, as `PrinterInfo` objects. In version 5.0.0, a failed request throws a plain `Exception` without a status code |
| `PDF.Create` | [POST /documentprocessing/pdf/create](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/pdf-create/post/llms-full.txt) | A PDF or PDF/A document |
| `PDF.GetEmbeddedFiles` | [POST /documentprocessing/pdf/embeddedfiles](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/pdf-embeddedfiles/post/llms-full.txt) | The files embedded in a PDF document |
| `PDF.GetMetaData` | [POST /documentprocessing/pdf/metadata](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/pdf-metadata/post/llms-full.txt) | The metadata of a PDF document |
| `PDF.AcroForms.GetFields` | [POST /documentprocessing/pdf/acroforms/fields](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/pdf-acroforms-fields/post/llms-full.txt) | The AcroForm fields of a PDF document |
| `Barcodes.Create` | [POST /documentprocessing/barcodes/create](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-create/post/llms-full.txt) | A barcode image of the text in a `BarcodeSettings` object, a QR code by default |
| `Barcodes.GetDefaultText` | [GET /documentprocessing/barcodes/defaulttext](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-defaulttext/get/llms-full.txt) | The default text of a barcode type |
| `Barcodes.GetMaximumTextLength`, `Barcodes.GetMinimumTextLength` | [GET /documentprocessing/barcodes/maximumtextlength](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-maximumtextlength/get/llms-full.txt), [GET /documentprocessing/barcodes/minimumtextlength](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-minimumtextlength/get/llms-full.txt) | The maximum or minimum text length of a barcode type |
| `Barcodes.IsTextValid` | [GET /documentprocessing/barcodes/istextvalid](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-istextvalid/get/llms-full.txt) | Whether a text is valid for a barcode type |

`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](https://docs.textcontrol.com/ds-server/reference/dotnet-api/llms-full.txt) 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:

| Method | Does |
|---|---|
| `GetSecurityProfileIds`, `GetSecurityProfile` | Return the IDs of all security profiles, or one profile by ID |
| `AddSecurityProfile`, `DeleteSecurityProfile` | Add a `SecurityProfile` and return its ID, or delete one by ID |
| `UpdateAllowClientCredentialsGrantType` | Allow or forbid the client credentials grant type for a profile |
| `UpdateExpiryDate` | Set the expiry date of a profile |
| `UpdateAuthorizedRedirectUris` | Set the authorized redirect URIs of a profile |
| `GetOAuthEnabled`, `SetOAuthEnabled` | Read or switch whether OAuth is enabled |
| `GetAuthenticationServerIds`, `GetAuthenticationServer`, `AddAuthenticationServer`, `DeleteAuthenticationServer`, `UpdateServerUrl` | Manage the authentication servers |
| `ChangeUserPassword` | Change the password of a user; the new password has at least eight characters |

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](https://docs.textcontrol.com/ds-server/reference/web-api/administration/llms-full.txt) endpoints of the Web API describe the requests behind the methods.

### Related Pages

- [Overview](https://docs.textcontrol.com/ds-server/client-libraries/overview/llms-full.txt): how the client libraries connect to DS Server and how to authorize them.
- [Getting Started](https://docs.textcontrol.com/ds-server/getting-started/llms-full.txt): the ASP.NET Core tutorials for the Document Editor, the Document Viewer and Document Processing.
- [Web API](https://docs.textcontrol.com/ds-server/reference/web-api/llms-full.txt): the endpoints the packages call.
- [.NET API](https://docs.textcontrol.com/ds-server/reference/dotnet-api/llms-full.txt): the namespaces and classes of the .NET packages.

---

## Nearby

- **Previous:** [Overview](https://docs.textcontrol.com/ds-server/client-libraries/overview/llms-full.txt)
- **Next:** [Angular](https://docs.textcontrol.com/ds-server/client-libraries/angular/llms-full.txt)