תוסף ממיר

תוסף הממיר הופך את Doconut לשירות המרת מסמכים. הוא תורם למנוע מאחורי המעטפת הציבורית DocumentConverter, וכן — באפשרות בחירה — וידג'ט מוכן לשימוש עם חוזה HTTP משלו, כך שניתן להמיר מסמכים מ‑C#, מהוידג'ט, או מממשק משתמש שאתה בונה בעצמך.

התקנת החבילה

התקן את תוסף הממיר היציב האחרון:

dotnet add package Doconut.NET6.Converter

כדי לעגן את התוסף לגרסה הנוכחית 26.7.0, העבר את הגרסה בנפרד:

dotnet add package Doconut.NET6.Converter --version 26.7.0

שמור על גרסת חבילת הממיר זהה לגרסת Doconut.NET6. מזהה החבילה הוא Doconut.NET6.Converter; .26.7.0 מופיע רק בשם הקובץ שהורד .nupkg.

רישום התוסף

אין שיטה AddConverter() — מודל הפלאגינים של Doconut אחיד. כל פלאגין, כולל הממיר, נרשם באותו האופן: קוראים AddPlugin<TPlugin>() בתוך AddDoconut(). ConverterPlugin מגיע בחבילת NuGet משלו, Doconut.NET6.Converter, המותקנת לצד חבילת הצופה הבסיסית.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

קריאה זו זורקת חריגה בזמן האתחול אם חסרה רישיון, קובץ TRIAL מיושן, או רישיון שאינו זמני שאינו מעניק את היכולת Converter — InvalidOperationException שמיוצרת מבפנים של AddDoconut(), לפני שהאפליקציה מתחילה לשרת בקשות. רישומי Demo/NFR זמניים מתקבלים; לאחר פקיעת תוקפם, ההמרה נשארת זמינה עם פלט מסומן במים. אין רמת חינם שקטה. ראה הגדרת רישיון כדי להבין איך רישיונות נטענים.

המרה מ‑C#

כל המרה מחזירה MemoryStream שניתן לחיפוש, ממוקמת ב‑0, מוכנה לקריאה או העתקה מיידית. קבל את DocumentConverter מה‑DI בכל מקום שבו אתה זקוק לו — הוא חסר‑מצב על‑פי‑תכנון, ולכן מופע יחיד בטוח לשימוש חוזר בין בקשות.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

שתי נקודות שיכולות לטעות בקלות: sourceExtension בגרסת ה‑stream חייב לכלול את הנקודה המקדימה (".xlsx", ולא "xlsx" ) — הממיר משווה זאת אל קטלוג הפורמטים ונקודה ללא קידומת לא תיפתר. ולמרות שמו, WordToHtmlAsync מחזיר Task<Stream>, ולא Task<string> — אתה מקבל את מסמך ה‑HTML (תמונות משובצות כ‑Base64) כ‑stream, בדיוק כמו כל תוצאה של המרה אחרת.

פורמטים יעד

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

לא כל מקור ניתן להמרה לכל יעד — התוסף ממפה כל משפחת פורמט מקור (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) למערך קבוע של יעדים מותרים. אל תקודד קבוע את המונה הזה ברשימת היעדים של הממשק שלך: ?convert=open מחזיר את allowedTargets האמיתי עבור הקובץ שהועלה זה עתה, וזה מה שצריך להניע את בחירת היעד.

וידג'ט מוכן לשימוש

קצות הקצה ?convert=open|run|download של הוידג'ט הם באפשרות בחירה וכבויים כברירת מחדל — מאובטחים כבר מההתחלה. אפשר אותם בצד השרת, יחד עם רישום התוסף:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

בלי AddConverterWidget(), שלושת הקצוות ?convert= מחזירים 404 — אך קובץ ה‑JS עצמו עדיין מוגש (זהו משאב סטטי משובץ; רק הקצוות שהוא מתקשר אליהם מוגבלים). AddConverterWidget() עדיין דורש שהתוסף Converter יהיה רשום ורישיון שמעניק Converter — הוא אינו מעניק זכויות המרה בפני עצמו.

התאמת הוידג'ט

אפשרויות אתחול שמועברות ל‑Doconut.convert(selector, options):

Callbacks:

Doconut.convert() מחזיר את מופע הוידג'ט עצמו — שמור עליו כדי לשלוט בוידג'ט תכנותית:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // חזרה למסך ההמתנה/נחת; לא מפעיל מחדש onReady
conv.loadFile(file);  // מתחיל את הזרימה עם אובייקט File; ללא‑פעולה אם אינו במצב המתנה
conv.destroy();       // מסיר מאזינים, מרוקן את המיקום; המופע אינו ניתן לשימוש לאחר מכן

בניית ממשק משתמש משלך

הוידג'ט הוא רק לקוח לחוזה HTTP הזה — בנה ממשק משתמש משלך נגדו ישירות לחוויית משתמש שונה. כל שלושת הנתיבים נמצאים תחת ענף ASP.NET שבו UseDoconut() מותקן (בדרך כלל /doconut):

בייטים של המקור המועלה נשמרים בצד השרת עם TTL של 30 דקות; לאחר חלוף חלון זמן זה, run מחזיר 404 והקובץ צריך להיפתח מחדש. תוצאת ההמרה נשמרת באותו מאגר — downloadToken מקבל חלון זמן של 30 דקות משלו כאשר ההמרה מסתיימת — בעוד resultToken הוא אסימון סשן צופה רגיל שהחיים שלו תלויות במטמון הסשן של הצופה, באופן עצמאי מהמאגר.

sourceExt בתשובת open אינו כולל נקודה (למשל "docx") — בניגוד לקונבנציית sourceExtension בפרמטר של DocumentConverter.ConvertAsync, שדורשת נקודה.

מצבי כשל, מקובצים לפי נתיב

בעלות על המשאבים

הממיר מחזיר MemoryStream שניתן לחיפוש, ממוקם באפס. המבצע הוא בעל ה‑stream ויש לפנות אותו לאחר העתקה או החזרת תוכנו. שירות DocumentConverter עצמו חסר‑מצב ונפתר מה‑DI; אין לבנות או לשחרר את השירות באופן ידני.

לגבי וידג'ט האינטרנט, מאגרי ההעלאה וההורדה פועלים עם TTL של 30 דקות נפרד. אסימון resultToken של הצופה מתמשך לאורך חיי סשן הצופה. סגירת תוצאת הצופה אינה מוחקת מאגר הורדה שעדיין בתוקף, והפעלת הוידג'ט מחדש אינה מאריכה אף אחד מה‑TTL‑ים.

פתרון בעיות

סימון במים

עם ConverterPlugin רשום, רישיון המארח נמצא באחת משלוש המצבים:

שתי דרכי הקריאה מחשבות את הדגל מאותו כלל: המעטפת C# של DocumentConverter מחשבת זאת פנימית מהמצב של IsViewerLicensed ו‑IsTemporary ברישיון, והמתאם של הוידג'ט ב‑?convert=run מבצע את אותה בדיקה (IsViewerLicensed && !IsTrial && !IsTemporary) כדי למלא את השדה watermarked שהוא מחזיר. ניתן לבנות אינטגרציה ולבדוק קצה‑קצה על רישיון הערכה לפני רכישה — רק בתים של הפלט משתנים.