רישום והפעלת הווידג'ט של Doconut להמרת קבצים ב‑.NET 8

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

להלן תצורת אתחול מלאה, מוכנה להעתקה, שמספקת את שני הדרישות.

---

1. דרישות מוקדמות – רישיון ותמיכת סשן

• רישיון – תוסף ה‑Converter דורש רישיון שמעניק את היכולת Converter. יש למקם את הקובץ (למשל, Doconut.Viewer.lic) במקום שנגיש ליישום ולהצביע ל‑DoconutOptions.LicensePath אליו.
• מצב סשן – מודל האבטחה של Doconut מאחסן אסימוני מסמכי‑סשן ב‑ASP.NET Core session. הוסף מטמון מבוזר ו‑AddSession() לפני שה‑middleware מחובר.

builder.Services.AddDistributedMemoryCache();   // נדרש למושב
builder.Services.AddSession();                  // מאפשר מושב מבוסס IDistributedCache‑backed

2. רישום שירותי הליבה של Doconut

AddDoconut() הוא נקודת הכניסה היחידה שמזריקה את הצופה, שירות הרישיון, ואת רישום התוספים.

builder.Services.AddDoconut(options =>
{
    // הגדר ל‑Doconut היכן למצוא את קובץ הרישיון.
    options.LicensePath = "Doconut.Viewer.lic";

    // רשום את תוסף ה‑Converter – פעולה זו גם מאמתת את יכולת הרישיון.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

אם הרישיון אינו כולל את היכולת Converter, הקריאה למעלה תזרוק InvalidOperationException והיישום לא יתחיל. התנהגות כשל‑מהירה זו מונעת ממך לפרוס גרסה עם רישיון שגוי.

3. הפעלת הווידג'ט עם AddConverterWidget

הווידג'ט הוא אופציונלי. קריאה ל‑AddConverterWidget() רושמת את שלוש נקודות הקצה של ההמרה (?convert=open, ?convert=run, ?convert=download) ומחברת כמות קטנה של תצורת צד‑לקוח (גודל העלאה מרבי, נתיבי בסיס, וכו').

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

    // הפעל את ממשק ה‑drop‑in וקבע את מגבלת ההעלאה בצד ה‑client‑side.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // בדיקת‑קדם של הלקוח; השרת אוכף את המגבלה שלו
    });
});

רק הקריאה ל‑AddConverterWidget יוצרת את נקודות הקצה; קובץ ה‑JavaScript הסטטי (doconutConverter.js) תמיד מוגש כמשאב משובץ, אך הוא ייכשל ליצור קשר עם השרת אם נקודות הקצה חסרות.

4. חיבור ה‑middleware בסדר הנכון

ה‑middleware שמשרת משאבים סטטיים (UseDoconutResources) חייב לרוץ לפני ה‑middleware של הצופה הסופי (UseDoconut). גם middleware של הסשן צריך להיות ממוקם מוקדם יותר מכיוון ש‑Doconut מאמת את הסשן בכל בקשה.

app.UseSession();           // חייב לבוא לפני UseDoconut()
app.UseDoconutResources();  // משרת JS, CSS, תמונות
app.UseDoconut();           // מטפל בבקשות ?convert= ובבקשות דפי מסמך

עם הצינור הזה במקום, בקשה ל‑/doconut-res/doconutConverter.js מצליחה, והווידג'ט יכול לקרוא ל‑/doconut?convert=open, /doconut?convert=run ו‑/doconut?convert=download.

5. מה שהווידג'ט עושה בפועל

שלב	נקודת קצה בשרת	תגובה טיפוסית
פתיחה	?convert=open	מחזירה מטען JSON המכיל token, ספירת עמודים, סיומת מקור, ורשימת פורמטים מטרה מותרים.
הפעלה	?convert=run	מתחילה את ההמרה ומחזירה downloadToken, ספירת עמודים בתוצאה, שם קובץ מוצע, וסימן שמציין האם הפלט מסומן במים.
הורדה	?convert=download	משדרת את הקובץ המומר כאשר הלקוח ניגש לכתובת ההורדה שסופקה.

בצד הלקוח, הווידג'ט מבצע בדיקת גודל קובץ לפני העלאה כנגד widget.MaxUploadMb. אם הקובץ חורג מהמגבלה, הווידג'ט מבטל את ההעלאה ומפעיל את קריאת ההחזרה onError עם phase = "open" והודעה ידידותית. השרת אוכף את המגבלה שלו ויענה 413 Payload Too Large אם הבקשה חודרת את הבדיקה בצד הלקוח.

6. חיבור לאירועי הווידג'ט (לא נדרש צד C#)

כל קריאות ההחזרה (onReady, onSourceLoaded, onConverted, onError, וכו') הן פונקציות JavaScript המסופקות על ידי העמוד שמארח את הווידג'ט. מכיוון שהשאלה מתמקדת בצד ה‑רישום, אינך צריך לכתוב קוד C# נוסף כדי לטפל בקריאות אלו — הווידג'ט קורא להן אוטומטית ברגע שנקודות הקצה פעילות.

7. בעיות נפוצות וכיצד להימנע מהן

תסמין	סיבה אפשרית	פתרון
404 on /doconut?convert=open	AddConverterWidget() הושמט.	הוסף את הקריאה כפי שמוצג בסעיף 3.
היישום נכשל בהפעלה עם InvalidOperationException על חוסר יכולת	קובץ הרישיון אינו מעניק את Converter.	קבל רישיון הכולל את היכולת Converter.
שגיאת 500 הקשורה לסשן	UseSession() הונח אחרי UseDoconut() או שחסר רישום מטמון.	ודא ש‑app.UseSession() רץ לפני app.UseDoconut() וששירות המטמון נרשם.

8. הרץ את האפליקציה וצפה בווידג'ט בפעולה

1. בנה והרץ את פרויקט ASP.NET Core.
2. פתח דף שמכיל אלמנט <div id="doconut-convert"></div> ומכלול את סקריפט הממיר של Doconut (הסקריפט מוגש אוטומטית מ‑/doconut-res/doconutConverter.js).
3. גרור קובץ נתמך (PDF, DOCX, DWG וכו') לאזור ההפלה.
4. הווידג'ט יקרא ל‑?convert=open, לאחר מכן ל‑?convert=run, ולבסוף יציג קישור הורדה שמפנה ל‑?convert=download.

אם שלוש נקודות הקצה מגיבות ב‑JSON במקום 404, הווידג'ט רשום כראוי ומוכן לשימוש בייצור.

הצעד הבא: הוסף את קטעי הקוד שלמעלה ל‑Program.cs (או Startup.cs), וודא שקובץ הרישיון קיים, והפעל את האפליקציה. הווידג'ט המוטמע של הממיר יהיה פעיל ללא שינויים נוספים בצד השרת.