הטמעת Doconut באפליקציית האינטרנט שלך: מדריך מעשי

מציג Doconut הוא ספרייה של .NET לצפייה במסמכים שנועדה לשלב PDF, Office, CAD, תמונות ומשפחות מסמכים נתמכות אחרות בתוך אפליקציה. אינטגרציית Doconut מוצקה פחות מתמקדת במציאת הקוד הקצר ביותר ויותר בבחירת גבול נקי בין האפליקציה שלך, המציג והדפדפן.

מרכז תיעוד Doconut מקשר לנתיבי ההגדרה המתוחזקים עבור סוגי פרויקטים של .NET נתמכים. השתמש במדריך המתאים לגרסה המותקנת באפליקציה שלך, ואז התייחס לדף הסביבה, בדיקות הזהות, ותהליך הגישה כקוד אפליקציה שהצוות שלך שולט בו.

---

התחל עם גבול האינטגרציה

יש שלוש דרכים נפוצות למקם תצוגה מקדימה של מסמך במוצר. הבחירה הנכונה תלויה במי שבבעלותו הניווט, האימות, והחיים של המציג.

תבנית	התאמה מיטבית	ויכוח מרכזי
תצוגת אפליקציה	דף .NET שמציג את המציג לצד פקדי המוצר	אינטגרציה הדוקה, אך חיי הדף והמציג משולבים
iframe בבעלות האפליקציה	פורטל שדורש בידוד בין ממשק המשתמש המארח לנתיב התצוגה המקדימה	גבול ברור, אך יש לתכנן תקשורת במפורש
רכיב מסגרת סביב נתיב שרת	מעטפת React, Angular או Vue הנתמכת על ידי אפליקציית .NET	הרכבה מוכרת של חזית, עם יותר מצבי חיי חיים לניהול

תבנית ה‑iframe אינה חייבת להצביע על כתובת URL של מסמך ציבורי. היא יכולה להצביע על נתיב מאומת באפליקציה שלך. נתיב זה יכול לאמת גישה ולהציג את דף המציג מבלי לחשוף נתיב אחסון לדף המארח.

בניית משטח תצוגה מקדימה יציב ורגיש

אל תבנה מחדש את סימון המציג או את האתחול מקטע בלוג אילוסטרטיבי. Doconut מפרסם את הקבצים, שלבי המידלוור, מרחבי השמות, והגדרת המציג המתאימים לכל קו .NET נתמך. לדוגמה, המדריך הרשמי של מדריך הגדרת .NET 6 ומעלה מסביר את המידלוור של השרת, אובייקט המציג, אפשרויות המסמך, תצורת הרינדור, והנכסים הדרושים ללקוח.

השתמש בחומרי הגרסה הללו כדי ליצור את המציג, ואז תן לאזור המארח שלו רוחב וגובה יציבים בפריסה שלך. שמור מספיק מקום לפני הטעינה כדי שהדף הסביבתי לא יקפץ, ובדוק את סרגל הכלים והדף הראשון בנקודות שבירה האמיתיות הנתמכות על ידי המוצר שלך.

לפני שאתה מתחייב להרכבה, השווה אותה עם הדגמות חיות של Doconut. ההדגמות מכסות סגנונות אינטגרציה מרובים של .NET והחזית, כולל דוגמת iframe ייעודית, ועוזרות להבדיל בין נתיב נתמך רשמית לבין קטע קוד שנראה משכנע.

שמור החלטות גישה על השרת

דף המארח לעולם לא צריך להחליט אם משתמש יכול לצפות במסמך. לפני רינדור נתיב התצוגה המקדימה, האפליקציה צריכה:

1. לאמת את הבקשה.
2. להעניק הרשאה למשתמש עבור המסמך והדייר המבוקש.
3. לפתור את המסמך באמצעות מזהה הנשלט על ידי השרת.
4. לפתוח אותו דרך המציג רק לאחר שהבדיקות עברו.
5. להחזיר מצב כללי של לא נמצא או אסור ללא חשיפת פרטי אחסון.

מזהה אטום משפר את היגיינת ה‑URL, אך אינו מהווה הרשאה. החל את אותן בדיקות על בקשות דף, תמונה ממוזערת, חיפוש, אנוטציה, ייצוא והדפסה שאתה חושף.

החלט כיצד המארח והמציג מתקשרים

תצוגת אפליקציה יכולה לקרוא לרכיביה ישירות. iframe דורש חוזה מצומצם יותר. הגדר רק את האירועים שהמארח באמת צריך, כגון:

• התצוגה מוכנה
• המסמך נכשל בפתיחה
• הדף הנוכחי השתנה
• הפגישה פגה
• המשתמש ביקש לסגור את התצוגה

אם אתה משתמש ב-postMessage, אמת גם את event.origin וגם את מבנה ההודעה. אל תקבל מקורות עם תו כללי בייצור, ולעולם אל תעביר אישורים, מיקומי אחסון, או תוכן מסמך גולמי דרך הודעות.

התייחס למגבלות הדפדפן כהגנה בעומק

iframe אינו מבודד אוטומטית. תכונת sandbox יכולה להפחית יכולות, אך ערך מחמיר מדי עלול לשבור סקריפטים של המציג, הורדות, או התנהגות מאותו מקור. התחל מהקבוצה הקטנה ביותר של יכולות המתועדת לאינטגרציה שלך ובדוק אותה עם מדיניות האבטחה של התוכן (CSP) שלך.

גם סקור:

• frame-ancestors או X-Frame-Options לנתיב התצוגה המקדימה
• frame-src לדף המארח
• התנהגות עוגיות Same-site אם ה‑iframe דורש מושב
• מדיניות Referrer ל‑URL‑ים שמכילים מזהי ניתוב
• כותרות Cache לדפים שמציגים חומר רגיש

בקרות אלו שייכות לאפליקציה ולתשתית הסביבתית. רכיב המציג אינו יכול לבחור את המדיניות הנכונה עבור השכירות והמודל האיומי שלך.

תכנון מצבי טעינה, שגיאה ופג תוקף

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

למסמכים ארוכים, שמור על מכולת המציג בזמן שהדף הראשון מוכן. אם משתמשים יכולים להחליף מסמכים מבלי לעזוב את הדף, בטל בקשות ישנות והאפס את הכותרת הגלויה, ספירת העמודים, והמיקוד לפני טעינת הפריט הבא.

נגישות והתנהגות מקלדת

תן לכל iframe title שימושי. הפוך את התצוגה למגיעה באמצעות מקלדת, ספק דרך נראית להחזיר את המיקוד לדף המארח, ואל לתפוס את המיקוד בתוך שכבות מותאמות. אם למציג יש קיצורי מקלדת משלו, תעד קונפליקטים עם קיצורי המקלדת שבהם משתמשת מעטפת המוצר שלך.

פתרון נגיש חלופי יכול להציע הורדה מבוקרת או ייצוג חלופי כאשר כללי העסק שלך מאפשרים זאת. אל תוסיף קישור קובץ ציבורי רק כפתרון גיבוי.

רשימת בדיקה מעשית

לפני השחרור, אמת את נתיב הבקשה המלא ולא רק את טעינת הדף הראשונית:

• משתמש מורשה יכול לפתוח מסמך מורשה.
• משתמש מדייר אחר אינו יכול להשתמש מחדש בכתובת התצוגה המקדימה.
• בקשות ישירות לנקודות קצה הקשורות למציג מקבלות את אותן בדיקות הרשאה.
• רענון, ניווט אחורה, ופג תוקף של הפגישה מייצרים מצבים מובנים.
• התצוגה נשארת שמישה בגודלי תצוגה ורמות זום נתמכות.
• שגיאות קונסול הדפדפן ובקשות רשת נכשלות נראות במעקב.
• יומני האחסון והאפליקציה אינם רושמים סודות או כתובות URL של המסמכים המלאים.

סיכום

ה‑embed של Doconut שניתן לתחזוקה הוא זה עם חוזה קטן ומפורש. תן ל‑Doconut לטפל בתפקיד הצפייה במסמכים המתואר בתיעוד המגוזר שלו, בעוד שהאפליקציה שלך מחזיקה בזהות, הרשאה, ניתוב, שמירה, מדיניות דפדפן ומשוב משתמש. כאשר אתה מוכן להעריך את הדוגמאות המארזות באופן מקומי, השתמש ב-משאבי הורדה של Doconut הרשמי במקום להעתיק קוד ממאמר בלתי קשור.