ستحصل على عارض مستندات مستضاف ذاتيًا وسريع كالبرق يعمل داخل تطبيق .NET الخاص بك
بنهاية هذا الدليل ستتمكن من فتح ملفات PDF وملفات Office ورسومات CAD وعشرات الصيغ الأخرى مباشرةً في المتصفح، مع أوقات تحميل أقل من ثانية، دون أي استدعاءات لخدمات SaaS خارجية، وتحكم كامل في الأمان.
المتطلبات المسبقة
| ما تحتاجه | لماذا هو مهم |
|---|---|
| .NET 6 أو أحدث (حزمة SDK تستهدف .NET 6+) | يضمن التوافق مع مجموعة تطوير Online Document Viewer SDK |
| خادم Windows أو Linux حيث يمكنك تشغيل تطبيقك (محليًا أو سحابة خاصة) | يتطلب الاستضافة الذاتية أن يعمل العارض داخل بنيتك التحتية الخاصة |
| الوصول إلى تغذية NuGet الخاصة بـ Online Document Viewer (https://doconut.com) | يتم توزيع SDK كحزمة NuGet |
| معرفة أساسية بـ ASP.NET Core وجافاسكريبت للواجهة الأمامية | ستقوم بإنشاء نقطة نهاية تُعيد عنوان URL موقعًا ثم تشغل العارض من المتصفح |
| موقع تخزين للملفات المصدر (نظام ملفات، تخزين كتل، إلخ.) | يقوم العارض بعرض الملفات من مسار محلي أو شبكة؛ يجب أن يكون المصدر قابلًا للوصول من قبل عملية الخادم |
غياب أي من هذه العناصر سيتسبب في توقف عملية البناء قبل تنفيذ السطر الأول من الشيفرة.
تثبيت مجموعة تطوير Online Document Viewer SDK
افتح مشروعك في Visual Studio أو بيئة التطوير المتكاملة المفضلة لديك وأضف مجموعة SDK الرسمية عبر مدير NuGet:
dotnet add package Doconut.NET8
تحتوي الحزمة على محرك العرض، محولات الصيغ، وطبقة HTTP خفيفة تُخدم الصفحات المُولدة. نظرًا لأن SDK يتم تجميعه داخل تطبيقك، لا يتم الاتصال بأي خدمة خارجية أثناء وقت التشغيل.
بعد استعادة الحزمة، سجّل خدمات SDK في Program.cs (أو Startup.cs للقوالب القديمة). يقوم التسجيل بحقن خط أنابيب العرض في حاوية DI الخاصة بـ ASP.NET Core، مما يجعلها متاحة للمتحكمات الخاصة بك.
تكوين خط أنابيب العرض للأنساق المطلوبة
يدعم العارض أكثر من 50 صيغة جاهزة، بما في ذلك:
- PDF, DOC, DOCX, ODT, RTF
- XLS, XLSX, CSV, ODS
- PPT, PPTX, ODP
- DWG, DXF, DGN (CAD)
- PSD, SVG, TIFF, WEBP, ICO
- EML, MSG, EPUB, MOBI, MPP, VSD
عند وصول الطلب، يحدد SDK نوع الملف ويختار المحول المناسب. للحصول على أفضل أداء، فعّل طبقة التخزين المؤقت المدمجة التي تخزن الصفحة المعروضة في الذاكرة طوال مدة الطلب؛ هذا ما يمنح تجربة “سريع كالبرق – عرض مستند فوري بأداء محسن وتحميل أقل من ثانية”.
في المتحكم الخاص بك، استدعِ طريقة العرض الخاصة بـ SDK (مثل RenderAsync) ومرّر المسار المطلق للملف المصدر. تُعيد الطريقة جزءًا من HTML يحتوي على عارض يعتمد على canvas. نظرًا لأن العرض يحدث على الخادم، يتلقى العميل فقط العلامات الجاهزة للعرض، مما يلغي المعالجة الثقيلة على جانب العميل.
تأمين العارض باستخدام عناوين URL قائمة على الرموز وتقييدات اختيارية
سيادة البيانات والامتثال للائحة GDPR هما من المخاوف الشائعة في عمليات النشر المحلية. يدمج SDK مع نظام المصادقة في ASP.NET Core، مما يتيح لك إنشاء رمز موقّع يمنح وصولًا لمرة واحدة إلى مستند معين.
التدفق النموذجي:
- الواجهة الأمامية تطلب من API الخاص بك رمز معاينة، مع توفير معرف المستند.
- يقوم API الخاص بك بالتحقق من أذونات المستخدم، وينشئ رمزًا على نمط JWT يشفّر مسار الملف وطابع زمني لانتهاء الصلاحية، ثم يُعيد الرمز.
- تضيف الواجهة الأمامية الرمز إلى عنوان URL للعارض (مثال:
/viewer?token=…). يتحقق SDK من صحة الرمز في كل طلب ويرفض أي رمز مُتلاعب أو منتهي الصلاحية.
إذا كنت بحاجة إلى منع المستخدمين من تنزيل أو طباعة المستند، قم بتكوين خيارات العرض التي يوفرها SDK لتعطيل تلك الإجراءات. سيقوم طبقة JavaScript للعارض بإخفاء زر التنزيل، وإلغاء اختصار الطباعة، ومنع قائمة السياق عند النقر بزر الفأرة الأيمن.
التحقق من أن كل شيء يعمل
- انتقل إلى الصفحة التي تستضيف العارض.
- يجب أن يظهر المستند خلال ثانية واحدة، مع أشرطة تمرير، أدوات تكبير، وصندوق بحث.
- إذا قمت بتكوين العارض لتعطيل التنزيل، يجب إخفاء زر “Download”.
- النقر بزر الفأرة الأيمن على المستند لا يجب أن يفتح قائمة السياق في المتصفح عندما يكون هذا القيد مفعلاً.
- بعد انتهاء صلاحية الرمز (الافتراضي 5 دقائق)، يجب أن يعيد تحديث الصفحة خطأ “401 Unauthorized”، مؤكدًا أن التحقق من الرمز نشط.
إذا فشل أي من هذه الفحوصات، عد إلى الخطوة المقابلة: تسجيل SDK مفقود، توليد رمز غير صحيح، أو إغفال علامات الأمان.