الترحيل

تغطي هذه الصفحة ترقية تطبيق ASP.NET موجود من Doconut.NETFramework 26.8.0 أو أقدم (.NET Framework 4.7) إلى 26.9.0 وما بعده (.NET Framework 4.7.2). حزمة عينات Doconut تتضمن دليل الترحيل الكامل والعينات الكلاسيكية التي تم نقلها إلى API الجديد — MVC 5، مزرعة ويب، وWeb Forms. مقارنة تطبيقك بالعينة التي بدأ منها هو أسرع مسار.

حزمة واحدة، إصداران

كلا المكتبتين تُنشران تحت نفس معرف الحزمة، Doconut.NETFramework. الإصدار يميزهما:

تحديث الحزمة هو الترقية. لا توجد حزمة منفصلة للتثبيت ولا طبقة توافق: 26.9.0 هي سطح API مختلف، لذا توقع أخطاء تجميع بعد التحديث — باقي هذه الصفحة. تم إيقاف خط .NET Framework 4.7 و 26.8.0 هو آخر إصدار له. يمكنك البقاء عليه — لا شيء هنا هو إصلاح أمان قد تفوّته — لكن الإصدارات الجديدة، الإضافات، الوضع الموزع، والودجات القابلة للإدماج تتوفر فقط في 26.9.0 وما بعده.

1. إعادة التوجيه وتحديث الحزمة

أعد توجيه مشروع الويب إلى .NET Framework 4.7.2 أولاً: المشروع الذي لا يزال يستهدف 4.7 لا يمكنه تثبيت 26.9.0، وNuGet يرفض التحديث. ثم قم بتحديث Doconut.NETFramework وأضف حزم الإضافات التي تستخدمها (Doconut.NETFramework.Converter، Doconut.NETFramework.Dicom، …). كل إضافة تحتاج إلى ترخيص يمنحها.

إذا كان المشروع يستخدم packages.config، فإن التحديث ينفّذ خطوة إلغاء تثبيت الإصدار السابق، التي تزيل معالج DocImage من Web.config، ولا يضيف 26.9.0ه مرة أخرى. سجّله مرة أخرى كما هو موضح في الخطوة 3؛ حتى تقوم بذلك، يرد DocImage.axd بـ 404 ولا تُظهر أي صفحة.

2. المساحات الاسمية: تقريبًا كل شيء تم نقله إلى الجذر

أسماء الأنواع لم تتغير: WordConfig، PdfConfig، ExcelConfig، CssConfig، ScriptConfig، FileShareConfig والبقية كلها لا تزال موجودة. في معظم الملفات التعديل الكامل هو حذف أسطر using.

3. بدء التشغيل: DoconutHost.Initialize وإدخالين في Web.config

الحزمة الكلاسيكية كانت تبني عارضها لكل طلب، مع خيارات كخصائص لتلك الحالة. الحزمة الجديدة لديها جذر تركيبي، يُبنى مرة واحدة في Application_Start، والعارض هو خدمة تقوم بحلّها:

// قبل - Doconut.NETFramework 26.8.0 وما قبله، حسب الطلب
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - المستعرض تم حله من DoconutHost، تم تكوين الترخيص مرة واحدة في DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize يذهب إلى Application_Start و DoconutHost.Shutdown في Application_End، و Web.config يحصل على معالج DocImage.axd ووحدة الموارد — كلاهما موجودان في التثبيت. إعدادات المظهر لكل صفحة (FitType، FixedZoom، ShowHyperlinks، …) انتقلت من حالة العارض إلى خيارات الودجت، أو إلى ViewerConfig يُمرّر إلى Viewer.RenderViewer (انظر ViewerConfig). لا يزال new Viewer() يُترجم بمجرد تشغيل DoconutHost.Initialize، لذا يمكن لكود الخلفية المُهجر الاحتفاظ بهذا السطر أثناء نقل الإعدادات.

الأمان يعمل كما كان. فتح مستند يمنح جلسة ASP.NET الحالية الوصول إلى صفحاته، وDocImage.axd يرفض الجميع. إعداد التطبيق DoconutUnSafeMode الذي كان يعطل ذلك أصبح الآن options.UnsafeMode في DoconutHost.Initialize — اتركه false. راجع الجلسات والأمان.

فشل بدء التشغيل الذي يُسقِط الموقع بالكامل. إضافة مسجّلة لا تمنحها أي ترخيص للقدرة تُلقي استثناءً في Application_Start، ثم يرد التطبيق بـ 500 فارغ لكل طلب — لا صفحة خطأ، لا شيء في سجل IIS، فقط إدخال في سجل أحداث Windows (المصدر ASP.NET). تُقرأ التراخيص من wwwroot تحت جذر الموقع ولا في أي مكان آخر، ويجب أن يكون الـ Doconut.Viewer.lic الأساسي موجودًا وإلا لن تُقرأ تراخيص الإضافة المجاورة له. راجع إعداد الترخيص.

4. مزرعة الويب: من علامة إلى الوضع الموزع

النموذج الكلاسيكي كان viewer.IsWebfarm = true بالإضافة إلى ExportToPng(path). النموذج الجديد يُسجل مرة واحدة: كل عقدة تشارك مخزنًا واحدًا ومفتاح توقيع واحد، وتستبدل تذكرة موقعة مرتبطة بالمتصفح عبارة "أي عقدة تجيب":

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath هو اسم مستعار
        d.SigningKey        = farmKey;                           // >= 32 بايت، نفس القيمة على كل عقدة
    }));

بعد ذلك افتح المستندات كالمعتاد، مع ربط المتصفح (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) وتسليم viewer.AccessToken إلى الواجهة مع الرمز. الجلسات والأمان يحتوي على الخطوات؛ عينة مزرعة الويب هي عقدة كاملة. لا يزال IsWebfarm و WebfarmPath يترجمان، لكنهما لم يعودا يفعّلان أي شيء.

شيئان يبدوان كنجاح ولكنهما ليسا كذلك: DistributedDocumentPublisher.PublishAsync يكتب ملفات المستند المصدرة لكنه لا يفتح جلسة، لذا يحصل المشاهد الموجه إلى رمز منشور على صورة خطأ بحجم ~2 كيلوبايت مع الحالة 200؛ وعميل اختبار بدون ملف تعريف الارتباط doconut-client يحصل على نفس الصورة، وليس 401. يمكنك التمييز بين صفحة حقيقية وصورة الخطأ حسب الحجم.

5. التحويل هو ملحق، وهو أصغر بكثير

التعداد SourceFormatConverter، والاثني عشر فئة *ConfigConverter، وتعداداتهم المستهدفة المتداخلة تُستبدل بتعداد واحد، ConversionTarget، واستدعاء واحد:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// افترض أن DoconutHost تم تهيئته بالفعل وأن CancellationToken المسمى ct متاح.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* دفق الإدخال الخاص بك */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

تنسيق المصدر يأتي من الامتداد الذي تمرره. لا يوجد طبقة توافق: كل إشارة إلى SourceFormatConverter هي خطأ تجميع تحلّه بحذفها. كائنات الخيارات لكل تنسيق لم تبقَ — لا يوجد ما يعادل WordConfigConverter.HtmlOptions و CadConfigConverter.CadOptions.ShowColor عبر ConvertAsync. في نماذج الويب، لا تحظر أبداً على ConvertAsync — انظر ملحق التحويل.

6. التخزين السحابي: الوصول إليه كمجلد مشترك

أنواع تكوين السحابة انتقلت إلى Doconut.Clouds دون تغيير. ومع ذلك، معالجات طلبات السحابة هي مكونات ASP.NET Core، ولا يحتوي تطبيق كلاسيكي على خط أنابيب لتشغيلها. من موقع System.Web، يمكن الوصول إلى التخزين السحابي كمجلد مشترك — على Azure، مشاركة Azure Files مُركبة على كل عقدة — يتم الوصول إليها عبر FileShareConfig.

7. التغييرات على جانب العميل التي تفشل بصمت

كل عنصر أدناه يترجم، يُنفّذ، لا يسجل أي شيء، ويقوم بالشيء الخطأ:

ثلاثة أخرى: المشاهد لا يرسم شريط أدواته الخاص (صفحتك توصل Zoom، Next، GotoPage والبقية إلى أزراره الخاصة); المشاهد الذي يُنشأ داخل نافذة Bootstrap مخفية يقيّم 0×0 ولا يرسم شيئًا حتى تعطي حاويته ارتفاعًا صريحًا وتعيد ضبطه على shown.bs.modal؛ وAllowSearch يفرض القيمة الافتراضية false لملف PDF، لذا يُعرض المستند بشكل مثالي بينما كل بحث لا يُعيد أي نتيجة.

8. ما يختفي

ترتيب العمل المقترح

1. أعد التوجيه، استبدل الحزمة، واحصل على تجميع Global.asax مع DoconutHost.Initialize وتسجيلين Web.config. يجب أن يبدأ الموقع.
2. صفحة عارض واحدة: احصل على مستند للعرض، ثم اعمل عبر القسم 7 حتى تعمل شريط الأدوات والبحث والتعليقات التوضيحية. تحقق في متصفح حقيقي — لا شيء في ذلك القسم يسبب خطأ.
3. التحويل (القسم 5): ميكانيكي، ومعظم أخطاء التجميع.
4. الصفحات المتبقية، باستخدام العينات المنقولة كهدف للفرق.
5. مزرعة الويب (القسم 4)، إذا كان لديك واحدة. اختبر باستخدام عقدتين ومتصفح، أو عميل يحتفظ بملفات تعريف الارتباط.