תוסף ממיר

המרת מסמכים ל-45 פורמטים יעד

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

פני שטחמתי להשתמש
DocumentConverter (C#)אתה ממיר בשרת, ללא דפדפן מעורב
Drop-in widget (doconutConverter.js)אתה רוצה מסך העלאה, המרה והורדה מוכן מראש בעמוד שלך
HTTP endpoints on DocImage.axd (?convert=open|run|download)אתה בונה UI המרה משלך נגד חוזה שרת מתועד

התקנת החבילה

powershell
Install-Package Doconut.NETFramework.Converter

כדי לקבע את התוסף לגרסה שהמסמך הזה מתאר:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

שמור את חבילת הממיר באותה גרסה כמו Doconut.NETFramework.

קובץ הרישיון של התוסף, Doconut.Viewer.Converter.lic, נמצא באותו תיקייה כמו Doconut.Viewer.lic; הוא נקרא יחד עם רישיון הצופה.

רישום התוסף

כל תוסף נרשם באותו אופן: AddPlugin<TPlugin>() ב-DoconutHost.Initialize, נקרא מ-Application_Start.

csharp
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:

text
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 בכל מקום שבו אתה צריך אותו והשתמש בו מחדש בחופשיות.

csharp
// פתור את DocumentConverter מ‑DoconutHost.Services; הבנאי שלו פנימי, ולכן לעולם אל תיצור אותו עם `new`.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension כולל את הנקודה המקדימה. password הוא null אלא אם המסמך מוגן.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// 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 את ההמרה:

csharp
[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 של הדף:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// 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 חברים:

text
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 והן כבויות כברירת מחדל. אפשר אותן ליד רישום הפלאגין:

csharp
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 זורק:

text
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 מעל למגבלת הווידג'ט:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

הטמע זאת

html
<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, ממיר, מציג תצוגה מקדימה של התוצאה כשזה אפשרי, ומציע את ההורדה.

אפשרויות

אפשרותסוגברירת מחדלהערות
basePathstring/doconutכתובת ה‑endpoint. הגדר '/DocImage.axd' בחבילה זו
resPathstring/doconut-resמקובל לצורך עקביות עם ווידג'טים אחרים של Doconut; ווידג'ט הממיר אינו בונה שום URL ממנו
maxUploadMbnumber25בדיקה מקדימה בצד הלקוח בלבד; השרת אוכף את המגבלה שלו
licenseUrlstring | nullnullהופך את הודעת המים על מסך התוצאה לקישור
labelsobject{}עוקף כל תת‑קבוצה של מחרוזות האנגלית של הווידג'ט

קריאות חזרה

קריאת חזרהמתרחשת כאשרנתוני העמסה
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() מחזיר את מופע הווידג'ט:

javascript
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'.

מפתחברירת מחדל באנגלית
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould 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 מותאמים אישית, כך שניתן לעצב אותו מבלי לגעת בפנים שלו:

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>המרת המקור שהועלה לtarget200 — { 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)סטטוס בלבד
open400לא מדובר בהעלאה מרובת חלקיםExpected a multipart file upload.
open400אין קובץ, או קובץ ריקNo file uploaded.
open400סוג שלא ניתן להמירThis file type cannot be converted.
open403סוג הקובץ דורש יכולת שהרישיון אינו מעניק (קובץ DICOM ללא Dicom)Converting this file type requires the Dicom capability license.
open413ההעלאה חורגת מMaxUploadMb (אך לא ממגבלות IIS)File is too large.
run400אסימון פגום (לא GUID)Invalid token.
run400target שלא מתפרש לConversionTargetUnknown target format.
run400יעד שלא נמצא בallowedTargetsThat target format is not available for this file.
run404ההעלאה פגה תוקף או שלא נפתחה מעולםUpload expired — please re-open the file.
open, run500העיבוד נכשלהודעה מסוננת
download400 / 404אסימון הורדה פגום, לא ידוע או פג תוקףסטטוס בלבד

סיבוב שלם עם fetch:

javascript
// 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 למטפל ולנתיבי המשאבים תחת המקור של הממשק שלך.

בייצור

  1. התקן את התוסף ליד חבילת הליבה, באותה גרסה: Install-Package Doconut.NETFramework.Converter.
  2. הוסף את קובץ הרישיון. שים Doconut.Viewer.Converter.lic באותה תיקייה כמו Doconut.Viewer.lic.
  3. הגדר את מגבלות ההעלאה. MaxUploadMb בAddConverterWidget הוא המגבלה ש-Doconut אוכף; שמור את maxRequestLength וmaxAllowedContentLength בWeb.config מעליו (ראה מגבלות העלאה), וmaxUploadMb של הווידג'ט שווה לו.
  4. לעולם אל תחסום על המרה ב-Web Forms (ראה ב-Web Forms).
  5. שחרר תוצאות המרה. הזרם ConvertAsync שמוחזר הוא משותף; שחרורו מחזיר את המאגרים שלו לבריכה.

חוות רשת

הווידג'ט שומר כל העלאה ותוצאתה בזיכרון על השרת שמספק את open. מאחורי מאזן עומסים ללא סשנים דביקים, בקשה מאוחרת של run, download או תצוגה מקדימה יכולה להגיע לשרת אחר ולא למצוא את ההעלאה. רשום את מאגר הווידג'ט המשותף והמוצפן דרך הארגומנט השני של DoconutHost.Initialize:

csharp
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

csharp
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

csharp
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
הווידג'ט נטען אך הבקשות שלו מחזירות 404AddConverterWidget() לא נקרא, או 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.

האם דף זה היה מועיל?