مهاجرت از یکپارچه‌سازی کلاسیک .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 هستند که به همان نسخه انتشار بسته اصلی قفل شده‌اند.

قبل از مهاجرت

  1. یک شاخه و یک نسخه پشتیبان قابل استقرار از برنامه موجود ایجاد کنید.
  2. نسخه‌های دقیق بسته هسته و افزونه را ثبت کنید.
  3. فهرست تمام نگاشت DocImage.axd، فراخوانی new Viewer(...)، فراخوانی بارگذاری لایسنس، اسکریپت کپی‌شده Doconut، اقدام نوار ابزار سفارشی و نقطه انتهایی باز کردن سند را تهیه کنید.
  4. فایل‌های .lic جاری و رازهای استقرار را خارج از کنترل نسخه حفظ کنید.
  5. یک مجموعه نماینده از اسناد PDF، Office، تصویر، CAD، ایمیل، DICOM، قابل جستجو، دارای رمز عبور و حاشیه‌نویسی شده را ضبط کنید.
  6. زمان‌سنجی جلسه موجود، رفتار امنیتی، فونت‌ها و تنظیمات پلتفرم را ثبت کنید.

قبل از تغییر به تولید، یک محیط را مهاجرت کنید. یکپارچه‌سازی فعلی زمان‌زندگی سرویس، مسیردهی درخواست، مالکیت جلسه و تحویل منابع مشتری را تغییر می‌دهد.

سازگاری بسته و لایسنس

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

bash
dotnet add package Doconut.NET6

برای یک مهاجرت قابل تکرار به نسخه‌ای که در این راهنما بررسی شده است، نسخه را به‌عنوان گزینه‌ای جداگانه عبور دهید:

bash
dotnet add package Doconut.NET6 --version 26.9.0

تمام افزونه‌های Doconut را در همان نسخه بسته هسته نگه دارید. یکپارچه‌سازی فعلی لایسنس‌ها را یک‌بار در طول AddDoconut() بارگذاری می‌کند و از این اولویت استفاده می‌کند:

text
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 می‌سازند:

csharp
// یکپارچه‌سازی کلاسیک — فقط برای مقایسه؛ این را در برابر SDK فعلی کامپایل نکنید.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

یکپارچه‌سازی فعلی Doconut را یک بار ثبت می‌کند و Viewer را از تزریق وابستگی دریافت می‌کند:

csharp
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 را تشخیص می‌دهد حذف کنید:

csharp
// یکپارچه‌سازی کلاسیک — در طول انتقال حذف شود.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

در خط لولهٔ فعلی:

  1. قبل از Doconut، هنگام فعال بودن امنیت نشست، UseSession() را فراخوانی کنید؛
  2. قبل از UseDoconut()، UseDoconutResources() را فراخوانی کنید؛
  3. اطمینان حاصل کنید که ResourcesPath، URLهای منابع تولید‌شده و ResPath سمت کلاینت هم‌راستا باشند؛
  4. هنگام نگاشت UseDoconut() به یک شاخه، آن شاخه و BasePath سمت کلاینت را هم‌راستا نگه دارید.

MiddlewarePath یک پیکربندی معتبر است؛ به تنهایی شاخهٔ ASP.NET Core ایجاد نمی‌کند. یا از خط لولهٔ ساده در نمونهٔ کامپایل‌شدهٔ بالا استفاده کنید یا یک ترتیب صریح app.Map("/doconut", branch => branch.UseDoconut()) که به‌طور مداوم توسط کلاینت استفاده می‌شود، به کار ببرید.

ساخت و طول عمر 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 });
});

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

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

OpenDocument(...) همزمان را با OpenDocumentAsync(...) جایگزین کنید:

csharp
// یکپارچه‌سازی فعلی .NET 6: Viewer از DI می‌آید و باز کردن سند به صورت ناهمزمان است.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

بارگذاری‌های فعلی یک مسیر فایل یا جریان، یک پیکربندی فرمت اختیاری، DocOptions اختیاری و یک توکن لغو را می‌پذیرند. هنگامیکه مرورگر دیگر به آن نیازی ندارد، نشست سرور را به‌صورت صریح ببندید:

csharp
viewer.CloseDocument(token);

پس از انتقال، توکن کلاسیک را مجدداً استفاده نکنید. هر سند را دوباره از طریق API فعلی باز کنید.

کلاس‌های پیکربندی

API فعلی نگرانی‌ها را جدا می‌کند:

نگرانینوع فعلی
مسیرهای میدل‌ویر، مجوزدهی، ثبت افزونهDoconutOptions
رمز عبور، زمان‌سنجی، امنیت، واترمارکDocOptions
رندر فرمت و DPIPdfConfig, WordConfig, ExcelConfig, و سایر انواع BaseConfig
پیش‌فرض‌های ویجت مرورگرViewerConfig یا گزینه‌های معادل JavaScript
CSS و اسکریپت‌های تولید‌شدهCssConfig و ScriptConfig

از DocOptions.ImageResolution به‌عنوان کنترل رندر استفاده نکنید. این مورد منسوخ شده است؛ BaseConfig.ImageResolution را در پیکربندی مخصوص فرمت تنظیم کنید. تمام پیش‌فرض‌ها را مرور کنید به‌جای این‌که فرض کنید یک پیکربندی کلاسیک همان رفتار را دارد.

نوار ابزار Viewer، جستجو و حاشیه‌نویسی

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

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

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

فایل‌های کلاسیک کپی‌شده به‌صورت دستی مانند documentLinks.js و docViewer.UI.js را فقط پس از این‌که صفحهٔ فعلی با منابع تولید‌شده توسط ReferenceCss و ReferenceScripts کار کرد، حذف کنید.

ثبت افزونه

روش‌های کلاسیک استاتیک مجوز افزونه، افزونه‌های فعلی را ثبت نمی‌کنند. هر بسته منتشر شده را به‌صورت صریح نصب و ثبت کنید:

csharp
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 را پیکربندی کند:

csharp
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 فعلی ریدایرکت نمی‌شود.

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