Просмотрщик
Основной класс просмотра документов
Viewer (namespace Doconut) является публичной точкой входа для открытия документов из MVC‑контроллеров, страниц Web Forms и обработчиков. Это временный сервис, составляемый DoconutHost.Initialize; получайте его там, где используете его:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() также работает после того, как DoconutHost.Initialize выполнен — он разрешает те же сервисы — что сохраняет совместимость кода, перенесённого из классического пакета. До Initialize он бросает InvalidOperationException.
Viewer не хранит состояние документа на каждый запрос и намеренно не реализует IDisposable: сеансы документов живут независимо от него, поэтому удаление Viewer никогда не закроет открытый документ (см. Как работает Viewer).
OpenDocumentAsync
Открывает документ и возвращает токен сеанса, который виджет использует для всех последующих запросов. Когда UnsafeMode является false (по умолчанию), токен предоставляется ASP.NET‑сессии текущего запроса — вызывайте его из запроса, имеющего состояние сессии (см. Сессии и безопасность).
| Перегрузка | Когда использовать |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Открытие с диска с автоматическим определением формата и конфигурацией по умолчанию для формата |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Необходимы параметры рендеринга для каждого формата (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Документ не является файлом на диске (загрузка, база данных, блоб). fileInfo должен иметь правильное расширение — оно определяет формат |
// Простое открытие
string token = await viewer.OpenDocumentAsync(path);
// С конфигурацией и параметрами для каждого формата
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Из загрузки (HttpPostedFileBase в MVC; HttpPostedFile в Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Исключения, которые следует обработать:
LicenseException— лицензия была найдена, но отклонена (сообщение содержит причину), либо формат требует возможности плагина, которую лицензия не предоставляет.FormatNotSupportedException— ни один просмотрщик не поддерживает расширение файла.InvalidDataException— содержимое повреждено или не соответствует его расширению.
OpenDocument (синхронный)
Для кода‑behind Web Forms и другого кода, который не использует асинхронные страницы:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Каждый возвращает токен и также сохраняет его в viewer.Token. fileName должен иметь правильное расширение. Эти обёртки безопасно вызывать из страницы Web Forms: путь открытия никогда не возобновляется в контексте запроса ASP.NET, поэтому ожидание не может привести к взаимной блокировке. То же самое не верно для каждого асинхронного API Doconut — см. раздел Web Forms в Плагин конвертера.
CloseDocument
void CloseDocument(string token)Удаляет сессию (сразу освобождая движок документа), удаляет грант токена из текущей ASP.NET‑сессии запроса и отзывает токен. Необязательно — скользящее истечение времени выполняет ту же очистку — но рекомендуется для больших документов.
Запросы сессии
| Элемент | Возвращает |
|---|---|
int GetPageCount(string token) | Общее количество страниц открытого документа |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Размер страницы по умолчанию при 100 % масштабе — координатное пространство для аннотаций, построенных в коде |
IReadOnlyList<string> GetWorksheetNames(string token) | Отрисованные листы таблицы в порядке книги; пусто для остальных документов |
Каждый бросает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.
ОпцииДокумента
Опции, независимые от формата, применяемые к каждому открытому документу (пространство имён Doconut):
| Тип | Свойство | По умолчанию | Описание |
|---|---|---|---|
string | Password | "" | Пароль для защищённых документов (автоматически копируется в конфигурацию формата). |
string | Watermark | "" | Текст пользовательского водяного знака, отрисовываемый на страницах — см. ниже. |
int | TimeOut | 60 | Скользящее истечение сессии, в минутах. |
string | BrowserId | "" | Веб‑фермы: браузер, к которому привязан подписанный билет. Установите его с помощью DoconutFarmBinding.EnsureBrowserId (см. Сеансы и безопасность). |
string | UserId | "" | Веб‑фермы: пользователь, к которому привязан билет, из DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Устарело. Вместо этого установите ImageResolution в конфигурацию формата. |
bool | IsSecured | true | Зарезервировано; не применяется. Управление доступом — DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Сохраняется для кода, перенесённого из классического пакета. Они не включают режим фермы — AddDoconutDistributed делает это. |
bool | EditMode | false | Зарезервировано для отдельно распространяемого редактора; оставьте false. |
Пользовательский водяной знак
DocOptions.Watermark принимает шесть полей, разделённых тильдами. Необязательный начальный ^ запрашивает расположение «по всем углам»:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Поле | Пример | Значение |
|---|---|---|
Leading ^ | ^ | Необязательное расположение по всем углам. Без него используется обычное размещение. |
| Text | Confidential | Текст, отрисовываемый на каждой странице. Не должен быть пустым. |
| Color | Red | Именованный цвет. |
| FontSize | 24 | Размер шрифта; недопустимый числовой ввод приводит к использованию значения по умолчанию. |
| FontName | Verdana | Семейство шрифтов. Должно быть установлено на сервере — в Windows Server меньше шрифтов, чем на настольном компьютере. |
| Opacity | 80 | От 0 до 255. Должно корректно парситься. |
| Angle | -45 | Поворот в градусах; недопустимый числовой ввод приводит к использованию значения по умолчанию. |
Парсер ожидает ровно шесть полей после необязательного ^. Неверное определение заменяется видимым текстом Invalid Watermark вместо того, чтобы бесшумно исчезнуть.
Решение о лицензии
| Состояние лицензии | Пользовательское значение предоставлено | Отрисованный результат |
|---|---|---|
| Действительная платная лицензия просмотра | Нет | Чистая страница |
| Действительная платная лицензия просмотра | Да | Пользовательский водяной знак |
| Активная временная/демо‑лицензия | Нет | Чистая страница |
| Активная временная/демо‑лицензия | Да | Пользовательский водяной знак |
| Отсутствующая, отклонённая, истёкшая, неверной версии или с недействительным доменом лицензия | Любое | Водяной знак оценки; пользовательское значение его не заменяет |
То же решение применяется к обслуживаемым страницам и к экспорту аннотаций. Пользовательский водяной знак — это функция лицензированного приложения, а не способ заменить водяной знак оценки.
API аннотаций
Загрузка и экспорт аннотаций на стороне сервера. Руководство доступно в Аннотации.
| Member | Purpose |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Менеджер, привязанный к размерам страниц открытой сессии |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Менеджер с явными размерами страниц |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Менеджер, независимый от сессии |
void LoadAnnotationData(string token, AnnotationManager manager) | Загружает аннотации, созданные на C#, в сессию |
void LoadAnnotationData(string token, string annotationData) | Загружает закодированный конверт, возвращённый AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Загружает аннотации из XML |
XmlDocument GetAnnotationXML(string token) | Экспортирует аннотации сессии в XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF с вшитыми аннотациями |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Один PNG на страницу, аннотации вшиты, записываются в directoryPath (создаётся, если отсутствует); возвращает количество записанных изображений |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP‑файл с PNG‑изображениями каждой страницы, вшитыми аннотациями |
Метаданные DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)В этом пакете он всегда возвращает null, а запрос метаданных виджета отвечает 501 Not Implemented: чтение тегов DICOM недоступно в .NET Framework. DICOM rendering — страницы, кадры и анимация — работают. См. Плагин DICOM.
Вспомогательные ресурсы — ReferenceCss / ReferenceScripts
Выводит теги <link> и <script> для ресурсов, которые модуль ресурсов обслуживает под DoconutOptions.ResourcesPath, в порядке зависимостей. Файлы функций, ограниченных лицензией (Search, Annotation), выводятся только когда лицензия их разрешает.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // состояние лицензии, для защиты ribbon init code
bool IsAnnotationEnabled { get; }CssConfig флаги: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ограничено поиском), IncludeAnnotationCss (ограничено аннотациями).
ScriptConfig флаги: IncludeJQuery (требуется всеми остальными), IncludeBootstrap, IncludeViewerScripts (ядро скриптов просмотрщика), IncludeSearchScripts и IncludeSearchBar (ограничено поиском), IncludeAnnotationScripts и IncludeAnnotationBar (ограничено аннотациями), EmitFeatureFlags (по умолчанию true: также записывает встроенный скрипт window.Doconut.features = { search, annotation, editor }; установите false при Content‑Security‑Policy, блокирующей встроенные скрипты).
Оба возвращают HTML: генерируйте их с помощью @Html.Raw(...) в MVC 5 (создавайте их в контроллере — представления не имеют @inject) или <%= %> в Web Forms. Быстрый старт показывает оба варианта.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Возвращает блок <script>, который инициализирует виджет в элементе с id elementId и отображает документ: docViewer({...}), построенный из ViewerConfig (по умолчанию: BasePath: '/', ResPath: 'doconut-res/images'), затем .View(token). Разместите его после скриптов просмотрщика. Сгенерированный скрипт не сохраняет ссылку на объект просмотрщика, поэтому страница со своей панелью инструментов должна инициализировать виджет вручную. См. КонфигурацияПросмотрщика.
Веб‑ферма
string? AccessToken хранит подписанный билет, выданный последним открытием при активном распределённом режиме, и UnsafeMode является false; на отдельном сервере он null. Отправьте его в виджет вместе с токеном: objViewer.View(token, accessToken).
Была ли эта страница полезной?