الترقية إلى .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.
قبل الترحيل
- أنشئ فرعًا ونسخة احتياطية قابلة للنشر من التطبيق الحالي.
- سجّل إصدارات الحزمة الأساسية والإضافية بدقة.
- قم بجرد كل استدعاء
new Viewer(...)، واستدعاءInitCache()، واستدعاء تحميل الترخيص، وتعيينUseDoconutWebFarm، ومتحكم التحويل، وسكريبت Doconut المنسوخ، وإجراء شريط الأدوات المخصص، واستدعاء Viewer، ونقطة النهاية لفتح المستند. - احفظ ملفات
.licالحالية وأسرار النشر خارج نظام التحكم في المصدر. - اجمع مجموعة ممثلة من مستندات PDF، Office، الصور، CAD، البريد الإلكتروني، DICOM، القابلة للبحث، المحمية بكلمة مرور، والمُعَلَّقة.
- سجّل مهلة الجلسة الحالية، وسلوك الأمان، والخطوط، وإعدادات المنصة.
قم بترحيل بيئة واحدة قبل تغيير الإنتاج. يغيّر التكامل الحالي عمر الخدمة، وتوجيه الطلبات، وملكية الجلسة، وتوصيل موارد العميل، — إذا كنت تدير مجموعة خوادم — كيفية وصول الصفحات إلى المتصفح تمامًا.
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. التوافق بين الحزمة والترخيص
استبدل أو حدّث الحزمة الأساسية عمدًا؛ لا تعتمد على معرّف الحزمة المتطابق لاختيار واجهة برمجة التطبيقات الجديدة. الأمر الافتراضي يثبت أحدث إصدار ثابت:
dotnet add package Doconut.NETStandardلإجراء ترحيل قابل لإعادة الإنتاج إلى الإصدار الذي تم تدقيقه بواسطة هذا الدليل، مرّر الإصدار كخيار منفصل:
dotnet add package Doconut.NETStandard --version 26.9.0احتفظ بكل مكوّن إضافي من Doconut بنفس إصدار الحزمة الأساسية — Doconut.NETStandard.Converter وDoconut.NETStandard.Dicom. التكامل الحالي يحمل التراخيص مرة واحدة أثناء AddDoconut()، باستخدام هذه الأولوية:
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 لكل طلب وتم تمرير الخيارات إلى الطبقة الوسيطة:
// التكامل السابق — للتمييز فقط؛ لا تقم بتجميع هذا ضد SDK الحالي.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });التكامل الحالي يسجل Doconut مرة واحدة ويتلقى Viewer من الحقن الاعتمادي:
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 نفسه لا يحتاج إلى تغيير — فقط الطبقة الوسيطة داخله:
app.UseDoconutResources(); // قبل الفرع
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());في خط الأنابيب الحالي:
- استدعِ
UseSession()قبل Doconut بينما أمان الجلسة مُفعَّل؛ - استدعِ
UseDoconutResources()قبلUseDoconut()؛ - احتفظ بـ
ResourcesPath، وعناوين URL للموارد المُولَّدة، وعميلResPathمتناسقين؛ - احتفظ بالفرع الذي تُخرِّطُه والعميل
BasePathمتناسقين.
MiddlewarePath هي تكوين مُتحقق؛ لا تُنشئ فرع ASP.NET Core بمفردها.
5. إنشاء العارض وعمره
قم بإزالة ذاكرات التخزين المؤقت المملوكة للتطبيق لكائنات Viewer. لا يبقى شيء في Viewer
ليس من المفيد الاحتفاظ به: فهو لا يحمل حالة المستند، وتملك ذاكرة التخزين المؤقت للجلسة كل ما يتجاوز مدة الطلب. قم بحقنه في نقطة نهاية، صفحة Razor، متحكم، أو خدمة تطبيق ذات نطاق:
app.MapPost("/api/open", async (Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});الرمز المميز المرتجع يحدد جلسة مستند على الخادم. عالجه كبيان حامل: لا تسجّله، ولا تحتفظ به، ولا تضعه في التحليلات.
6. فتح وإغلاق المستندات
استبدل OpenDocument(...) المتزامن بـ OpenDocumentAsync(...):
// التكامل الحالي: يأتي Viewer من DI وفتح المستند غير متزامن.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });تقبل التحميلات الحالية مسار ملف أو تدفق، تكوين تنسيق اختياري، DocOptions اختياري، ورمز إلغاء. أغلق جلسة الخادم صراحةً عندما لا يحتاج المتصفح إليها:
viewer.CloseDocument(token);احذف أي استدعاء لـ InitCache() والعلم الذي يحميه — لا يوجد شيء لتسخينه يدوياً. لا تعيد استخدام الرمز المميز الذي أنشأته المكتبة السابقة بعد الانتقال: افتح كل مستند مرة أخرى عبر API الحالي.
7. مزرعة الويب → موزعة: أكبر تغيير
UseDoconutWebFarm و WebFarmOptions لم يعودا موجودين. إذا كان تطبيقك يستدعيهما، فهذا القسم هو الترقية الخاصة بك؛ إذا لم يكن كذلك، تخطَّ إلى §8.
سابقاً كان هناك طبقة وسطية واحدة تقوم بكل شيء: كانت تخدم الصور المسبقة التجسيد من مجلد مشترك، وتقوم بالاستطلاع بينما كان عقدة أخرى لا تزال تكتبها.
// التكامل السابق — استدعاء واحد، تنسيق ضمني عبر نظام الملفات.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
Path = Path.Combine(env.WebRootPath, "webfarm"),
PageWaitTimeSeconds = 180,
StartWaitFromPage = 5,
});الوظيفة نفسها الآن مقسمة إلى نصفين واضحين. جانب الكتابة — العقدة التي تفتح المستند تنشر مجموعة القطع الكاملة (الصفحات، معلومات المستند، فهرس البحث، البيانات الوصفية) إلى المشاركة:
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);جانب القراءة — أي عقدة تخدم من المشاركة:
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.Path | FileShareConfig.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:
builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());// التكامل السابق
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 التي تُبدّل داخل الوسيط:
// التكامل السابق
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.UnSafeMode | UnsafeMode |
DocOptions.IsWebfarm | IsWebFarm |
DocOptions.WebfarmPath | WebFarmPath |
DocOptions.ImageResolution | لا يزال موجودًا لكن مهمل — اضبط الدقة في تكوين الصيغة بدلاً من ذلك |
DocOptions يحصل أيضًا على IsSecured.
واجهة برمجة التطبيقات الحالية تفصل الاهتمامات بشكل أكثر صرامة من السابقة، لذا تحقق من أن كل إعداد موجود في الكائن الذي يملكه الآن:
| الاهتمام | النوع الحالي |
|---|---|
| مسارات الوسيط، الترخيص، تسجيل المكوّن الإضافي | DoconutOptions |
| كلمة المرور، المهلة، الأمان، العلامة المائية | DocOptions |
| عرض الصيغة و DPI | PdfConfig، WordConfig، ExcelConfig، وأنواع أخرى BaseConfig |
| الإعدادات الافتراضية لأداة المتصفح | ViewerConfig أو خيارات JavaScript المكافئة |
| CSS والسكربتات المولدة | CssConfig و ScriptConfig |
| التخزين المشترك ومزودي السحابة | FileShareConfig والتهيئات الأخرى Doconut.Clouds |
لا تستمر في استخدام DocOptions.ImageResolution كعنصر تحكم في العرض. فهو مهمل؛ اضبط BaseConfig.ImageResolution في تكوين الصيغة المحددة. راجع جميع الإعدادات الافتراضية بدلاً من افتراض أن التكوين السابق له نفس السلوك.
11. عارض الجانب العميل — تغييران يفشلان بصمت
كلاهما يترك الخادم يعمل بشكل مثالي. مستندك يُعرض، والصفحة تبدو صحيحة، ولا يظهر شيء في وحدة تحكم المتصفح. اقرأ هذا القسم حتى إذا نجح تجميع C# من أول محاولة.
ردود نداء العارض هي خيارات الآن، ليست دوالًا عامة
العارض السابق كان يستدعي المعالجات الخاصة بك بالاسم، مستخرجًا اسم الدالة العامة من معرف الحاوية. كان إعلان function ctlDoc_OnViewerReady() على صفحة تحتوي على <div id="div_ctlDoc"> كافيًا. العارض الحالي يأخذ ردود نداء صريحة في كائن الخيارات ولم يعد يبحث عن تلك الدوال العامة:
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 إلى بادئة المورد
ResPath: '', // قبل — الموارد كانت تأتي من جذر التطبيق
ResPath: 'doconut-res/images', // الآن — البادئة UseDoconutResources() تُركّبإذا قمت بتغيير البادئة عبر DoconutOptions.ResourcesPath، فاستخدم تلك القيمة بدلاً من ذلك.
12. شريط أدوات العارض، البحث، والتعليقات التوضيحية
لا تقم بترحيل السكريبتات القديمة واحدة تلو الأخرى. التطبيقات المرجعية الحالية تُنشئ حزمة صفحة كاملة:
- إصدار CSS للعارض وCSS للبحث/التعليقات التوضيحية المرخصة باستخدام
ReferenceCss؛ - عرض شريط أدوات العارض المملوك للتطبيق؛
- عرض
searchBarMount،annBarMount، والملحق المطلوب للعارض؛ - إصدار سكريبتات العارض والوحدات المرخصة باستخدام
ReferenceScripts؛ - تحميل سكريبت المساعد الخاص بشريط أدوات التطبيق؛
- تهيئة واحد
objViewer؛ - تهيئة أشرطة البحث والتعليقات التوضيحية المرخصة؛
- استدعاء
attach(objViewer)على كل شريط؛ - فتح المستند واستدعاء
objViewer.View(token).
البحث والتعليقات التوضيحية هما وحدتان مرفقتان بنفس العارض، وليسا أشرطة أدوات مستقلة. شريط الأدوات الرئيسي يخص تطبيق المضيف؛ أشرطة البحث والتعليقات التوضيحية مدمجة، وتُقيد بالقدرات.
قم بإزالة الملفات المنسوخة يدويًا مثل documentLinks.js وdocViewer.UI.js فقط بعد أن تعمل الصفحة الحالية مع الموارد الصادرة عن ReferenceCss وReferenceScripts.
13. تسجيل الإضافات
طرق الترخيص الثابتة للإضافات لا تسجل الإضافات الحالية. قم بتثبيت وتسجيل كل حزمة مُصدرة صراحةً:
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:
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت (MVC/Razor Pages بالفعل يضيف واحدة)
builder.Services.AddSession();
app.UseSession();احتفظ بـ DocOptions.IsSecured = true ما لم يتطلب تصميم مُراجَع خلاف ذلك. لا تستخدم أبداً UnsafeMode = true كاختصار للترحيل على عقدة واحدة. اختبر الطلبات بدون رمز، رمز غير صالح، رمز منتهي الصلاحية، ورمز من جلسة متصفح مختلفة.
في بيئة مزارع، قد يصل طلب الصفحة إلى عقدة لم تشهد الطلب الأول، وبالتالي سيتسبب فحص الجلسة في رفضه. هذه هي الحالة الوحيدة التي يكون فيها UnsafeMode = true صحيحًا — ويجب أن يُقترن بتذاكر وصول موقعة عبر AddDoconutDistributedDocumentSecurity، وليس مُرسلًا بمفرده. راجع نشر موزع.
ملاحظة حول التسمية
في جميع الأطر، الصنف هو Viewer. إذا وجدت DocumentViewer في مقتطفات قديمة أو مقالات من طرف ثالث، فإن هذا النوع لم يكن موجودًا أبدًا في SDK.
15. ترتيب العمل المقترح
- تأكد من أن إطار العمل المضيف يمكنه استهلاك netstandard2.1. إذا لم يستطع، توقف.
- قم بترقية الحزمة إلى 26.8.0 ثم ابنِها. عالج أخطاء التجميع — معظمها أسطر
usingفي الفقرة 1. - انقل بدء التشغيل إلى
AddDoconut()واتصالات الطبقة الوسيطة إلى ترتيبها الجديد (§3، §4). - أدخل
Viewerحيث كنت تُنشئه، اجعلOpenDocumentغير متزامن، واحذفInitCache()(§5، §6). - إذا كنت تستخدم مزرعة الويب، نفّذ §7 — الجزء الوحيد الذي يتطلب إعادة تصميم بدلاً من إعادة تسمية.
- إذا قمت بتحويل المستندات، نفّذ §8.
- نفّذ §11 — التغييرات على جانب العميل. هي التي لن تُعلن عن نفسها.
- افتح مستندًا حقيقيًا في المتصفح، وراقب المؤشر المتحرك. بناء أخضر لا يثبت شيئًا هنا: الترخيص، تسجيل الإضافات، مسار المورد، ونداءات العارض تفشل جميعها فقط أثناء التشغيل. بالنسبة لمزرعة، تحقق من أن المستند المنشور من عقدة واحدة يُقدم من قبل عقدة أخرى.
اختبار الترحيل
على الأقل، تحقق من:
- بدء تشغيل التطبيق مع الترخيص الإنتاجي وكل المكوّن الإضافي المسجل؛
- ملفات CSS/السكريبتات للعارض وكل طلبات صور الصفحات تحت المسارات المختارة؛
- فتح المستند، التنقل، التكبير، الصور المصغرة، الطباعة، والإغلاق الصريح؛
- البحث في مستند يحتوي على نص وحالة عدم قابلية البحث لملف يحتوي على صورة فقط؛
- تحميل التعليقات التوضيحية، الحفظ، التصدير، وتقييد القدرة؛
- اكتشاف هدف المحول، الإخراج، التنزيل، وحالة العلامة المائية؛
- صفحات DICOM، الإطارات، والرسوم المتحركة؛ البيانات الوصفية التقنية غير متوفرة في هذه الحزمة؛
- المستندات المحمية بكلمة مرور، الخطوط المخصصة، النص غير اللاتيني، والمهلات المكوّنة؛
- رفض الرموز عبر الجلسات وسلوك الجلسة المنتهية؛
- للمزرعة: نشر على عقدة واحدة، طلب صفحة متأخرة من أخرى، وتأكيد أن العارض يعيد محاولة استجابات
202بدلاً من عرض بلاطات مكسورة؛ - الهواتف المحمولة، الوضع الداكن، ومسار العكس الوكيل الإنتاجي.
خطة الاسترجاع
احتفظ بقطعة النشر السابقة، الحزم المطابقة، ملفات الترخيص، والموارد المتصفح المنسوخة معًا. عملية استرجاع آمنة تبدّل جيل التطبيق بالكامل؛ لا تخلط خادم الجيل السابق مع السكريبتات الحالية، أو خادم حالي مع مواقع استدعاء new Viewer(...).
قبل التحويل، وثّق:
- فتحة النشر أو القطعة المستخدمة للاسترجاع؛
- تأثير التخزين المشترك، إن وجد — القطع المنشورة بواسطة 26.8.0 لا تُستهلك من قبل طبقة الوسيط للويب-فارم السابقة؛
- كيف سيتم إبطال جلسات المستند النشطة؛
- فحص الصحة ووثيقة الاختبار السريعة المستخدمة لتحديد الاسترجاع؛
- من يمكنه استعادة مجموعة الحزم السابقة والإعدادات.
الوثائق القديمة
الدليل السابق المترجم لا يزال متاحًا على إعداد .NET Standard القديم. الـ بوابة التكامل السابقة تشرح نفس إشارات التعريف وتربط مرة أخرى إلى دليل الترحيل هذا.
احتفظ بعنوان URL التاريخي في العلامات المرجعية وتذاكر الدعم طالما أن تثبيتات netstandard2.0 لا تزال موجودة. هو يوثّق جيلًا مختلفًا ولا يُعاد توجيهه إلى الـ API الحالي.
هل كانت هذه الصفحة مفيدة؟