مهاجرت به .NET Standard 2.1
انتقال یک برنامهٔ موجود Doconut.NETStandard از نسخهٔ ۲۶.۷.۰ به ۲۶.۸.۰
Doconut دو ادغام متمایز .NET Standard دارد. آنها از همان نام بستهٔ Doconut.NETStandard استفاده میکنند، بنابراین نسل را از نسخه و APIهای موجود در برنامه شناسایی کنید قبل از اینکه بستهها، راهاندازی، مجوزها یا منابع مرورگر را تغییر دهید.
نسخه نقطهٔ انشعاب است
هر دو نسل تحت یک شناسهٔ بستهٔ یکسان منتشر میشوند. فقط نسخه آنها را از هم متمایز میکند:
| نسخه | هدف | API |
|---|---|---|
| 26.7.0 و پایینتر | netstandard2.0 | API قبلی |
| 26.8.0 و بالاتر | netstandard2.1 | API فعلی |
افزایش شماره نسخه، ارتقا است. پس از ارتقا خطاهای کامپایل را انتظار داشته باشید؛ بقیهٔ این راهنما فهرست آنهاست.
کدام ادغام را استفاده میکنید؟
| اگر پروژه شامل… | نسل |
|---|---|
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 دارند.
قبل از مهاجرت
- یک شاخه و یک نسخهٔ پشتیبان قابل استقرار از برنامهٔ موجود ایجاد کنید.
- نسخههای دقیق بستهٔ هسته و افزونه را ثبت کنید.
- فهرست تمام فراخوانیهای
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. سازگاری بسته و مجوز
بستهٔ هستهای را بهصورت عمدی جایگزین یا بهروزرسانی کنید؛ به شناسهٔ بستهٔ یکسان برای انتخاب API جدید تکیه نکنید. فرمان پیشفرض آخرین نسخهٔ پایدار را نصب میکند:
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 را بهصورت جداگانه با artefacts نسخهٔ تأییدشده تست کنید.
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()جایگزین 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 خودش نیازی به تغییر ندارد — فقط میدلور داخل آن:
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 را حذف کنید. هیچ چیزی در یک Viewer باقی نمیماند که ارزش نگهداری داشته باشد: این شیء هیچ وضعیت سندی را حمل نمیکند و کش جلسه همه چیز را که پس از یک درخواست باقی میماند، مالکیت میکند. آن را به یک نقطه انتهایی، صفحه Razor، کنترلر یا سرویس برنامه scoped تزریق کنید:
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(...) جایگزین کنید:
// ادغام فعلی: 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 برمیگرداند.
پیکربندی را در یک helper بسازید و از هر دو سمت فراخوانی کنید.
PageWaitTimeSeconds = 180 به معنای «مسدود کردن تا سه دقیقه به امید ظاهر شدن صفحه» بود. جایگزین بهصورت صریح است: با FirstPagePriority = true، صفحهٔ ۱ بلافاصله قابل سرویس است و صفحات بعدی تا زمان نوشتن HTTP 202 Accepted پاسخ میدهند. Viewer بستهشده بهطور خودکار وقتی 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، …)، هر کدام با یک enum تو در توEnTargetFormat— حذف شد. اکنون یک enumConversionTargetبرای هر خانواده وجود دارد. 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 را بهدست میآورد.
API فعلی همچنین نگرانیها را نسبت به نسخه قبلی بهصورت دقیقتری جدا میکند، بنابراین بررسی کنید که هر تنظیمات بر روی شیئی باشد که اکنون مالک آن است:
| نگرانی | نوع فعلی |
|---|---|
| مسیرهای میدلویر، لایسنس، ثبت افزونه | DoconutOptions |
| رمز عبور، زمانانتظار، امنیت، واترمارک | DocOptions |
| رندر فرمت و DPI | PdfConfig، WordConfig، ExcelConfig، و سایر انواع BaseConfig |
| پیشفرضهای ویجت مرورگر | ViewerConfig یا گزینههای معادل جاوااسکریپت |
| 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. نوار ابزار Viewer، جستجو و حاشیهنویسی
اسکریپتهای قدیمی را یکییکی مهاجرت نکنید. برنامههای مرجع فعلی یک بسته صفحه کامل را ترکیب میکنند:
- CSS Viewer و CSS جستجو/حاشیهنویسی دارای مجوز را با
ReferenceCssصادر کنید؛ - نوار ابزار Viewer متعلق به برنامه را رندر کنید؛
searchBarMount،annBarMountو سوارسازی مورد نیاز Viewer را رندر کنید؛- اسکریپتهای Viewer و ماژولهای دارای مجوز را با
ReferenceScriptsصادر کنید؛ - اسکریپت کمکی نوار ابزار خود برنامه را بارگذاری کنید؛
- یک
objViewerرا مقداردهی اولیه کنید؛ - نوارهای جستجو و حاشیهنویسی دارای مجوز را مقداردهی اولیه کنید؛
- برای هر نوار،
attach(objViewer)را فراخوانی کنید؛ - سند را باز کنید و
objViewer.View(token)را فراخوانی کنید.
جستجو و حاشیهنویسی ماژولهایی هستند که به همان Viewer متصل میشوند، نه نوارهای ابزار مستقل. نوار ابزار اصلی متعلق به برنامه میزبان است؛ نوارهای جستجو و حاشیهنویسی بهصورت جاسازی شده و با قابلیتهای محدود شده در دسترس هستند.
فایلهای کپی شده بهصورت دستی مانند 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را به صورت async کنید وInitCache()را حذف کنید (§5، §6).- اگر از مزرعه وب استفاده میکنید، §7 را انجام دهید — تنها بخشی که بازطراحی است نه تغییر نام.
- اگر اسناد را تبدیل میکنید، §8 را انجام دهید.
- §11 را انجام دهید — تغییرات سمت کلاینت. اینها همان مواردی هستند که خودشان را اعلام نمیکنند.
- یک سند واقعی را در مرورگر باز کنید و نشانگر مشغول را مشاهده کنید. یک ساخت سبز در اینجا چیزی ثابت نمیکند: مجوزدهی، ثبت افزونه، مسیر منبع و فراخوانیهای Viewer فقط در زمان اجرا شکست میخورند. برای یک مزرعه، تأیید کنید که سندی که توسط یک گره منتشر شده است، توسط گره دیگری سرو شود.
آزمون مهاجرت
در حداقل، موارد زیر را تأیید کنید:
- راهاندازی برنامه با لایسنس تولید و هر افزونه ثبتشده؛
- CSS/اسکریپتهای Viewer و تمام درخواستهای تصویر‑صفحه تحت مسیرهای انتخابشده؛
- باز کردن سند، ناوبری، زوم، تصویرهای کوچک، چاپ، و بسته شدن صریح؛
- جستجو در سندی که متن دارد و وضعیت غیرقابل جستجو بودن فایلی که فقط تصویر دارد؛
- بارگذاری، ذخیره، صادرات حاشیهنویسی و محدودیت قابلیتها؛
- کشف هدف مبدل، خروجی، دانلود و وضعیت واترمارک؛
- صفحات، فریمها و انیمیشن DICOM؛ متادیتای فنی در این بسته در دسترس نیست؛
- اسناد محافظتشده با رمز عبور، فونتهای سفارشی، متن غیرلاتین، و زمانسنجیهای پیکربندیشده؛
- رد توکنهای بینجلسهای و رفتار جلسه منقضیشده؛
- برای یک فارم: انتشار بر روی یک گره، درخواست صفحهای دیرهنگام از گره دیگر، و تأیید اینکه Viewer پاسخهای
202را مجدداً تلاش میکند بهجای نمایش کاشیهای خراب؛ - موبایل، حالت تاریک، و مسیر reverse-proxy تولید.
برنامه بازگشت
سابقهٔ استقرار قبلی، بستههای منطبق، فایلهای لایسنس، و منابع مرورگر کپیشده را با هم نگه دارید. یک بازگشت ایمن تمام نسل برنامه را تغییر میدهد؛ این کار سرور نسل قبلی را با اسکریپتهای فعلی یا سرور فعلی را با مکانهای فراخوانی new Viewer(...) مخلوط نمیکند.
قبل از قطع، مستند کنید:
- اسلات یا آرشیو استقرار استفادهشده برای بازگشت؛
- تأثیر ذخیرهسازی مشترک، در صورت وجود — آرشیوهای منتشرشده توسط نسخهٔ ۲۶.۸.۰ توسط میانیافزار وب‑فارم قبلی مصرف نمیشوند؛
- نحوهٔ نامعتبر شدن جلسات سند فعال؛
- بررسی سلامت و سند تستی (smoke) استفادهشده برای تصمیمگیری بازگشت؛
- کسی که میتواند مجموعهٔ بستههای قبلی و پیکربندی را بازگرداند.
مستندات قدیمی
راهنمای قبلی ترجمهشده همچنان در دسترس است در نصب Legacy .NET Standard. درگاه ادغام قبلی سیگنالهای شناسایی یکسان را توضیح میدهد و به این راهنمای مهاجرت بازمیگردد.
آدرس تاریخی را در نشانکها و تیکتهای پشتیبانی نگه دارید تا زمانی که نصبهای netstandard2.0 هنوز وجود دارند. این آدرس نسل متفاوتی را مستند میکند و به API فعلی هدایت نمیشود.
آیا این صفحه مفید بود؟