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 و وابستگی‌های دسترسی‑درخواست می‌سازند:

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 یک سرویس موقت (transient) است. مدیر جلسهٔ سند و کش آن، وضعیت سند طولانی‌مدت را در اختیار دارند، نه نمونهٔ خاص 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()));

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

UseSession() را قبل از Doconut فراخوانی کنید در حالی که امنیت جلسه فعال است؛
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` و سایر انواع `BaseConfig`
پیش‌فرض‌های ویجت مرورگر	`ViewerConfig` یا گزینه‌های معادل JavaScript
CSS و اسکریپت‌های تولیدشده	`CssConfig` و `ScriptConfig`

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

نوار ابزار Viewer، Search و Annotation

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

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

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

فایل‌های کلاسیک کپی‌شده مانند 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 منتشرشده هستند. Search و Annotation معمولی ویژگی‌های دارای مجوز داخلی هستند، نه بسته‌های AddPlugin<TPlugin>().

امنیت جلسه و سند

یکپارچه‌سازی فعلی اسناد را به توکن‌های مبهم و جلسات کش‌شده متصل می‌کند. با UnsafeMode = false پیش‌فرض، UseDoconut() امنیت دسترسی به سند را اضافه می‌کند و میزبان باید جلسهٔ ASP.NET را پیکربندی کند:

csharp

builder.Services.AddSession();
app.UseSession();

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

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

تست مهاجرت

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

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

برنامهٔ بازگشت (Rollback)

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

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

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

مستندات کلاسیک

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

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

کدام یکپارچه‌سازی .NET 6 را استفاده می‌کنید؟

چرا نام بسته NuGet ممکن است به شما نگوید

پیش از مهاجرت

سازگاری بسته و مجوز

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

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

ساخت Viewer و طول عمر آن

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

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

نوار ابزار Viewer، Search و Annotation

ثبت افزونه‌ها

امنیت جلسه و سند

تست مهاجرت

برنامهٔ بازگشت (Rollback)

مستندات کلاسیک

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