مهاجرت به .NET Standard 2.1

انتقال یک برنامهٔ موجود Doconut.NETStandard از نسخهٔ ۲۶.۷.۰ به ۲۶.۸.۰

Doconut دو ادغام متمایز .NET Standard دارد. آن‌ها از همان نام بستهٔ Doconut.NETStandard استفاده می‌کنند، بنابراین نسل را از نسخه و APIهای موجود در برنامه شناسایی کنید قبل از اینکه بسته‌ها، راه‌اندازی، مجوزها یا منابع مرورگر را تغییر دهید.

نسخه نقطهٔ انشعاب است

هر دو نسل تحت یک شناسهٔ بستهٔ یکسان منتشر می‌شوند. فقط نسخه آن‌ها را از هم متمایز می‌کند:

نسخههدفAPI
26.7.0 و پایین‌ترnetstandard2.0API قبلی
26.8.0 و بالاترnetstandard2.1API فعلی

افزایش شماره نسخه، ارتقا است. پس از ارتقا خطاهای کامپایل را انتظار داشته باشید؛ بقیهٔ این راهنما فهرست آن‌هاست.

کدام ادغام را استفاده می‌کنید؟

اگر پروژه شامل…نسل
new Viewer(_cache, _accessor, ...)قبلی
viewer.OpenDocument(...) (synchronous)قبلی
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 تأمین‌شده توسط تزریق وابستگیفعلی
await viewer.OpenDocumentAsync(...)فعلی

اگر هر دو ستون در یک برنامه ظاهر شوند، مهاجرت را ناقص در نظر بگیرید. یک توکن سند را از طریق منابع یا میدل‌ویر نسل دیگر ارسال نکنید.

ابتدا چارچوب میزبان را بررسی کنید

این یک مانع سخت است، نه یک ترجیح. بستهٔ فعلی هدف netstandard2.1 دارد:

میزبانآیا می‌تواند ۲۶.۸.۰ را مصرف کند
.NET Core 3.0 یا بالاتر (از جمله .NET 5/6/7/8)بله
.NET Framework، هر نسخه‌اینه

.NET Framework نمی‌تواند به کتابخانهٔ netstandard2.1 ارجاع دهد. اگر برنامه روی .NET Framework اجرا می‌شود، اینجا متوقف شوید و به‌جای آن از بستهٔ Doconut.NETFramework استفاده کنید؛ از نسخهٔ ۲۶.۹.۰ به بعد به .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. سازگاری بسته و مجوز

بستهٔ هسته‌ای را به‌صورت عمدی جایگزین یا به‌روزرسانی کنید؛ به شناسهٔ بستهٔ یکسان برای انتخاب API جدید تکیه نکنید. فرمان پیش‌فرض آخرین نسخهٔ پایدار را نصب می‌کند:

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 را به‌صورت جداگانه با artefacts نسخهٔ تأییدشده تست کنید.

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() جایگزین wiring دستی 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 را حذف کنید. هیچ چیزی در یک Viewer باقی نمی‌ماند که ارزش نگه‌داری داشته باشد: این شیء هیچ وضعیت سندی را حمل نمی‌کند و کش جلسه همه چیز را که پس از یک درخواست باقی می‌ماند، مالکیت می‌کند. آن را به یک نقطه انتهایی، صفحه Razor، کنترلر یا سرویس برنامه scoped تزریق کنید:

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

توکن بازگردانده‌شده یک جلسه سند سمت‑سرور را شناسایی می‌کند. آن را به‌عنوان یک اعتبار حامل در نظر بگیرید: آن را لاگ نکنید، ذخیره نکنید یا در تجزیه و تحلیل‌ها قرار ندهید.

6. باز کردن و بستن اسناد

دستورات synchronous 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 برمی‌گرداند.
پیکربندی را در یک helper بسازید و از هر دو سمت فراخوانی کنید.

PageWaitTimeSeconds = 180 به معنای «مسدود کردن تا سه دقیقه به امید ظاهر شدن صفحه» بود. جایگزین به‌صورت صریح است: با FirstPagePriority = true، صفحهٔ ۱ بلافاصله قابل سرویس است و صفحات بعدی تا زمان نوشتن HTTP 202 Accepted پاسخ می‌دهند. Viewer بسته‌شده به‌طور خودکار وقتی 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، …)، هر کدام با یک enum تو در تو EnTargetFormat — حذف شد. اکنون یک enum 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 را به‌دست می‌آورد.

API فعلی همچنین نگرانی‌ها را نسبت به نسخه قبلی به‌صورت دقیق‌تری جدا می‌کند، بنابراین بررسی کنید که هر تنظیمات بر روی شیئی باشد که اکنون مالک آن است:

نگرانینوع فعلی
مسیرهای میدل‌ویر، لایسنس، ثبت افزونهDoconutOptions
رمز عبور، زمان‌انتظار، امنیت، واترمارکDocOptions
رندر فرمت و DPIPdfConfig، WordConfig، ExcelConfig، و سایر انواع BaseConfig
پیش‌فرض‌های ویجت مرورگرViewerConfig یا گزینه‌های معادل جاوااسکریپت
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. نوار ابزار Viewer، جستجو و حاشیه‌نویسی

اسکریپت‌های قدیمی را یکی‌یکی مهاجرت نکنید. برنامه‌های مرجع فعلی یک بسته صفحه کامل را ترکیب می‌کنند:

  1. CSS Viewer و CSS جستجو/حاشیه‌نویسی دارای مجوز را با ReferenceCss صادر کنید؛
  2. نوار ابزار Viewer متعلق به برنامه را رندر کنید؛
  3. searchBarMount، annBarMount و سوارسازی مورد نیاز Viewer را رندر کنید؛
  4. اسکریپت‌های Viewer و ماژول‌های دارای مجوز را با ReferenceScripts صادر کنید؛
  5. اسکریپت کمکی نوار ابزار خود برنامه را بارگذاری کنید؛
  6. یک objViewer را مقداردهی اولیه کنید؛
  7. نوارهای جستجو و حاشیه‌نویسی دارای مجوز را مقداردهی اولیه کنید؛
  8. برای هر نوار، attach(objViewer) را فراخوانی کنید؛
  9. سند را باز کنید و objViewer.View(token) را فراخوانی کنید.

جستجو و حاشیه‌نویسی ماژول‌هایی هستند که به همان Viewer متصل می‌شوند، نه نوارهای ابزار مستقل. نوار ابزار اصلی متعلق به برنامه میزبان است؛ نوارهای جستجو و حاشیه‌نویسی به‌صورت جاسازی شده و با قابلیت‌های محدود شده در دسترس هستند.

فایل‌های کپی شده به‌صورت دستی مانند 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 را به صورت async کنید و InitCache() را حذف کنید (§5، §6).
  5. اگر از مزرعه وب استفاده می‌کنید، §7 را انجام دهید — تنها بخشی که بازطراحی است نه تغییر نام.
  6. اگر اسناد را تبدیل می‌کنید، §8 را انجام دهید.
  7. §11 را انجام دهید — تغییرات سمت کلاینت. این‌ها همان مواردی هستند که خودشان را اعلام نمی‌کنند.
  8. یک سند واقعی را در مرورگر باز کنید و نشانگر مشغول را مشاهده کنید. یک ساخت سبز در اینجا چیزی ثابت نمی‌کند: مجوزدهی، ثبت افزونه، مسیر منبع و فراخوانی‌های Viewer فقط در زمان اجرا شکست می‌خورند. برای یک مزرعه، تأیید کنید که سندی که توسط یک گره منتشر شده است، توسط گره دیگری سرو شود.

آزمون مهاجرت

در حداقل، موارد زیر را تأیید کنید:

  • راه‌اندازی برنامه با لایسنس تولید و هر افزونه ثبت‌شده؛
  • CSS/اسکریپت‌های Viewer و تمام درخواست‌های تصویر‑صفحه تحت مسیرهای انتخاب‌شده؛
  • باز کردن سند، ناوبری، زوم، تصویرهای کوچک، چاپ، و بسته شدن صریح؛
  • جستجو در سندی که متن دارد و وضعیت غیرقابل جستجو بودن فایلی که فقط تصویر دارد؛
  • بارگذاری، ذخیره، صادرات حاشیه‌نویسی و محدودیت قابلیت‌ها؛
  • کشف هدف مبدل، خروجی، دانلود و وضعیت واترمارک؛
  • صفحات، فریم‌ها و انیمیشن DICOM؛ متادیتای فنی در این بسته در دسترس نیست؛
  • اسناد محافظت‌شده با رمز عبور، فونت‌های سفارشی، متن غیرلاتین، و زمان‌سنجی‌های پیکربندی‌شده؛
  • رد توکن‌های بین‌جلسه‌ای و رفتار جلسه منقضی‌شده؛
  • برای یک فارم: انتشار بر روی یک گره، درخواست صفحه‌ای دیرهنگام از گره دیگر، و تأیید اینکه Viewer پاسخ‌های 202 را مجدداً تلاش می‌کند به‌جای نمایش کاشی‌های خراب؛
  • موبایل، حالت تاریک، و مسیر reverse-proxy تولید.

برنامه بازگشت

سابقهٔ استقرار قبلی، بسته‌های منطبق، فایل‌های لایسنس، و منابع مرورگر کپی‌شده را با هم نگه دارید. یک بازگشت ایمن تمام نسل برنامه را تغییر می‌دهد؛ این کار سرور نسل قبلی را با اسکریپت‌های فعلی یا سرور فعلی را با مکان‌های فراخوانی new Viewer(...) مخلوط نمی‌کند.

قبل از قطع، مستند کنید:

  • اسلات یا آرشیو استقرار استفاده‌شده برای بازگشت؛
  • تأثیر ذخیره‌سازی مشترک، در صورت وجود — آرشیوهای منتشرشده توسط نسخهٔ ۲۶.۸.۰ توسط میانی‌افزار وب‑فارم قبلی مصرف نمی‌شوند؛
  • نحوهٔ نامعتبر شدن جلسات سند فعال؛
  • بررسی سلامت و سند تستی (smoke) استفاده‌شده برای تصمیم‌گیری بازگشت؛
  • کسی که می‌تواند مجموعهٔ بسته‌های قبلی و پیکربندی را بازگرداند.

مستندات قدیمی

راهنمای قبلی ترجمه‌شده همچنان در دسترس است در نصب Legacy .NET Standard. درگاه ادغام قبلی سیگنال‌های شناسایی یکسان را توضیح می‌دهد و به این راهنمای مهاجرت بازمی‌گردد.

آدرس تاریخی را در نشانک‌ها و تیکت‌های پشتیبانی نگه دارید تا زمانی که نصب‌های netstandard2.0 هنوز وجود دارند. این آدرس نسل متفاوتی را مستند می‌کند و به API فعلی هدایت نمی‌شود.

آیا این صفحه مفید بود؟