תוסף ממיר
המרת מסמכים ל-45 פורמטים יעד
תוסף הממיר הופך את Doconut לשירות המרת מסמכים. הוא תורם את המנוע מאחורי המעטפת הציבורית DocumentConverter ו‑— במצב אופציונלי — וידג'ט נשלף שמסופק על‑ידי DocImage.axd, כך שאתה יכול להמיר מסמכים מ‑C#, מהוידג'ט, או מממשק קדמי שאתה כותב בעצמך.
| פני שטח | מתי להשתמש |
|---|---|
DocumentConverter (C#) | אתה ממיר בשרת, ללא דפדפן מעורב |
Drop-in widget (doconutConverter.js) | אתה רוצה מסך העלאה, המרה והורדה מוכן מראש בעמוד שלך |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | אתה בונה UI המרה משלך נגד חוזה שרת מתועד |
התקנת החבילה
Install-Package Doconut.NETFramework.Converterכדי לקבע את התוסף לגרסה שהמסמך הזה מתאר:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0שמור את חבילת הממיר באותה גרסה כמו 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; הבנאי שלו פנימי, ולכן לעולם אל תיצור אותו עם `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 על העומס של ה‑stream חייב לכלול את הנקודה המקדימה (".xlsx", ולא "xlsx"), אחרת הוא לא יפתור. ולמרות שמו, WordToHtmlAsync מחזיר Task<Stream>, ולא Task<string> — מסמך ה‑HTML (תמונות משובצות כ‑Base64) מגיע כ‑stream, כמו כל תוצאה אחרת.
הקורא מחזיק ב‑MemoryStream שההמרה מחזירה וצריך לפנות אותו אחרי העתקה או החזרה (MVC's 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" והרץ את ההמרה כמשימת async של הדף:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: ההוראה @Page צריכה Async=\"true\", וההמרה רצה כמשימת async של דף.
// חסימה של זה במקום זאת (.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 (namespace 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, web document, DICOM) יש סט משלה של יעדים מותרים. המרת מקור DICOM (.dcm, .ima) דורשת גם רישיון שמעניק את היכולת Dicom; היעדים שלו הם Pdf, Png, Jpeg, Bmp, Tiff ו‑Gif. אל תקודד קבוע את המונה הזה כרשימת היעדים של הממשק שלך: ?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" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 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 | כתובת ה‑endpoint. הגדר '/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]; // קובץ משלך <input type="file" id="picker">
conv.reset(); // חזרה למסך ההפלה; לא מפעיל מחדש onReady
conv.loadFile(file); // מתחיל את הזרימה עם File; no-op אלא אם הווידג'ט נמצא במסך ההפלה
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": "..." }, למעט כאשר הטבלה מציינת "status only". ערך ?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 | לא מדובר בהעלאה מרובת חלקים | 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:
// file: הקובץ להמרה, לדוגמה מ-<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);
}הקצות הן same-origin: גרסה זו אינה תומכת ב‑CORS. יש לשרת את הממשק שלך ואת סקריפט הווידג'ט מאותו מקור כמו Doconut, או לבצע reverse‑proxy למטפל ולנתיבי המשאבים תחת המקור של הממשק שלך.
בייצור
- התקן את התוסף ליד חבילת הליבה, באותה גרסה:
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. מאחורי מאזן עומסים ללא סשנים דביקים, בקשה מאוחרת של 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; הבנאי פנימי. 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 |
| הווידג'ט נכשל כאשר הממשק נמצא במקור אחר | לנקודות הקצה אין תמיכת CORS | הגש את הממשק מאותו מקור, או הפוך-פרוקסי את נתיבי 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.
האם דף זה היה מועיל?