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 جدید تکیه نکنید. فرمان پیش‌فرض آخرین نسخهٔ پایدار را نصب می‌کند:

bash

dotnet add package Doconut.NET6

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

bash

dotnet add package Doconut.NET6 --version 26.7.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

// Classic integration — contrast only; do not compile this against the current 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.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer یک سرویس موقت است. مدیر جلسه سند و کش آن، وضعیت طولانی‌مدت سند را در اختیار دارند، نه نمونه خاص Viewer تزریق‌شده.

میدلور و مسیردهی منابع

شاخه کلاسیک MapWhen که DocImage.axd را تشخیص می‌دهد حذف کنید:

csharp

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

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

قبل از Doconut، UseSession() را فراخوانی کنید در حالی که امنیت نشست فعال است؛
UseDoconutResources() را قبل از UseDoconut() فراخوانی کنید؛
ResourcesPath، URLهای منابع تولید شده و ResPath سمت کلاینت را هم‌راستا نگه دارید؛
هنگام نگاشت 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 });
});

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

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

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

csharp

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

csharp

viewer.CloseDocument(token);

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

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

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

نگرانی	نوع فعلی
مسیرهای میدلور، مجوزدهی، ثبت افزونه‌ها	`DoconutOptions`
رمز عبور، زمان‌سنجی، امنیت، واترمارک	`DocOptions`
رندر فرمت و DPI	`PdfConfig`, `WordConfig`, `ExcelConfig`, and other `BaseConfig` types
پیش‌فرض‌های ویجت مرورگر	`ViewerConfig` or the equivalent JavaScript options
CSS و اسکریپت‌های تولید شده	`CssConfig` and `ScriptConfig`

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

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

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

ReferenceCss را برای تولید CSS Viewer و CSS جستجو/حاشیه‌نویسی دارای مجوز استفاده کنید؛
نوار ابزار 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 کار کرد، حذف کنید.

ثبت افزونه

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

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.AddSession();
app.UseSession();

مقدار DocOptions.IsSecured = true را نگه دارید مگر اینکه طراحی بازبینی‌شده نیاز به خلاف آن داشته باشد. هرگز از UnsafeMode = true به‌عنوان یک راه‌حل کوتاه برای مهاجرت استفاده نکنید. درخواست‌ها را با توکن‌ نداشتن، توکن خراب، توکن منقضی‌شده و توکن از جلسه مرورگر متفاوت آزمایش کنید.

برنامه مرجع Distributed بلیت‌های دسترسی و جزئیات حمل‌ونقل را اضافه می‌کند. این APIها برای یک مهاجرت تک‌نودی معمولی لازم نیستند.

آزمایش مهاجرت

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

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

برنامه بازگردانی

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

قبل از انتقال، موارد زیر را مستند کنید:

اسلات یا آرتیفکت استقرار مورد استفاده برای بازگردانی؛
تأثیر بر پایگاه‌داده/کش، در صورت وجود؛
چگونگی نامعتبر شدن جلسات سند فعال؛
چک سلامت و سند smoke مورد استفاده برای تصمیم‌گیری بازگردانی؛
کسی که می‌تواند مجموعه بسته‌های قبلی و پیکربندی را بازگرداند.

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

راهنمای کلاسیک ترجمه‌شده در دسترس است در راهنمای کلاسیک .NET 6. درگاه جدید درگاه یکپارچه‌سازی کلاسیک سیگنال‌های شناسایی مشابه را توضیح می‌دهد و به این راهنمای مهاجرت پیوند می‌زند.

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