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()` plus `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 را به‌صورت جداگانه با آرتیفکت‌های نسخه تأییدشده تست کنید.

راه‌اندازی و تزریق وابستگی

برنامه‌های کلاسیک 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()));

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

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

توکن بازگردانده‌شده یک نشست سند سمت سرور را شناسایی می‌کند. آن را مانند یک اعتبار 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`
رندر فرمت و DPI	`PdfConfig`، `WordConfig`، `ExcelConfig` و سایر انواع `BaseConfig`
پیش‌فرض‌های ویجت مرورگر	`ViewerConfig` یا گزینه‌های معادل JavaScript
CSS و اسکریپت‌های تولید شده	`CssConfig` و `ScriptConfig`

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

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

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

CSS Viewer و CSS جستجو/حاشیه‌نویسی دارای مجوز را با ReferenceCss صادر کنید؛
نوار ابزار Viewer متعلق به برنامه را رندر کنید؛
searchBarMount، annBarMount و سوارسازی مورد نیاز Viewer را رندر کنید؛
اسکریپت‌های Viewer و ماژول‌های دارای مجوز را با ReferenceScripts صادر کنید؛
viewerToolbar.js مخصوص برنامه را بارگذاری کنید؛
یک objViewer را مقداردهی اولیه کنید؛
نوارهای جستجو و حاشیه‌نویسی دارای مجوز را مقداردهی اولیه کنید؛
attach(objViewer) را بر روی هر نوار فراخوانی کنید؛
سند را باز کنید و objViewer.View(token) را فراخوانی کنید.

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

فایل‌های کلاسیک کپی‌شده به‌صورت دستی مانند 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(); // وضعیت جلسه به یک کش نیاز دارد (MVC/Razor Pages قبلاً یک کش اضافه می‌کند)
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 قدیمی در دسترس است. دروازه یکپارچه‌سازی کلاسیک همان سیگنال‌های شناسایی را توضیح می‌دهد و به این راهنمای مهاجرت بازمی‌گردد.

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