Setup in .NET Standard / Core

Using Your LicenseActivate and apply your Doconut license.

Startup.cs file

Within the Startup.cs file of a .NET Core project, these lines of code define a middleware pipeline configuration using the MapWhen method. The provided predicate checks if the incoming request path ends with DocImage.axd. Inside this block, the UseDoconut method is called with a DoconutOptions object as an argument.

Startup.cs
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    appBranch =>
    {
        appBranch.UseDoconut(new DoconutOptions { UnsafeMode = false, ShowDoconutInfo = false });
    }
);

Add Doconut Namespaces

In your project, add the following using statements:

Usings
using Doconut;
using Doconut.Configs;
using Doconut.Clouds;

// TODO: implement licence loading, viewer registration, document opening, conversion using current API

Instantiate Viewer object

This line instantiates a new instance of the Viewer class, allowing you to create a viewer object within your code.

Instantiation
// Viewer is injected; no explicit construction required in Doconut.NETStandard 26.9.0

Setup a DocOptions object

Example initialization of a DocOptions object with specific configurations:

DocOptions
var documentOptions = new DocOptions
{
    Password = "",
    // ImageResolution is obsolete; omitted.
    TimeOut = 30
};

Setup a config object

Initialize a new PdfConfig object with specific configurations for handling PDF documents:

PdfConfig
var config = new PdfConfig { DefaultRender = true, ExtractHyperlinks = true };

Open your document

This line invokes the OpenDocument method of the viewer object, passing the path of the document file located on the server and the previously configured PdfConfig and DocOptions objects as parameters.

OpenDocument
dynamic viewer = null;
var token = viewer.LoadDocument(path, null, null);

Add the viewer in your HTML

HTML
<div id="div_ctlDoc"></div>

Add CSS and JavaScript files

Add the following CSS and JavaScript files in the page. These scripts are included in the ZIP file with code samples.

HTML Headers
<link rel="stylesheet" href="css/viewer.css" />

<!-- Main Viewer Related Scripts -->
<script src="scripts/jquery.min.js"></script>
<script src="scripts/docViewer.js"></script>
<script src="scripts/splitter.js"></script>
<script src="scripts/search.js"></script>
<script src="scripts/documentLinks.js"></script>

<!-- Viewer functions -->
<script src="scripts/docViewer.UI.js?v=1"></script>

Add Licenses to Your Project

Automatic License Detection

To initialize the docViewer with automatic license detection, use the following line:

C#
```csharp
// Create a Viewer instance using the current API (no constructor arguments required).
var docViewer = new Viewer();
```

Add Manual Default License

You can manually specify the path to a single default license file when initializing the viewer.

C#
using System.IO;
using Microsoft.Extensions.DependencyInjection;
using Doconut;

var licenseFilePath = Path.Combine(builder.Environment.WebRootPath, "path/to/your/license");
var docViewer = app.Services.GetRequiredService<Viewer>();

Add License by Stream

This method uses the Viewer.DoconutLicense(Stream licenseStream) overload to add a license using a stream.

C#
using System.IO;
using Doconut.Infrastructure.Licensing;

using (var licenseStream = new FileStream("path/to/your/license", FileMode.Open, FileAccess.Read))
{
    var license = new DoconutLicense { DocBytes = new BinaryReader(licenseStream).ReadBytes((int)licenseStream.Length) };
}

Add License by XML Document

This method uses the Viewer.DoconutLicense(XMLDocument licence) overload to add a license using an XML document.

C#
using System.Xml;
using Doconut.Infrastructure.Licensing;

var xmlDoc = new XmlDocument(); // load the license XML
xmlDoc.Load("path/to/your/license.xml");
var license = new DoconutLicense(); // instantiate license object (populate properties as needed)

Manual Default Multiple Plugin Licenses

If you need to specify multiple licenses, you can provide a list of file paths to the viewer initialization.

C#
```csharp
// Prepare the paths to the viewer licence files (kept for reference; the current API loads them automatically)
var licenseFilePaths = new List<string>
{
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.lic"),
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.Annotation.lic"),
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.Search.lic")
};

// The Viewer class no longer requires the licences in its constructor.
// Create an instance with the default constructor.
var docViewer = new Viewer();

// Open a document (e.g., a PDF) and obtain a token that represents the opened file.
string token = await docViewer.OpenDocumentAsync(
    filePath: Path.Combine(_hostingEnvironment.WebRootPath, "sample.pdf"),
    options: new DocOptions(),
    ct: CancellationToken.None);
```

Add Plugin License by Stream

This method uses the Viewer.SetLicensePlugin(Stream pluginLicence) overload to add a plugin license using a stream.

C#
using (var pluginLicenseStream = new FileStream("path/to/your/plugin-license.lic", FileMode.Open))
{
    // In Doconut.NETStandard 26.9.0 the license is supplied via the configuration
    // passed to OpenDocumentAsync (BaseConfig), so the explicit SetLicensePlugin call
    // is no longer required. Keep the license file accessible to the viewer or
    // include it in your BaseConfig as shown in other samples.
}

Add Plugin License by XML Document

This method uses the Viewer.SetLicensePlugin(XMLDocument xmlPluginLicence) overload to add a plugin license using an XML document.

C#
// The license XML is discovered automatically by the viewer in Doconut.NETStandard 26.9.0.
// No explicit API call is required to register it.

string token = await Viewer.OpenDocumentAsync(
    "path/to/your/document.pdf",
    null, // DocOptions – use default settings
    CancellationToken.None);

Required NuGet Packages

To ensure your project is fully compatible with .NET Core Standard, the following NuGet packages need to be included, listed in alphabetical order.

  • MessagePack - Version 2.5.140
  • Microsoft.Bcl.AsyncInterfaces - Version 8.0.0
  • Microsoft.Extensions.Caching.Abstractions - Version 8.0.0
  • Microsoft.Extensions.Configuration - Version 8.0.0
  • Microsoft.Extensions.Configuration.Abstractions - Version 8.0.0
  • Microsoft.Extensions.Configuration.FileExtensions - Version 8.0.0
  • Microsoft.Extensions.Configuration.Json - Version 8.0.0
  • Microsoft.Extensions.FileProviders.Abstractions - Version 8.0.0
  • Microsoft.Extensions.FileProviders.Physical - Version 8.0.0
  • Microsoft.Extensions.FileSystemGlobbing - Version 8.0.0
  • Microsoft.Extensions.Primitives - Version 8.0.0
  • System.Buffers - Version 4.5.1
  • System.Formats.Asn1 - Version 8.0.0
  • System.Numerics.Vectors - Version 4.5.0
  • System.Security.Cryptography.Cng - Version 5.0.0
  • System.Security.Cryptography.Pkcs - Version 8.0.0
  • System.Text.Encoding.CodePages - Version 8.0.0
  • System.Text.Encodings.Web - Version 8.0.0
  • System.Text.Json - Version 8.0.3
  • System.Threading.Tasks.Extensions - Version 4.5.4

Render Configuration Options

You can configure the rendering behavior using the following options:

  • CadConfig: Used for DWG, DXF, and DGN files.
  • EmailConfig: Used for EML, EMLX, and MSG files.
  • EpubConfig: Used for EPUB files.
  • ExcelConfig: Used for Excel and CSV files.
  • MhtConfig: Used for MHT files.
  • PptConfig: Used for PowerPoint files.
  • ProjectConfig: Used for MPP files.
  • PsdConfig: Used for PSD files.
  • TxtConfig: Used for TXT files.
  • TiffConfig: Used for TIFF files.

Render Options Configuration

The render options are configured using the DefaultRender property:

  • DefaultRender = true : This option offers higher quality rendering but uses more server memory and processing time.
  • DefaultRender = false : This option provides faster rendering at the expense of slightly reduced quality.

How To Add An Image Annotation

In C#

1. Open the document and get the dimensions of the first page. 2. Initialize the AnnotationManager with the page dimensions. 3. Create an ImageAnnotation, setting the image path in imgUrl, and specify the position and size within Rectangle. 4. Add the annotation to the manager and load it in the document viewer to display.

C#
using Doconut.Annotations;
using System.Drawing;

// Placeholder: open the document and obtain page dimensions using the current Doconut.NETStandard API.
// Placeholder: create an annotation manager for the page size.

string imgUrl = "img/sample.png";
var imgAnn = new ImageAnnotation(
    1,
    new Rectangle(600, 700, 750, 300),
    imgUrl
);

// Placeholder: add the annotation to the manager and load the annotation XML back into the viewer using the current API.

In JavaScript

1. Ensure YourController is available. 2. Create a new ImageAnnotation, setting the image path with SetNote. 3. Add and paint the annotation to render it on the document.

JavaScript
function ImageStamp() {
    if (null != objctlDoc.YourController()) {
        var objStampImage = new ImageAnnotation({ left: 200, top: 200, width: 260, height: 55 });
        objctlDoc.YourController().AddAnnotation(null, objStampImage, null);

        objStampImage.SetNote('/images/Approved_Stamp.png');
        objStampImage.Paint();
    }
}

Custom Fonts in Word documents

The FontFolders property in the WordConfig class specifies custom directories where the application will search for fonts. This is particularly useful for processing Word documents that rely on fonts not installed in the system's default font directories.

Usage
var config = new WordConfig
{
    FontFolders = new string[] { "C:\\CustomFonts", "D:\\SharedFonts" }
};

Important Update for Doconut 25.2.0

It is essential to update the System.Text.Json package to version 8.0.5 in all your projects. This update is crucial to ensure compatibility with the latest features and to address important security improvements.

Email Encoding

The EmailEncoding property in the EmailConfig class specifies the preferred encoding for both the email's subject and body.

Usage
var emailConfig = new EmailConfig {
    EmailEncoding = Encoding.UTF8 // Set preferred email encoding
};

Subject & Body Encoding

The SubjectEncoding and BodyEncoding properties in the EmailConfig class define the encoding used for the subject and body of an email, respectively.

Usage
var emailConfig = new EmailConfig {
    SubjectEncoding = Encoding.UTF8, // Set encoding for the subject
    BodyEncoding = Encoding.UTF8     // Set encoding for the body
};

Word Viewer Culture Support

The DocumentCulture property in the WordConfig class allows you to explicitly define the culture for DOC and DOCX files. This ensures that localized content—such as dates, currencies, and numbers—renders exactly as it does in Microsoft Word. This is particularly useful for languages with specific formatting requirements.

Usage
var config = new WordConfig { DocumentCulture = "he-IL" }; // Hebrew (Israel)
var config = new WordConfig { DocumentCulture = "ar-SA" }; // Arabic (Saudi Arabia)
var config = new WordConfig { DocumentCulture = "th-TH" }; // Thai (Thailand)
var config = new WordConfig { DocumentCulture = "ja-JP" }; // Japanese (Japan)