الترقية إلى .NET Standard 2.1

نقل تطبيق Doconut.NETStandard موجود من الإصدار 26.7.0 إلى 26.8.0

يحتوي Doconut على تكاملين مميزين مع .NET Standard. يستخدمان نفس اسم الحزمة Doconut.NETStandard، لذا حدد الجيل من خلال الإصدار وواجهات برمجة التطبيقات في التطبيق قبل تغيير الحزم أو بدء التشغيل أو التراخيص أو موارد المتصفح.

الإصدار هو التقاطع في الطريق

الإصدارالهدفواجهة برمجة التطبيقات
26.7.0 وما أدناهnetstandard2.0واجهة برمجة التطبيقات السابقة
26.8.0 وما فوقnetstandard2.1واجهة برمجة التطبيقات الحالية

زيادة رقم الإصدار هي الترقية. لا توجد حزمة منفصلة للتثبيت ولا طبقة توافق — 26.8.0 هو سطح واجهة برمجة تطبيقات مختلف. توقع أخطاء تجميع بعد الزيادة؛ بقية هذا الدليل هي قائمة بهذه الأخطاء.

أي تكامل تستخدم؟

إذا كان المشروع يحتوي على…الجيل
new Viewer(_cache, _accessor, ...)سابق
viewer.OpenDocument(...) (متزامن)سابق
viewer.InitCache()سابق
UseDoconut(new DoconutOptions { ... })سابق
UseDoconutWebFarm(...) / WebFarmOptionsسابق
Viewer.DoconutLicense(...) أو Viewer.SetLicensePlugin(...)سابق
viewer.Converter.GetConverter()سابق
using Doconut.Configs; / using Doconut.Models;سابق
نسخ يدويًا docViewer.js، documentLinks.js أو docViewer.UI.jsسابق
builder.Services.AddDoconut(...)الحالي
app.UseDoconutResources() مع app.UseDoconut() بدون معلماتالحالي
Viewer supplied by dependency injectionالحالي
await viewer.OpenDocumentAsync(...)الحالي

إذا ظهرت كلا العمودين في نفس التطبيق، اعتبر الترحيل غير مكتمل. لا تقم بإرسال رمز مستند واحد عبر الموارد أو الوسطية من الجيل الآخر.

تحقق من إطار العمل المضيف أولاً

هذا باب صعب، ليس مجرد تفضيل. تستهدف الحزمة الحالية netstandard2.1:

المضيفيمكنه استهلاك 26.8.0
.NET Core 3.0 أو أحدث (بما في ذلك .NET 5/6/7/8)نعم
.NET Framework، أي إصدارلا

لا يمكن لـ .NET Framework الإشارة إلى مكتبة netstandard2.1. إذا كان التطبيق يعمل على .NET Framework، توقف هنا واستخدم حزمة Doconut.NETFramework بدلاً من ذلك؛ بدءًا من الإصدار 26.9.0 تتطلب .NET Framework 4.7.2. كلا التطبيقين المرجعيين لهذا الإصدار يستهدفان net8.0.

قبل الترحيل

  1. أنشئ فرعًا ونسخة احتياطية قابلة للنشر من التطبيق الحالي.
  2. سجّل إصدارات الحزمة الأساسية والإضافية بدقة.
  3. قم بجرد كل استدعاء new Viewer(...)، واستدعاء InitCache()، واستدعاء تحميل الترخيص، وتعيين UseDoconutWebFarm، ومتحكم التحويل، وسكريبت Doconut المنسوخ، وإجراء شريط الأدوات المخصص، واستدعاء Viewer، ونقطة النهاية لفتح المستند.
  4. احفظ ملفات .lic الحالية وأسرار النشر خارج نظام التحكم في المصدر.
  5. اجمع مجموعة ممثلة من مستندات PDF، Office، الصور، CAD، البريد الإلكتروني، DICOM، القابلة للبحث، المحمية بكلمة مرور، والمُعَلَّقة.
  6. سجّل مهلة الجلسة الحالية، وسلوك الأمان، والخطوط، وإعدادات المنصة.

قم بترحيل بيئة واحدة قبل تغيير الإنتاج. يغيّر التكامل الحالي عمر الخدمة، وتوجيه الطلبات، وملكية الجلسة، وتوصيل موارد العميل، — إذا كنت تدير مجموعة خوادم — كيفية وصول الصفحات إلى المتصفح تمامًا.

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

كانت أنواع التكوين موزعة عبر أربع مساحات اسمية. الآن جميعها موجودة في Doconut.

قبلالآن
using Doconut.Configs.View;using Doconut;
using Doconut.Models;using Doconut;
using Doconut.Configs;using Doconut;
using Doconut.Configs.Cloud;using Doconut.Clouds;
using Doconut.Configs.Conversion;دون تغيير
using Doconut.Middleware;دون تغيير

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

Doconut.Configs.Editor (BaseConfigEditor، PdfConfigEditor) تم إزالته ولا يوجد بديل له في هذه الحزمة. إذا كان تطبيقك يشير إلى تلك الأنواع، خطط لهذا الجزء بشكل منفصل ولا تعتبره جزءًا من هذا الترحيل.

2. التوافق بين الحزمة والترخيص

استبدل أو حدّث الحزمة الأساسية عمدًا؛ لا تعتمد على معرّف الحزمة المتطابق لاختيار واجهة برمجة التطبيقات الجديدة. الأمر الافتراضي يثبت أحدث إصدار ثابت:

bash
dotnet add package Doconut.NETStandard

لإجراء ترحيل قابل لإعادة الإنتاج إلى الإصدار الذي تم تدقيقه بواسطة هذا الدليل، مرّر الإصدار كخيار منفصل:

bash
dotnet add package Doconut.NETStandard --version 26.9.0

احتفظ بكل مكوّن إضافي من Doconut بنفس إصدار الحزمة الأساسية — Doconut.NETStandard.Converter وDoconut.NETStandard.Dicom. التكامل الحالي يحمل التراخيص مرة واحدة أثناء AddDoconut()، باستخدام هذه الأولوية:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

يبحث الاكتشاف التلقائي عن Doconut.Viewer.lic وملفات Doconut.Viewer.<Capability>.lic المرافقة. الاستدعاءات الثابتة السابقة Viewer.DoconutLicense(...) وViewer.SetLicensePlugin(...) ليست آلية بدء تشغيل حالية، ولا يُعد List<string> لمسارات الترخيص التي كان يقبلها المُنشئ القديم Viewer. انقل الترخيص إلى DoconutOptions، احتفظ بملفات المرافقة معًا عند استخدام الاكتشاف التلقائي، أعد التشغيل بعد تغيير الترخيص، وتحقق من القدرات عبر IDoconutLicenseService.

لا تفترض أن وجود ترخيص مكوّن إضافي قديم يثبت الأهلية لبناء مكوّن إضافي حالي. اختبر Viewer وSearch وAnnotation وConverter وDICOM بشكل منفصل باستخدام قطع الإصدار المعتمدة.

3. بدء التشغيل والحقن الاعتمادي

في السابق كان يتم إنشاء Viewer لكل طلب وتم تمرير الخيارات إلى الطبقة الوسيطة:

csharp
// التكامل السابق — للتمييز فقط؛ لا تقم بتجميع هذا ضد SDK الحالي.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

التكامل الحالي يسجل Doconut مرة واحدة ويتلقى Viewer من الحقن الاعتمادي:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // لاحظ تغيير الإملاء: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت (MVC/Razor Pages يضيف واحدة بالفعل)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer هي خدمة مؤقتة. مدير جلسة المستند وذاكرته يملكان حالة المستند ذات العمر الطويل، وليس المثيل المُحقن المحدد Viewer.

ثلاثة أشياء لنقلها:

  • new Viewer(cache, accessor) غير موجود. حقن Doconut.Viewer في المتحكم الخاص بك، أو استخدم @inject Doconut.Viewer Viewer في عرض Razor.
  • UseDoconutResources() يستبدل التوصيل اليدوي app.UseMiddleware<EmbeddedResourceMiddleware>()، ويجب أن يُنفّذ قبل فرع المستند.
  • UnSafeMode → UnsafeMode. إعادة تسمية بحرف واحد سيكتشفها المترجم.

عندما يكون UnsafeMode هو false يتحقق SDK من رمز الجلسة مقابل الطلب الأصلي، لذا يجب أن يظل AddSession() / UseSession() في خط الأنابيب، UseSession() قبل الفرع.

الأساليب التي لم تعد موجودة

قبلالآن
viewer.OpenDocument(path, config, options)await viewer.OpenDocumentAsync(path, config, options)
viewer.InitCache()تم الإزالة — لا شيء لتسخينه يدويًا؛ احذف الاستدعاء وأي علامة "هل قمت بالتهيئة بالفعل؟" حوله
viewer.ExportToPng(sharedPath)انظر §7
viewer.ExportToCloud(cloudConfig)انظر §7
using var v = new Viewer(...); v.CloseDocument(t)viewer.CloseDocument(token) على المثيل المُحقن

4. الطبقة الوسيطة وتوجيه الموارد

UseDoconut() الآن لا يأخذ أي معطيات. شكل فرع MapWhen نفسه لا يحتاج إلى تغيير — فقط الطبقة الوسيطة داخله:

csharp
app.UseDoconutResources();   // قبل الفرع

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

في خط الأنابيب الحالي:

  1. استدعِ UseSession() قبل Doconut بينما أمان الجلسة مُفعَّل؛
  2. استدعِ UseDoconutResources() قبل UseDoconut()؛
  3. احتفظ بـ ResourcesPath، وعناوين URL للموارد المُولَّدة، وعميل ResPath متناسقين؛
  4. احتفظ بالفرع الذي تُخرِّطُه والعميل BasePath متناسقين.

MiddlewarePath هي تكوين مُتحقق؛ لا تُنشئ فرع ASP.NET Core بمفردها.

5. إنشاء العارض وعمره

قم بإزالة ذاكرات التخزين المؤقت المملوكة للتطبيق لكائنات Viewer. لا يبقى شيء في Viewer ليس من المفيد الاحتفاظ به: فهو لا يحمل حالة المستند، وتملك ذاكرة التخزين المؤقت للجلسة كل ما يتجاوز مدة الطلب. قم بحقنه في نقطة نهاية، صفحة Razor، متحكم، أو خدمة تطبيق ذات نطاق:

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

الرمز المميز المرتجع يحدد جلسة مستند على الخادم. عالجه كبيان حامل: لا تسجّله، ولا تحتفظ به، ولا تضعه في التحليلات.

6. فتح وإغلاق المستندات

استبدل OpenDocument(...) المتزامن بـ OpenDocumentAsync(...):

csharp
// التكامل الحالي: يأتي Viewer من DI وفتح المستند غير متزامن.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

تقبل التحميلات الحالية مسار ملف أو تدفق، تكوين تنسيق اختياري، DocOptions اختياري، ورمز إلغاء. أغلق جلسة الخادم صراحةً عندما لا يحتاج المتصفح إليها:

csharp
viewer.CloseDocument(token);

احذف أي استدعاء لـ InitCache() والعلم الذي يحميه — لا يوجد شيء لتسخينه يدوياً. لا تعيد استخدام الرمز المميز الذي أنشأته المكتبة السابقة بعد الانتقال: افتح كل مستند مرة أخرى عبر API الحالي.

7. مزرعة الويب → موزعة: أكبر تغيير

UseDoconutWebFarm و WebFarmOptions لم يعودا موجودين. إذا كان تطبيقك يستدعيهما، فهذا القسم هو الترقية الخاصة بك؛ إذا لم يكن كذلك، تخطَّ إلى §8.

سابقاً كان هناك طبقة وسطية واحدة تقوم بكل شيء: كانت تخدم الصور المسبقة التجسيد من مجلد مشترك، وتقوم بالاستطلاع بينما كان عقدة أخرى لا تزال تكتبها.

csharp
// التكامل السابق — استدعاء واحد، تنسيق ضمني عبر نظام الملفات.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

الوظيفة نفسها الآن مقسمة إلى نصفين واضحين. جانب الكتابة — العقدة التي تفتح المستند تنشر مجموعة القطع الكاملة (الصفحات، معلومات المستند، فهرس البحث، البيانات الوصفية) إلى المشاركة:

csharp
var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher، مُحقن من DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // نفس المجلد الذي تستخدمه اليوم
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

جانب القراءة — أي عقدة تخدم من المشاركة:

csharp
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* نفس FileShareConfig SAME كما هو أعلاه */;
    }, "/"));
قبلالآن
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageتم إزالته — تم استبداله بـ FirstPagePriority على جانب الكتابة بالإضافة إلى FileShareConfig.ReadReadyPollMs على جانب القراءة
viewer.OpenDocument(...) ثم viewer.ExportToPng(share)استدعاء واحد PublishAsync(...)
DocOptions.IsWebfarm / WebfarmPathما زال موجودًا، مكتوبًا IsWebFarm / WebFarmPath — لكنه غير مطلوب في مسار النشر

بنيتك لا تتغير. وجه RootPath إلى نفس مشاركة UNC ويستمر كل عقدة في العمل كما هو اليوم. ما يتغير هو أن النشر هو عملية تستدعيها، بدلاً من أن يكون تأثيرًا جانبيًا للتجسيد.

يجب أن يتفق النصفان. إذا كان RootPath أو UsePerTokenSubfolders يختلفان بين الناشر والمعالج، فإن العقدة الأخرى تجيب 404. ابنِ التكوين في مساعد واحد واستدعِه من كلا الجانبين.

PageWaitTimeSeconds = 180 يعني "حجب حتى ثلاث دقائق على أمل ظهور الصفحة". الاستبدال واضح: مع FirstPagePriority = true، الصفحة 1 قابلة للخدمة فورًا والصفحات اللاحقة تجيب HTTP 202 Accepted حتى تُكتب. يعيد العارض المدمج المحاولة تلقائيًا عندما يُضبط retryOn409. العميل الذي لا يعيد المحاولة سيظهر بلاطات مكسورة للصفحات التي لا تزال تُجَسَّد.

التنظيم الكامل، بما في ذلك النشر الخلفي وتذاكر الوصول، موجود في التوزيعات الموزعة.

8. التحويل هو مكوّن إضافي، وهو أصغر بكثير

سجّل المكوّن الإضافي، ثم أدخل واجهة DocumentConverter:

csharp
builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());
csharp
// التكامل السابق
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// التكامل الحالي
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

ما الذي تم استبداله:

  • SourceFormatConverter — تم الحذف. مرّر امتداد الملف كسلسلة، بما في ذلك النقطة.
  • أنواع *ConfigConverter لكل عائلة (WordConfigConverter، ExcelConfigConverter، …)، كل منها يحتوي على تعداد EnTargetFormat متداخل — تم الحذف. الآن هناك تعداد واحد ConversionTarget لكل عائلة.
  • viewer.Converter.GetConverter() — تم الحذف. أدخل Doconut.DocumentConverter.

ConvertAsync تُعيد تدفقًا قابلًا للتمرير، لذا return File(result, mime, name) يعمل مباشرة — النسخة MemoryStream من الشيفرة القديمة لم تعد ضرورية. في العينة المرفقة تم حذف مفتاح امتداد بـ 68 حالة وعشرة متحكمات شبه متطابقة.

انظر مكوّن التحويل للحصول على الواجهة الكاملة.

9. مزوّدو السحابة

UseDoconutCloud أصبحت عامة. الموفر هو معامل النوع بدلاً من قيمة Location التي تُبدّل داخل الوسيط:

csharp
// التكامل السابق
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// التكامل الحالي
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

فئات التكوين لم تتغير باستثناء مساحة الاسم (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig، AmazonConfig، GoogleCloudConfig، DropBoxConfig، RedisConfig، CDNConfig، FTPConfig، بالإضافة إلى FileShareConfig الجديد. المتعاملون مسماة بـ <Provider>CloudHandler.

معالج CDN هو للقراءة فقط — فهو يقدم ما هو موجود بالفعل على CDN؛ لا يقوم بالرفع.

10. كائنات التكوين التي تغيرت أسماؤها

قبلالآن
DoconutOptions.UnSafeModeUnsafeMode
DocOptions.IsWebfarmIsWebFarm
DocOptions.WebfarmPathWebFarmPath
DocOptions.ImageResolutionلا يزال موجودًا لكن مهمل — اضبط الدقة في تكوين الصيغة بدلاً من ذلك

DocOptions يحصل أيضًا على IsSecured.

واجهة برمجة التطبيقات الحالية تفصل الاهتمامات بشكل أكثر صرامة من السابقة، لذا تحقق من أن كل إعداد موجود في الكائن الذي يملكه الآن:

الاهتمامالنوع الحالي
مسارات الوسيط، الترخيص، تسجيل المكوّن الإضافيDoconutOptions
كلمة المرور، المهلة، الأمان، العلامة المائيةDocOptions
عرض الصيغة و DPIPdfConfig، WordConfig، ExcelConfig، وأنواع أخرى BaseConfig
الإعدادات الافتراضية لأداة المتصفحViewerConfig أو خيارات JavaScript المكافئة
CSS والسكربتات المولدةCssConfig و ScriptConfig
التخزين المشترك ومزودي السحابةFileShareConfig والتهيئات الأخرى Doconut.Clouds

لا تستمر في استخدام DocOptions.ImageResolution كعنصر تحكم في العرض. فهو مهمل؛ اضبط BaseConfig.ImageResolution في تكوين الصيغة المحددة. راجع جميع الإعدادات الافتراضية بدلاً من افتراض أن التكوين السابق له نفس السلوك.

11. عارض الجانب العميل — تغييران يفشلان بصمت

كلاهما يترك الخادم يعمل بشكل مثالي. مستندك يُعرض، والصفحة تبدو صحيحة، ولا يظهر شيء في وحدة تحكم المتصفح. اقرأ هذا القسم حتى إذا نجح تجميع C# من أول محاولة.

ردود نداء العارض هي خيارات الآن، ليست دوالًا عامة

العارض السابق كان يستدعي المعالجات الخاصة بك بالاسم، مستخرجًا اسم الدالة العامة من معرف الحاوية. كان إعلان function ctlDoc_OnViewerReady() على صفحة تحتوي على <div id="div_ctlDoc"> كافيًا. العارض الحالي يأخذ ردود نداء صريحة في كائن الخيارات ولم يعد يبحث عن تلك الدوال العامة:

javascript
objctlDoc = $("#div_ctlDoc").docViewer({
    // ... خياراتك الحالية ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // تم العثور عليه بالاسم
    onViewerReady:    ctlDoc_OnViewerReady,     // تم العثور عليه بالاسم
    onCopy:           ctlDoc_Copy,              // كان ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // كان ctlDoc_AutoLoadStatus(page)
});

لماذا هذا مزعج: الاستدعاء القديم كان محاطًا بـ catch فارغ، مما ابتلع كل شيء. الآن لا تُنفّذ دوالك أبداً ولا يُبلغ عن أي خطأ. العرض الشائع هو مؤشر تحميل مستمر لا يتوقف — لأن الدالة التي كانت تخفيه هي ctlDoc_OnViewerReady. المستند خلفه سليم.

قائمة الخيارات الكاملة هي onPageLoading، onPageLoaded، onThumbnailClicked، onPageClicked، onDoubleClick، onViewerBusy، onViewerReady، onViewerError، onCopy، onAnnSaved، onAnnSaveError، onAnnLoaded، onAnnClosed، onAutoLoadStatus، onThumbsShown، وonError. لا يوجد رد نداء عند النقر على الرابط: معالجة الروابط مدمجة، وتُقَدَّم بواسطة showHyperlinks.

يجب أن يشير ResPath إلى بادئة المورد

javascript
ResPath: '',                      // قبل — الموارد كانت تأتي من جذر التطبيق
ResPath: 'doconut-res/images',    // الآن    — البادئة UseDoconutResources() تُركّب

إذا قمت بتغيير البادئة عبر DoconutOptions.ResourcesPath، فاستخدم تلك القيمة بدلاً من ذلك.

12. شريط أدوات العارض، البحث، والتعليقات التوضيحية

لا تقم بترحيل السكريبتات القديمة واحدة تلو الأخرى. التطبيقات المرجعية الحالية تُنشئ حزمة صفحة كاملة:

  1. إصدار CSS للعارض وCSS للبحث/التعليقات التوضيحية المرخصة باستخدام ReferenceCss؛
  2. عرض شريط أدوات العارض المملوك للتطبيق؛
  3. عرض searchBarMount، annBarMount، والملحق المطلوب للعارض؛
  4. إصدار سكريبتات العارض والوحدات المرخصة باستخدام ReferenceScripts؛
  5. تحميل سكريبت المساعد الخاص بشريط أدوات التطبيق؛
  6. تهيئة واحد objViewer؛
  7. تهيئة أشرطة البحث والتعليقات التوضيحية المرخصة؛
  8. استدعاء attach(objViewer) على كل شريط؛
  9. فتح المستند واستدعاء objViewer.View(token).

البحث والتعليقات التوضيحية هما وحدتان مرفقتان بنفس العارض، وليسا أشرطة أدوات مستقلة. شريط الأدوات الرئيسي يخص تطبيق المضيف؛ أشرطة البحث والتعليقات التوضيحية مدمجة، وتُقيد بالقدرات.

قم بإزالة الملفات المنسوخة يدويًا مثل documentLinks.js وdocViewer.UI.js فقط بعد أن تعمل الصفحة الحالية مع الموارد الصادرة عن ReferenceCss وReferenceScripts.

13. تسجيل الإضافات

طرق الترخيص الثابتة للإضافات لا تسجل الإضافات الحالية. قم بتثبيت وتسجيل كل حزمة مُصدرة صراحةً:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() يتحقق من قدرات الإضافات المسجلة عند بدء التشغيل. Converter و DICOM هما الإضافات المُصدرة لـ .NET Standard. البحث والتعليقات التوضيحية العادية هي ميزات مرخصة مدمجة، ليست حزم AddPlugin<TPlugin>().

14. أمان الجلسة والمستند

التكامل الحالي يربط المستندات برموز غير شفافة وجلسات مخزنة مؤقتًا. باستخدام UnsafeMode = false الافتراضي، يضيف UseDoconut() أمان وصول المستند ويجب على المضيف تكوين جلسة ASP.NET:

csharp
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت (MVC/Razor Pages بالفعل يضيف واحدة)
builder.Services.AddSession();
app.UseSession();

احتفظ بـ DocOptions.IsSecured = true ما لم يتطلب تصميم مُراجَع خلاف ذلك. لا تستخدم أبداً UnsafeMode = true كاختصار للترحيل على عقدة واحدة. اختبر الطلبات بدون رمز، رمز غير صالح، رمز منتهي الصلاحية، ورمز من جلسة متصفح مختلفة.

في بيئة مزارع، قد يصل طلب الصفحة إلى عقدة لم تشهد الطلب الأول، وبالتالي سيتسبب فحص الجلسة في رفضه. هذه هي الحالة الوحيدة التي يكون فيها UnsafeMode = true صحيحًا — ويجب أن يُقترن بتذاكر وصول موقعة عبر AddDoconutDistributedDocumentSecurity، وليس مُرسلًا بمفرده. راجع نشر موزع.

ملاحظة حول التسمية

في جميع الأطر، الصنف هو Viewer. إذا وجدت DocumentViewer في مقتطفات قديمة أو مقالات من طرف ثالث، فإن هذا النوع لم يكن موجودًا أبدًا في SDK.

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

  1. تأكد من أن إطار العمل المضيف يمكنه استهلاك netstandard2.1. إذا لم يستطع، توقف.
  2. قم بترقية الحزمة إلى 26.8.0 ثم ابنِها. عالج أخطاء التجميع — معظمها أسطر using في الفقرة 1.
  3. انقل بدء التشغيل إلى AddDoconut() واتصالات الطبقة الوسيطة إلى ترتيبها الجديد (§3، §4).
  4. أدخل Viewer حيث كنت تُنشئه، اجعل OpenDocument غير متزامن، واحذف InitCache() (§5، §6).
  5. إذا كنت تستخدم مزرعة الويب، نفّذ §7 — الجزء الوحيد الذي يتطلب إعادة تصميم بدلاً من إعادة تسمية.
  6. إذا قمت بتحويل المستندات، نفّذ §8.
  7. نفّذ §11 — التغييرات على جانب العميل. هي التي لن تُعلن عن نفسها.
  8. افتح مستندًا حقيقيًا في المتصفح، وراقب المؤشر المتحرك. بناء أخضر لا يثبت شيئًا هنا: الترخيص، تسجيل الإضافات، مسار المورد، ونداءات العارض تفشل جميعها فقط أثناء التشغيل. بالنسبة لمزرعة، تحقق من أن المستند المنشور من عقدة واحدة يُقدم من قبل عقدة أخرى.

اختبار الترحيل

على الأقل، تحقق من:

  • بدء تشغيل التطبيق مع الترخيص الإنتاجي وكل المكوّن الإضافي المسجل؛
  • ملفات CSS/السكريبتات للعارض وكل طلبات صور الصفحات تحت المسارات المختارة؛
  • فتح المستند، التنقل، التكبير، الصور المصغرة، الطباعة، والإغلاق الصريح؛
  • البحث في مستند يحتوي على نص وحالة عدم قابلية البحث لملف يحتوي على صورة فقط؛
  • تحميل التعليقات التوضيحية، الحفظ، التصدير، وتقييد القدرة؛
  • اكتشاف هدف المحول، الإخراج، التنزيل، وحالة العلامة المائية؛
  • صفحات DICOM، الإطارات، والرسوم المتحركة؛ البيانات الوصفية التقنية غير متوفرة في هذه الحزمة؛
  • المستندات المحمية بكلمة مرور، الخطوط المخصصة، النص غير اللاتيني، والمهلات المكوّنة؛
  • رفض الرموز عبر الجلسات وسلوك الجلسة المنتهية؛
  • للمزرعة: نشر على عقدة واحدة، طلب صفحة متأخرة من أخرى، وتأكيد أن العارض يعيد محاولة استجابات 202 بدلاً من عرض بلاطات مكسورة؛
  • الهواتف المحمولة، الوضع الداكن، ومسار العكس الوكيل الإنتاجي.

خطة الاسترجاع

احتفظ بقطعة النشر السابقة، الحزم المطابقة، ملفات الترخيص، والموارد المتصفح المنسوخة معًا. عملية استرجاع آمنة تبدّل جيل التطبيق بالكامل؛ لا تخلط خادم الجيل السابق مع السكريبتات الحالية، أو خادم حالي مع مواقع استدعاء new Viewer(...).

قبل التحويل، وثّق:

  • فتحة النشر أو القطعة المستخدمة للاسترجاع؛
  • تأثير التخزين المشترك، إن وجد — القطع المنشورة بواسطة 26.8.0 لا تُستهلك من قبل طبقة الوسيط للويب-فارم السابقة؛
  • كيف سيتم إبطال جلسات المستند النشطة؛
  • فحص الصحة ووثيقة الاختبار السريعة المستخدمة لتحديد الاسترجاع؛
  • من يمكنه استعادة مجموعة الحزم السابقة والإعدادات.

الوثائق القديمة

الدليل السابق المترجم لا يزال متاحًا على إعداد .NET Standard القديم. الـ بوابة التكامل السابقة تشرح نفس إشارات التعريف وتربط مرة أخرى إلى دليل الترحيل هذا.

احتفظ بعنوان URL التاريخي في العلامات المرجعية وتذاكر الدعم طالما أن تثبيتات netstandard2.0 لا تزال موجودة. هو يوثّق جيلًا مختلفًا ولا يُعاد توجيهه إلى الـ API الحالي.

هل كانت هذه الصفحة مفيدة؟