Плагін Конвертера
Конвертуйте документи у 45 цільових форматів
Плагін Converter перетворює Doconut у сервіс конвертації документів. Він забезпечує движок, що стоїть за публічним фасадом DocumentConverter і — за бажанням — віджетом, який надає DocImage.axd, тож ви можете конвертувати документи з C#, з віджета або з фронтенду, який створите самі.
| Середовище | Коли використовувати |
|---|---|
DocumentConverter (C#) | Ви конвертуєте на сервері, без браузера |
Drop-in widget (doconutConverter.js) | Вам потрібен готовий екран завантаження, конвертації та завантаження у вашій сторінці |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | Ви створюєте власний інтерфейс конвертації, використовуючи задокументований серверний контракт |
Встановити пакет
Install-Package Doconut.NETFramework.ConverterЩоб закріпити плагін за випуском, описаним у цій документації:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Тримайте пакет Converter тієї ж версії, що і Doconut.NETFramework.
Файл ліцензії плагіна, Doconut.Viewer.Converter.lic, розташовується в тій же папці, що і Doconut.Viewer.lic; він читається разом з ліцензією переглядача.
Зареєструвати плагін
Кожен плагін реєструється однаково: AddPlugin<TPlugin>() у DoconutHost.Initialize, викликається з Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Це все, що потрібно фасаду C#. Віджет і його HTTP‑кінцеві точки — це окрема опція, AddConverterWidget() (див. Вбудований віджет).
Плагіну потрібна ліцензія, що надає можливість Converter. Без неї DoconutHost.Initialize генерує виключення з Application_Start:
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.У System.Web це означає, що кожен запит повертає порожній 500, а причина зазначена лише у журналі подій Windows (джерело ASP.NET). Виключення виникає через відсутність ліцензії, застарілий файл TRIAL, ліцензію без Converter, або платну ліцензію, використану поза її часовим вікном. Тимчасові ліцензії Demo/NFR приймаються. Див. Налаштування ліцензії.
Ліцензування та водяний знак
| Стан ліцензії | Запуск | Результат конвертації |
|---|---|---|
Платна ліцензія переглядача, що надає Converter, у межах її версійного вікна | Запускається | Чистий — watermarked: false |
| Активна тимчасова (Demo/NFR) ліцензія | Запускається | Конвертує, з водяним знаком оцінки — watermarked: true |
| Протермінована тимчасова (Demo/NFR) ліцензія | Запускається | Конвертує, з водяним знаком оцінки — watermarked: true |
Відсутня ліцензія, застарілий файл TRIAL, ліцензія без Converter, або платна ліцензія поза її версійним вікном | Application_Start генерує виключення; кожен запит повертає порожній 500 | — |
Фасад DocumentConverter та обробник ?convert=run віджета застосовують те ж саме правило. Інтеграцію можна створити та протестувати від початку до кінця на ліцензії оцінки перед покупкою — змінюються лише байти вихідного результату.
Джерело DICOM (.dcm, .ima) також потребує можливості Dicom. Без неї ConvertAsync генерує LicenseException (Converting '.dcm' requires the Dicom capability license.), а відповідач віджета open повертає 403.
Використання з C#
Кожна конвертація повертає придатний до пошуку MemoryStream, розташований на позиції 0. DocumentConverter без стану: отримуйте його з DoconutHost.Services там, де потрібно, і вільно повторно використовуйте.
// Отримайте DocumentConverter з DoconutHost.Services; його конструктор internal, тому ніколи не `new` його.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension включає початкову крапку. password дорівнює null, якщо документ не захищений.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: Stream, що містить HTML, який треба перетворити назад у документ Word, наприклад результат WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Дві деталі, які легко помилитися: sourceExtension у перевантаженні потоку має містити початкову крапку (".xlsx", а не "xlsx"), інакше він не розпізнається. І, незважаючи на назву, WordToHtmlAsync повертає Task<Stream>, а не Task<string> — HTML‑документ (зображення вбудовані у Base64) надходить як потік, як і будь‑який інший результат.
Викликаючий володіє MemoryStream, який повертає конвертація, і повинен його звільнити після копіювання або повернення (MVC‑овий File(stream, …) звільняє його за вас). Не створюйте і не звільняйте DocumentConverter самостійно — його конструктор внутрішній.
У контролері MVC 5
Зробіть дію асинхронною і await конверсію:
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
Stream pdf = await converter.ConvertAsync(
file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
password: null, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}У Web Forms: ніколи не блокуйте конверсію
Сторінка Web Forms працює в однопоточному контексті запиту. ConvertAsync відновлюється в цьому контексті, коли завершується, тому сторінка, яка чекає на неї синхронно — .Result, .Wait(), .GetAwaiter().GetResult() — займає саме той потік, який потрібен конверсії для завершення. Запит ніколи не повертається. Браузер продовжує крутитися, IIS нічого не записує, а решта сайту працює, тому це виглядає як повільна конверсія, а не блокування.
Позначте сторінку Async="true" і запустіть конверсію як асинхронне завдання сторінки:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: директива @Page потребує Async="true", і конвертація виконується як асинхронне завдання сторінки.
// Блокування його замість цього (.Result, .Wait(), .GetAwaiter().GetResult()) призводить до взаємної блокування запиту:
// він ніколи не повертається, і нічого не записується в журнал.
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack) return;
RegisterAsyncTask(new PageAsyncTask(async ct =>
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
using (var pdf = await converter.ConvertAsync(
Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
using (var ms = new MemoryStream())
{
if (pdf.CanSeek) pdf.Position = 0;
await pdf.CopyToAsync(ms);
Response.ContentType = "application/pdf";
Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
Response.BinaryWrite(ms.ToArray());
// Context, а не HttpContext.Current: після await останнє може бути null.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Без Async="true" у директиві @Page, RegisterAsyncTask тихо ігнорується. Після await використовуйте Context сторінки; HttpContext.Current може бути null там.
Цільові формати
ConversionTarget (простір імен Doconut.Configs.Conversion) має 45 членів:
Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, IcoНе кожне джерело конвертується у кожну ціль: кожна сімейство форматів джерела (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, веб‑документ, DICOM) має власний набір дозволених цілей. Конвертація DICOM‑джерела (.dcm, .ima) також потребує ліцензії, яка надає можливість Dicom; його цілі — Pdf, Png, Jpeg, Bmp, Tiff і Gif. Не жорстко кодуйте цей enum у список цілей вашого інтерфейсу: ?convert=open повертає allowedTargets для завантаженого файлу, і саме це має керувати вибором.
Вбудований віджет
Увімкнення кінцевих точок
Кінцеві точки ?convert=open|run|download віджета обслуговуються DocImage.axd і вимкнені за замовчуванням. Увімкніть їх поруч із реєстрацією плагіна:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});
// System.Web читає весь завантажений файл до того, як Doconut його побачить: залиште maxRequestLength (KB) і
// maxAllowedContentLength (bytes) у Web.config вище значення MaxUploadMb віджета.AddConverterWidget() без аргументу увімкне віджет з налаштуваннями за замовчуванням (MaxUploadMb = 25). Він сам по собі не надає прав на конверсію: потрібен AddPlugin<ConverterPlugin>(), інакше DoconutHost.Initialize викидає:
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.Дві речі, які слід перевірити, коли віджет поводиться неправильно:
basePath: '/DocImage.axd'. За замовчуванням віджета,/doconut, є кінцева точка ASP.NET Core. У цьому пакеті кінцеві точки — це обробникDocImage.axdзWeb.config.- Скрипт і кінцеві точки незалежні. Ресурсний модуль обслуговує
doconutConverter.jsнезалежно від того, чи увімкнено віджет. БезAddConverterWidget()віджет завантажується, малює свою зону перетягування і виглядає цілком правильно — а його перша дія відповідає404.
Обмеження завантаження
ASP.NET читає весь тіло запиту перед тим, як запускається DocImage.axd. Завантаження вище MaxUploadMb, але нижче обмежень хоста, отримує власний JSON 413 від віджета (File is too large.). Завантаження вище обмежень хоста спочатку відхиляється IIS, з помилковою сторінкою, яку віджет не може прочитати. Тримайте обидва обмеження хоста в Web.config вище межі віджета:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- КІЛОБАЙТИ: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- БАЙТИ: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Вбудуйте це
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', maxUploadMb: 25 });
</script>Doconut.convert(selectorOrElement, options) приймає CSS‑селектор або елемент, викидає помилку, якщо монтування не знайдено, і повертає дескриптор. Віджет завантажує файл, показує попередній перегляд сторінки 1, дозволяє користувачеві вибрати один із allowedTargets, конвертує, попередньо переглядає результат, коли це можливо, і пропонує завантаження.
Параметри
| Параметр | Тип | За замовчуванням | Примітки |
|---|---|---|---|
basePath | string | /doconut | URL кінцевої точки. Встановіть '/DocImage.axd' у цьому пакеті |
resPath | string | /doconut-res | Прийнято для узгодженості з іншими віджетами Doconut; віджет конвертера не створює жодного URL з нього |
maxUploadMb | number | 25 | Лише передперевірка на клієнті; сервер застосовує власне обмеження |
licenseUrl | string | null | null | Перетворює повідомлення про водяний знак на екрані результату у посилання |
labels | object | {} | Перезаписує будь-яку підмножину англійських рядків віджета |
Зворотні виклики
| Зворотний виклик | Викликається коли | Дані |
|---|---|---|
onReady() | Віджет відобразив свій екран перетягування | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open успішно | Токен джерела, кількість сторінок, розширення джерела (без крапки), дозволені цілі |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run успішно | Відповідь виконання плюс запитаний target |
onDownload({ downloadName, downloadToken }) | Користувач натискає «Завантажити» | Викликається разом із завантаженням браузера |
onError({ phase, message }) | Запит відкриття або виконання не вдається | phase є 'open' або 'run'; message — це очищена помилка сервера |
Зворотний виклик, який викидає виключення, ловиться і записується в журнал; він ніколи не порушує роботу віджета.
Імперативний дескриптор
Doconut.convert() повертає екземпляр віджета:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // File з вашого власного <input type="file" id="picker">
conv.reset(); // повернутись до екрану перетягування; не викликає повторно onReady
conv.loadFile(file); // запускає процес з File; без дії, якщо widget не знаходиться на своєму drop screen
conv.destroy(); // видаляє слухачі, очищає mount; інстанція непрацездатна після цьогоМітки
Кожен рядок має англійське значення за замовчуванням; labels перезаписує будь-яку підмножину, а решта залишається англійською. Фрагменти, які змінюються під час виконання, використовують {placeholders}, наприклад uploading: 'Uploading {name}…' і pages: '{n} pages'.
| Ключ | Англійське за замовчуванням |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could not reach the server. Please check your connection and try again. |
Подальші ключі охоплюють aria-label зони перетягування (dropAriaLabel), тексти попереднього перегляду alt (previewAlt, resultAlt), зв'язану форму повідомлення про водяний знак, що використовується з licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), нечитаючу відповідь (badResponse) та оголошення aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
JSON‑помилка від сервера відображається так, як її записав сервер; serverError використовується лише коли невдала відповідь не містить JSON‑помилки, наприклад 404 вимкненого віджета.
Тематизація
Віджет додає клас dcw до свого елементу монтування та читає його кольори, радіус і шрифт з користувацьких властивостей CSS, тому ви можете оформити його без зміни внутрішньої структури:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}За замовчуванням: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px та системний UI шрифт для --dcw-font.
Створіть власний інтерфейс
Віджет є клієнтом цього HTTP‑контракту на DocImage.axd. Маршрути відповідають 404, доки не буде викликано AddConverterWidget(). Помилки містять тіло у форматі JSON, { "error": "..." }, за винятком випадків, коли в таблиці зазначено «лише статус». Невідоме значення ?convert= відповідає 400.
| Маршрут | Призначення | Успішна відповідь |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | Завантажити та відкрити вихідний документ | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Перетворити завантажений вихідний файл у target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Транслювати перетворений файл | 200 — файл, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt у відповіді open не має початкової крапки ("docx") — навпаки до параметра sourceExtension у ConvertAsync. allowedTargets перераховує назви цілей у нижньому регістрі ("pdf", "html", …); передайте одну з них як target, яка порівнюється без урахування регістру. open використовує перший файл у multipart‑тілі.
resultToken — це null, а resultPages — це 0, коли результат не можна попередньо переглянути. downloadName — це назва вихідного файлу з розширенням цілі.
Зображення попереднього перегляду використовують стандартний маршрут зображень переглядача, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, з token з open або resultToken з run. Віджет запитує width=240.
Завантажені джерела зберігаються протягом 30 хвилин після останнього читання; після цього run відповідає 404 і файл потрібно відкрити знову. downloadToken отримує власне 30‑хвилинне вікно після завершення конвертації. resultToken — це звичайний токен переглядача для попереднього перегляду результату; коли результат можна переглянути, він має те саме значення, що і downloadToken.
| Маршрут | Статус | Коли | Тіло |
|---|---|---|---|
| будь-який | 404 | Віджет не ввімкнено (AddConverterWidget() ніколи не викликався) | лише статус |
| будь-який | 405 | Неправильний метод (open/run потребують POST, download потребує GET) | лише статус |
open | 400 | Не multipart‑завантаження | Expected a multipart file upload. |
open | 400 | Немає файлу або файл порожній | No file uploaded. |
open | 400 | Тип, який не можна конвертувати | This file type cannot be converted. |
open | 403 | Тип файлу потребує можливості, яку ліцензія не надає (файл DICOM без Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Завантаження перевищує MaxUploadMb (але не обмеження IIS) | File is too large. |
run | 400 | Некоректний токен (не GUID) | Invalid token. |
run | 400 | target, який не розбирається у ConversionTarget | Unknown target format. |
run | 400 | Ціль, якої немає у allowedTargets | That target format is not available for this file. |
run | 404 | Термін дії завантаження минув або його ніколи не відкривали | Upload expired — please re-open the file. |
open, run | 500 | Обробка не вдалася | Очищене повідомлення |
download | 400 / 404 | Некоректний, невідомий або прострочений токен завантаження | лише статус |
Повний цикл з fetch:
// файл: Файл для конвертації, наприклад з <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: завантажте файл
const form = new FormData();
form.append('file', file, file.name);
const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
if (!openResp.ok) throw new Error((await openResp.json()).error);
const opened = await openResp.json();
// 2. run: конвертуйте у PDF, коли це дозволено, інакше у перший дозволений цільовий формат
const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
'&convert=run&target=' + target, { method: 'POST' });
if (!runResp.ok) throw new Error((await runResp.json()).error);
const converted = await runResp.json();
// 3. download: простий GET, який може виконати браузер
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Кінцеві точки є однакове походження: ця версія не підтримує CORS. Розміщуйте ваш інтерфейс та скрипт віджета з того ж походження, що й Doconut, або використовуйте reverse‑proxy для обробника та шляхів ресурсів під вашим походженням UI.
У продакшн
- Встановіть плагін поруч із ядром пакету, тієї ж версії:
Install-Package Doconut.NETFramework.Converter. - Додайте файл ліцензії. Помістіть
Doconut.Viewer.Converter.licу ту ж папку, що іDoconut.Viewer.lic. - Встановіть обмеження завантаження.
MaxUploadMbуAddConverterWidget— це ліміт, який накладає Doconut; тримайтеmaxRequestLengthіmaxAllowedContentLengthуWeb.configвище його (див. Обмеження завантаження), і значенняmaxUploadMbвіджета має бути рівним йому. - Ніколи не блокуйте під час конвертації у Web Forms (див. У Web Forms).
- Вивільняйте результати конвертації. Потік, який повертає
ConvertAsync, використовується з пулу; його вивільнення повертає буфери в пул.
Веб‑ферми
Віджет зберігає кожне завантаження та його результат у пам'яті на сервері, який обслуговував open. За навантажувальником без sticky‑сесій, пізніший запит run, download або попереднього перегляду може потрапити на інший сервер і не знайти завантаження. Зареєструйте спільне, зашифроване сховище віджета через другий аргумент DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // тека, яку кожен сервер може читати і записувати
store.FarmKey = farmKey; // не менше 32 байтів, ідентична на кожному сервері
// store.Ttl = TimeSpan.FromMinutes(30); // як довго зберігається завантаження (за замовчуванням)
}));- Окремий сервер нічого не потребує: без цього виклику використовується сховище в пам'яті.
- Завантаження та результати зашифровані у спокої на спільному сховищі (AES-256, encrypt-then-MAC), і кожен файл прив'язаний до свого токена, тому один токен ніколи не може прочитати файл іншого.
- На спільному сховищі завантаження або результат зберігаються протягом
Ttlпісля запису; читання не продовжує цей інтервал. FarmKeyмає бути щонайменше 32 байти і однаковим на всіх серверах. Завантажте його з секретного сховища; ніколи не вбудовуйте його в код. Реєстрація генеруєArgumentException, колиRootPathвідсутній абоFarmKeyкоротший за 32 байти.- Вкажіть
RootPathна те саме спільне розташування, яке використовує розподілений переглядач.
Посилання на API
Фасад та параметри віджета знаходяться в просторі імен Doconut; ConversionTarget розташований у Doconut.Configs.Conversion. ConverterPlugin розташований у Doconut.Plugins.Converter.
DocumentConverter
public sealed class DocumentConverter
{
public Task<Stream> ConvertAsync(
string filePath, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> ConvertAsync(
Stream source, string sourceExtension, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);
public Task<Stream> HtmlToWordAsync(
Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
CancellationToken ct = default);
}Отримується з DoconutHost.Services; конструктор є internal. sourceExtension включає початкову крапку. HtmlToWordAsync записує файл .doc, коли outputFormat є ConversionTarget.Doc, і файл .docx для будь-якого іншого значення.
ConversionTarget
45 форматів виводу, перелічених у Формати цілей.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Встановлюється через DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), який повертає DoconutOptions, щоб виклики можна було ланцюжити.
Усунення неполадок
| Симптом | Причина | Виправлення |
|---|---|---|
Кожен запит повертає порожній 500 після додавання плагіна; журнал подій Windows (джерело ASP.NET) показує The Converter plugin is registered via AddPlugin but no active license grants Converter. | Відсутня ліцензія, файл TRIAL, ліцензія без Converter або платна ліцензія поза її часовим вікном версії | Встановіть ліцензію, що надає Converter, або видаліть AddPlugin<ConverterPlugin>() |
Кожен запит повертає порожній 500; журнал подій показує AddConverterWidget() was called but the Converter plugin is not registered. | Віджет увімкнено без його плагіна | Додайте options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
Розв’язання DocumentConverter викликає No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin не зареєстровано | Додайте AddPlugin<ConverterPlugin>() у DoconutHost.Initialize |
| Конверсія Web Forms ніколи не повертає | Сторінка блокується на ConvertAsync | Використайте Async="true" та RegisterAsyncTask |
| Конверсія потоку повідомляє, що формат не підтримується | sourceExtension не має крапки на початку | Передайте ".xlsx", а не "xlsx" |
ConvertAsync викликає Converting '.dcm' requires the Dicom capability license. | Джерело DICOM, і ліцензія не надає Dicom | Використайте ліцензію, що надає Dicom |
| Вихід має водяний знак | Ліцензія тимчасова (Demo/NFR) | Використайте платну ліцензію, що надає Converter |
Віджет завантажується, але його запити повертають 404 | AddConverterWidget() не був викликаний, або basePath не є '/DocImage.axd' | Викличте AddConverterWidget(); встановіть basePath: '/DocImage.axd' |
| Велике завантаження показує сторінку помилки IIS замість повідомлення віджета | maxRequestLength / maxAllowedContentLength нижче MaxUploadMb | Підвищте ліміти Web.config вище MaxUploadMb |
open відповідає 403 Converting this file type requires the Dicom capability license. | Завантаження DICOM, і ліцензія не надає Dicom | Використайте ліцензію, що надає Dicom |
run відповідає 400 That target format is not available for this file. | Ціль не є однією з allowedTargets джерела | Пропонуйте лише allowedTargets з convert=open |
run або download відповідає 404 (Upload expired — please re-open the file. з run) | 30‑хвилинне вікно минуло, або інший сервер у фермі не має завантаження | Відкрийте файл знову; у фермі зареєструйте AddDoconutDistributedWidgets |
| Віджет не працює, коли UI знаходиться на іншому походженні | Кінцеві точки не підтримують CORS | Обслуговуйте UI з того ж походження, або використовуйте reverse-proxy для шляхів Doconut |
| Тема не застосовується | Змінні встановлені у предка або в елементі всередині монтованого; власне правило .dcw віджета встановлює їх на монтаж | Спрямовуйте на сам монтаж: #doconut-convert.dcw або #doconut-convert |
Примітки щодо фреймворку
У порівнянні з пакетами ASP.NET Core, цей пакет відрізняється лише способом хостингу; API, контракт кінцевих точок, скрипт віджета та правила ліцензування залишаються такими ж.
- Реєстрація знаходиться у
Application_Start, черезDoconutHost.Initialize, замістьbuilder.Services.AddDoconut. Сервіси, такі якAddDoconutDistributedWidgets, передаються другим аргументом. - Кінцеві точки обслуговуються
DocImage.axd, а скрипт –DoconutResourceModule, обидва зареєстровані уWeb.config, замістьUseDoconut()таUseDoconutResources(). Віджету потрібенbasePath: '/DocImage.axd'. - Помилки запуску проявляються у вигляді порожнього
500на кожному запиті, причину можна знайти у журналі подій Windows. - Завантаження повністю читаються ASP.NET до того, як Doconut їх бачить, тому ліміти IIS мають бути вище
MaxUploadMb. - Сторінки Web Forms не повинні блокуватись під час конверсії; дивіться У Web Forms.
- Тільки Windows, як і решта пакету .NET Framework.
Чи була ця сторінка корисною?