مهاجرت از یکپارچهسازی کلاسیک .NET 6
انتقال یک برنامه موجود Doconut.NET6 به DI فعلی و API ناهمزمان
Doconut دو یکپارچهسازی متمایز .NET 6 دارد. آنها میتوانند از همان نام بسته Doconut.NET6 استفاده کنند، بنابراین قبل از تغییر بستهها، استارتاپ، لایسنسها یا منابع مرورگر، نسل را از APIهای موجود در برنامه شناسایی کنید.
کدام یکپارچهسازی .NET 6 را استفاده میکنید؟
| اگر پروژه شامل… | نسل |
|---|---|
app.MapWhen(... "DocImage.axd" ...) | قدیمی / کلاسیک |
new Viewer(_cache, _accessor, ...) | قدیمی / کلاسیک |
Viewer.DoconutLicense(...) یا Viewer.SetLicensePlugin(...) | قدیمی / کلاسیک |
بهصورت دستی کپی شده docViewer.js، documentLinks.js یا docViewer.UI.js | قدیمی / کلاسیک |
builder.Services.AddDoconut(...) | یکپارچهسازی فعلی |
app.UseDoconutResources() بهعلاوه app.UseDoconut() | یکپارچهسازی فعلی |
Viewer توسط تزریق وابستگی فراهم شده | یکپارچهسازی فعلی |
await viewer.OpenDocumentAsync(...) | یکپارچهسازی فعلی |
اگر هر دو ستون در یک برنامه ظاهر شوند، مهاجرت را ناقص در نظر بگیرید. توکن سند را از طریق منابع یا میدلویر نسل دیگر ارسال نکنید.
چرا نام بسته NuGet ممکن است به شما نگوید
هر دو نسل تحت شناسه بسته Doconut.NET6 منتشر شدهاند. بنابراین یک مرجع بسته، فایل قفل یا .nupkg کششده به تنهایی API میزبانی را شناسایی نمیکند. نسخه دقیق بسته را ثبت کنید و Program.cs، ساخت Viewer، باز کردن سند و اسکریپتهای مرورگر را با هم بررسی کنید.
نسخه جاری که برای این راهنما بررسی شده Doconut.NET6 26.7.0 است. بستههای عمومی اختیاری آن Doconut.NET6.Converter و Doconut.NET6.Dicom هستند که به همان نسخه انتشار بسته اصلی قفل شدهاند.
قبل از مهاجرت
- یک شاخه و یک نسخه پشتیبان قابل استقرار از برنامه موجود ایجاد کنید.
- نسخههای دقیق بسته هسته و افزونه را ثبت کنید.
- فهرست تمام نگاشت
DocImage.axd، فراخوانیnew Viewer(...)، فراخوانی بارگذاری لایسنس، اسکریپت کپیشده Doconut، اقدام نوار ابزار سفارشی و نقطه انتهایی باز کردن سند را تهیه کنید. - فایلهای
.licجاری و رازهای استقرار را خارج از کنترل نسخه حفظ کنید. - یک مجموعه نماینده از اسناد PDF، Office، تصویر، CAD، ایمیل، DICOM، قابل جستجو، دارای رمز عبور و حاشیهنویسی شده را ضبط کنید.
- زمانسنجی جلسه موجود، رفتار امنیتی، فونتها و تنظیمات پلتفرم را ثبت کنید.
قبل از تغییر به تولید، یک محیط را مهاجرت کنید. یکپارچهسازی فعلی زمانزندگی سرویس، مسیردهی درخواست، مالکیت جلسه و تحویل منابع مشتری را تغییر میدهد.
سازگاری بسته و لایسنس
بسته هسته را بهصورت عمدی جایگزین یا بهروز کنید؛ به شناسه بسته یکسان برای انتخاب API جدید اعتماد نکنید. فرمان پیشفرض آخرین نسخه پایدار را نصب میکند:
dotnet add package Doconut.NET6برای یک مهاجرت قابل تکرار به نسخهای که در این راهنما بررسی شده است، نسخه را بهعنوان گزینهای جداگانه عبور دهید:
dotnet add package Doconut.NET6 --version 26.9.0تمام افزونههای Doconut را در همان نسخه بسته هسته نگه دارید. یکپارچهسازی فعلی لایسنسها را یکبار در طول AddDoconut() بارگذاری میکند و از این اولویت استفاده میکند:
LicenseStream > LicenseContent > LicensePath > automatic discoveryکشف خودکار به دنبال Doconut.Viewer.lic و فایلهای همراه Doconut.Viewer.<Capability>.lic میگردد. یک فراخوانی کلاسیک به Viewer.DoconutLicense(...) یا Viewer.SetLicensePlugin(...) مکانیزم استارتاپ فعلی نیست. لایسنس را به DoconutOptions منتقل کنید، هنگام استفاده از کشف خودکار فایلهای همراه را با هم نگه دارید، پس از تغییر لایسنس مجدداً راهاندازی کنید و قابلیتها را از طریق IDoconutLicenseService تأیید کنید.
فرض نکنید حضور لایسنس افزونه قدیمی حق استفاده از ساخت افزونه فعلی را ثابت میکند. Viewer، Search، Annotation، Converter و DICOM را بهصورت جداگانه با artefacts نسخه تأییدشده تست کنید.
راهاندازی و تزریق وابستگی
برنامههای کلاسیک Viewer را با کش ASP.NET و وابستگیهای request‑accessor میسازند:
// یکپارچهسازی کلاسیک — فقط برای مقایسه؛ این را در برابر SDK فعلی کامپایل نکنید.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);یکپارچهسازی فعلی Doconut را یک بار ثبت میکند و Viewer را از تزریق وابستگی دریافت میکند:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseSession();
app.UseDoconutResources();
app.UseDoconut();Viewer یک سرویس موقت است. مدیر نشست سند و کش آن، وضعیت سند طولانیمدت را مالک هستند، نه نمونهٔ خاص تزریقشدهٔ Viewer.
میدلویر و مسیردهی منابع
شاخهٔ کلاسیک MapWhen که DocImage.axd را تشخیص میدهد حذف کنید:
// یکپارچهسازی کلاسیک — در طول انتقال حذف شود.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
branch => branch.UseDoconut(new DoconutOptions()));در خط لولهٔ فعلی:
- قبل از Doconut، هنگام فعال بودن امنیت نشست،
UseSession()را فراخوانی کنید؛ - قبل از
UseDoconut()،UseDoconutResources()را فراخوانی کنید؛ - اطمینان حاصل کنید که
ResourcesPath، URLهای منابع تولیدشده وResPathسمت کلاینت همراستا باشند؛ - هنگام نگاشت
UseDoconut()به یک شاخه، آن شاخه وBasePathسمت کلاینت را همراستا نگه دارید.
MiddlewarePath یک پیکربندی معتبر است؛ به تنهایی شاخهٔ ASP.NET Core ایجاد نمیکند. یا از خط لولهٔ ساده در نمونهٔ کامپایلشدهٔ بالا استفاده کنید یا یک ترتیب صریح app.Map("/doconut", branch => branch.UseDoconut()) که بهطور مداوم توسط کلاینت استفاده میشود، به کار ببرید.
ساخت و طول عمر 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 });
});توکن بازگرداندهشده یک نشست سند سمت سرور را شناسایی میکند. آن را بهعنوان اعتبار Bearer در نظر بگیرید: آن را لاگ نکنید، ذخیره نکنید و در تجزیه و تحلیلها قرار ندهید.
باز کردن و بستن اسناد
OpenDocument(...) همزمان را با OpenDocumentAsync(...) جایگزین کنید:
// یکپارچهسازی فعلی .NET 6: Viewer از DI میآید و باز کردن سند به صورت ناهمزمان است.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });بارگذاریهای فعلی یک مسیر فایل یا جریان، یک پیکربندی فرمت اختیاری، DocOptions اختیاری و یک توکن لغو را میپذیرند. هنگامیکه مرورگر دیگر به آن نیازی ندارد، نشست سرور را بهصورت صریح ببندید:
viewer.CloseDocument(token);پس از انتقال، توکن کلاسیک را مجدداً استفاده نکنید. هر سند را دوباره از طریق API فعلی باز کنید.
کلاسهای پیکربندی
API فعلی نگرانیها را جدا میکند:
| نگرانی | نوع فعلی |
|---|---|
| مسیرهای میدلویر، مجوزدهی، ثبت افزونه | DoconutOptions |
| رمز عبور، زمانسنجی، امنیت، واترمارک | DocOptions |
| رندر فرمت و DPI | PdfConfig, WordConfig, ExcelConfig, و سایر انواع BaseConfig |
| پیشفرضهای ویجت مرورگر | ViewerConfig یا گزینههای معادل JavaScript |
| CSS و اسکریپتهای تولیدشده | CssConfig و ScriptConfig |
از DocOptions.ImageResolution بهعنوان کنترل رندر استفاده نکنید. این مورد منسوخ شده است؛ BaseConfig.ImageResolution را در پیکربندی مخصوص فرمت تنظیم کنید. تمام پیشفرضها را مرور کنید بهجای اینکه فرض کنید یک پیکربندی کلاسیک همان رفتار را دارد.
نوار ابزار Viewer، جستجو و حاشیهنویسی
اسکریپتهای قدیمی را یکییکی مهاجرت نکنید. برنامههای مرجع فعلی یک بستهٔ کامل صفحه را ترکیب میکنند:
- CSS Viewer و CSS جستجو/حاشیهنویسی دارای مجوز را با
ReferenceCssتولید کنید؛ - نوار ابزار Viewer متعلق به برنامه را رندر کنید؛
searchBarMount،annBarMountو mount مورد نیاز Viewer را رندر کنید؛- اسکریپتهای Viewer و ماژولهای دارای مجوز را با
ReferenceScriptsتولید کنید؛ viewerToolbar.jsخود برنامه را بارگذاری کنید؛- یک
objViewerرا مقداردهی اولیه کنید؛ - Ribbonهای جستجو و حاشیهنویسی دارای مجوز را مقداردهی اولیه کنید؛
- در هر Ribbon،
attach(objViewer)را فراخوانی کنید؛ - سند را باز کنید و
objViewer.View(token)را فراخوانی کنید.
جستجو و حاشیهنویسی ماژولهایی هستند که به همان Viewer متصل میشوند، نه نوارهای ابزار مستقل. نوار ابزار اصلی متعلق به برنامهٔ میزبان است؛ Ribbonهای جستجو و حاشیهنویسی بهصورت توکار و بر پایه قابلیتها گیتدار هستند.
فایلهای کلاسیک کپیشده بهصورت دستی مانند documentLinks.js و docViewer.UI.js را فقط پس از اینکه صفحهٔ فعلی با منابع تولیدشده توسط ReferenceCss و ReferenceScripts کار کرد، حذف کنید.
ثبت افزونه
روشهای کلاسیک استاتیک مجوز افزونه، افزونههای فعلی را ثبت نمیکنند. هر بسته منتشر شده را بهصورت صریح نصب و ثبت کنید:
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});AddDoconut() قابلیتهای افزونههای ثبتشده را در زمان راهاندازی اعتبارسنجی میکند. Converter و DICOM افزونههای .NET 6 منتشر شده هستند. جستجوی معمولی و حاشیهنویسی ویژگیهای دارای مجوز داخلی هستند و بستههای AddPlugin<TPlugin>() نیستند.
امنیت جلسه و سند
ادغام فعلی اسناد را به توکنهای نامشخص و جلسات کششده متصل میکند. با UnsafeMode = false پیشفرض، UseDoconut() امنیت دسترسی به سند را اضافه میکند و میزبان باید جلسه ASP.NET را پیکربندی کند:
builder.Services.AddDistributedMemoryCache(); // session state نیاز به یک cache دارد (MVC/Razor Pages قبلاً یک مورد اضافه میکند)
builder.Services.AddSession();
app.UseSession();تا زمانی که طراحی بازبینیشده نیازی به خلاف آن نداشته باشد، DocOptions.IsSecured = true را نگه دارید. هرگز از UnsafeMode = true بهعنوان یک راهحل کوتاه برای مهاجرت استفاده نکنید. درخواستها را با عدم وجود توکن، توکن خراب، توکن منقضیشده و توکنی از جلسه مرورگر متفاوت تست کنید.
برنامه مرجع توزیعشده بلیتهای دسترسی و جزئیات انتقال را اضافه میکند. این APIها برای یک مهاجرت تکنودی عادی لازم نیستند.
آزمایش مهاجرت
حداقل، موارد زیر را تأیید کنید:
- راهاندازی برنامه با مجوز تولید و تمام افزونههای ثبتشده؛
- CSS/اسکریپتهای Viewer و تمام درخواستهای تصویر‑صفحه در مسیرهای انتخابشده؛
- باز کردن سند، ناوبری، زوم، تصویرهای بندانگشتی، چاپ و بستن صریح؛
- جستجو در سند حاوی متن و وضعیت غیرقابل جستجو بودن فایلی که فقط تصویر دارد؛
- بارگذاری، ذخیره، صادرات حاشیهنویسی و کنترل قابلیتها؛
- کشف هدف Converter، خروجی، دانلود و وضعیت واترمارک؛
- صفحات، فریمها و انیمیشن DICOM؛ متادیتای فنی .NET 6 در دسترس نیست؛
- سندهای محافظتشده با رمز عبور، قلمهای سفارشی، متن غیرلاتین و زمانسنجیهای پیکربندیشده؛
- رد توکنهای بینجلسهای و رفتار جلسه منقضیشده؛
- حالت موبایل، حالت تاریک و مسیر reverse‑proxy تولید.
برنامه بازگردانی
آرتیفکت استقرار کلاسیک، بستههای منطبق، فایلهای مجوز و منابع مرورگر کپیشده را با هم نگه دارید. یک بازگردانی ایمن نسل کامل برنامه را تغییر میدهد؛ ترکیب سرور کلاسیک با اسکریپتهای فعلی یا سرور فعلی با تماسهای کلاسیک DocImage.axd انجام نمیشود.
قبل از انتقال، موارد زیر را مستند کنید:
- اسلات یا آرتیفکت استقرار مورد استفاده برای بازگردانی؛
- تأثیر بر پایگاهداده/کش، در صورت وجود؛
- نحوه نامعتبر شدن جلسات سند فعال؛
- بررسی سلامت و سند smoke مورد استفاده برای تصمیمگیری بازگردانی؛
- چه کسی میتواند مجموعه بستههای قبلی و پیکربندی را بازگرداند.
مستندات قدیمی
دفترچه راهنمای کلاسیک ترجمهشده در دسترس است در نصب .NET 6 قدیمی. درگاه یکپارچهسازی کلاسیک جدید همان سیگنالهای شناسایی را توضیح میدهد و به این راهنمای مهاجرت لینک میدهد.
URL تاریخی را در نشانکها و تیکتهای پشتیبانی نگه دارید تا زمانی که نصبهای کلاسیک هنوز وجود دارند. این URL یک نسل متفاوت را مستند میکند و به API فعلی ریدایرکت نمیشود.
آیا این صفحه مفید بود؟