在 .NET 6 或更高版本中设置

Startup.cs 文件

在 .NET Core 项目的 Startup.cs 文件中，这些代码行使用 MapWhen 方法定义了中间件管道配置。提供的谓词检查传入的请求路径是否以 DocImage.axd 结尾。在此块中，调用 UseDoconut 方法，并传入一个 DoconutOptions 对象作为参数。

Startup.cs

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

添加 Doconut 命名空间

在你的项目中，添加以下 using 语句：

添加 Doconut 命名空间

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

实例化 Viewer 对象

此行实例化 Viewer 类的新实例，使你能够在代码中创建一个 viewer 对象。

实例化 Viewer 对象

// License is configured via AddDoconut; obtain the viewer from DI.
var docViewer = app.Services.GetRequiredService<Viewer>();

设置 DocOptions 对象

使用特定配置初始化 DocOptions 对象的示例：

DocOptions

```csharp
// Document opening options – password and session timeout
var docOptions = new DocOptions
{
    Password = string.Empty,
    TimeOut = 30
};

// Per‑format rendering options – set image resolution via the format‑specific config
var pdfConfig = new PdfConfig
{
    ImageResolution = 200
};
```

设置 config 对象

使用特定配置初始化新的 PdfConfig 对象，以处理 PDF 文档：

PdfConfig

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

打开文档

此行调用 viewer 对象的 OpenDocument 方法，传入位于服务器上的文档文件路径以及先前配置的 PdfConfig 和 DocOptions 对象作为参数。

OpenDocument

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

在 HTML 中添加 viewer

HTML

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

添加 CSS 和 JavaScript 文件

在页面中添加以下 CSS 和 JavaScript 文件。这些脚本包含在带有代码示例的 ZIP 文件中。

添加 CSS 和 JavaScript 文件

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

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

向项目添加许可证

自动许可证检测

要使用自动许可证检测初始化 docViewer，请使用以下代码行：

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // The token is opaque — hand it to the widget, never log or persist it.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

添加手动默认许可证

在初始化 viewer 时，你可以手动指定单个默认许可证文件的路径。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

通过流添加许可证

此方法使用 Viewer.DoconutLicense(Stream licenseStream) 重载，通过流添加许可证。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

通过 XML 文档添加许可证

此方法使用 Viewer.DoconutLicense(XMLDocument licence) 重载，通过 XML 文档添加许可证。

// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

手动默认多个插件许可证

如果需要指定多个许可证，你可以在 viewer 初始化时提供文件路径列表。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state needs a cache (MVC/Razor Pages already add one)
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

通过流添加插件许可证

此方法使用 Viewer.SetLicensePlugin(Stream pluginLicence) 重载，通过流添加插件许可证。

using var pluginLicenseStream = new FileStream("path/to/your/plugin-license.lic", FileMode.Open);

builder.Services.AddDoconut(options =>
{
    // The stream takes precedence over LicenseContent, LicensePath, and auto‑search.
    options.LicenseStream = pluginLicenseStream;
});

通过 XML 文档添加插件许可证

此方法使用 Viewer.SetLicensePlugin(XMLDocument xmlPluginLicence) 重载，通过 XML 文档添加插件许可证。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

必需的 NuGet 包

为确保你的项目完全兼容 .NET Core Standard，需要包含以下 NuGet 包，按字母顺序列出。

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

渲染配置选项

你可以使用以下选项配置渲染行为：

CadConfig：用于 DWG、DXF 和 DGN 文件。
EmailConfig：用于 EML、EMLX 和 MSG 文件。
EpubConfig：用于 EPUB 文件。
ExcelConfig：用于 Excel 和 CSV 文件。
MhtConfig：用于 MHT 文件。
PptConfig：用于 PowerPoint 文件。
ProjectConfig：用于 MPP 文件。
PsdConfig：用于 PSD 文件。
TxtConfig：用于 TXT 文件。
TiffConfig：用于 TIFF 文件。

渲染选项配置

渲染选项使用 DefaultRender 属性进行配置：

DefaultRender = true：此选项提供更高质量的渲染，但会使用更多的服务器内存和处理时间。
DefaultRender = false：此选项提供更快的渲染速度，但质量会略有下降。

如何添加图像注释

在 C# 中

1. 打开文档并获取第一页的尺寸。 2. 使用页面尺寸初始化 AnnotationManager。 3. 创建 ImageAnnotation，在 imgUrl 中设置图像路径，并在 Rectangle 中指定位置和大小。 4. 将注释添加到管理器，并在文档查看器中加载以显示。

var token = await viewer.OpenDocumentAsync(pathToFile, config, documentOptions);

// The annotation manager is automatically bound to the opened document's page dimensions.
using var annMgr = viewer.GetAnnotationManager(token);

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

annMgr.Add(imgAnn);
viewer.LoadAnnotationData(token, annMgr);

在 JavaScript 中

1. 确保 YourController 可用。 2. 创建新的 ImageAnnotation，使用 SetNote 设置图像路径。 3. 添加并绘制注释，使其在文档上渲染。

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();
    }
}

Word 文档中的自定义字体

WordConfig 类中的 FontFolders 属性指定了应用程序搜索字体的自定义目录。这对于处理依赖于系统默认字体目录未安装的字体的 Word 文档特别有用。

Word 文档中的自定义字体

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

Doconut 25.2.0 的重要更新

在所有项目中将 System.Text.Json 包更新到 8.0.5 版是必需的。此更新对于确保兼容最新功能以及解决重要的安全改进至关重要。

电子邮件编码

EmailConfig 类中的 EmailEncoding 属性指定了电子邮件主题和正文的首选编码。

电子邮件编码

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

主题和正文编码

EmailConfig 类中的 SubjectEncoding 和 BodyEncoding 属性分别定义了电子邮件主题和正文使用的编码。

主题和正文编码

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

Word 查看器文化支持

DocumentCulture 属性在 WordConfig 类中允许您显式定义 DOC 和 DOCX 文件的文化。这确保本地化内容——如日期、货币和数字——的呈现方式与 Microsoft Word 完全一致。这对于具有特定格式要求的语言特别有用。

Word 查看器文化支持

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)