مهاجرت

این صفحه به‌روزرسانی یک برنامه ASP.NET موجود را از Doconut.NETFramework 26.8.0 یا نسخه‌های قبلی (.NET Framework 4.7) به 26.9.0 و بعدی‌ها (.NET Framework 4.7.2) را پوشش می‌دهد. بسته نمونه‌های Doconut راهنمای کامل مهاجرت و نمونه‌های کلاسیک منتقل‌شده به API جدید — MVC 5، یک وب‌فارم، و Web Forms — را شامل می‌شود. مقایسه برنامه شما با نمونه‌ای که از آن شروع شده سریع‌ترین مسیر است.

یک بسته، دو نسخه

هر دو کتابخانه تحت یک شناسه بسته یکسان، Doconut.NETFramework، منتشر می‌شوند. نسخه‌ها آن‌ها را از هم متمایز می‌کند:

به‌روزرسانی بسته، همان ارتقا است. بستهٔ جداگانه‌ای برای نصب وجود ندارد و لایهٔ سازگاری‌ای نیز نیست: 26.9.0 یک سطح API متفاوت است، بنابراین پس از به‌روزرسانی انتظار خطاهای کامپایل را داشته باشید — بقیهٔ این صفحه. خط .NET Framework 4.7 منسوخ شده و 26.8.0 آخرین انتشار آن است. می‌توانید روی آن بمانید — هیچ‌یک از این‌ها اصلاح امنیتی‌ای نیست که از دست بدهید — اما نسخه‌های جدید، افزونه‌ها، حالت توزیع‌شده، و ویجت‌های آمادهٔ استفاده فقط در 26.9.0 و بعد از آن موجود هستند.

1. تغییر هدف و به‌روزرسانی بسته

ابتدا پروژه وب را به .NET Framework 4.7.2 تغییر هدف دهید: پروژه‌ای که هنوز هدف 4.7 دارد نمی‌تواند 26.9.0 را نصب کند و NuGet به‌روزرسانی را رد می‌کند. سپس Doconut.NETFramework را به‌روزرسانی کنید و بسته‌های افزونه‌ای که استفاده می‌کنید (Doconut.NETFramework.Converter، Doconut.NETFramework.Dicom، …) را اضافه کنید. هر افزونه به مجوزی نیاز دارد که به آن اجازه دهد.

اگر پروژه از packages.config استفاده کند، به‌روزرسانی مرحلهٔ حذف نصب نسخهٔ قبلی را اجرا می‌کند که هندلر DocImage را از Web.config حذف می‌سازد و 26.9.0 آن را باز نمی‌گرداند. همان‌طور که در گام ۳ نشان داده شده دوباره ثبت کنید؛ تا آن زمان، DocImage.axd پاسخ 404 می‌دهد و هیچ صفحه‌ای رندر نمی‌شود.

2. فضای‌نام‌ها: تقریباً همه چیز به ریشه منتقل شد

نام‌های نوع تغییر نکرده‌اند: WordConfig، PdfConfig، ExcelConfig، CssConfig، ScriptConfig، FileShareConfig و بقیه همچنان موجود هستند. در اکثر فایل‌ها ویرایش کامل حذف خطوط using است.

3. راه‌اندازی: DoconutHost.Initialize و دو ورودی Web.config

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

// قبل از - Doconut.NETFramework 26.8.0 و قبلی، به درخواست
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - Viewer از DoconutHost دریافت شد، مجوز یک بار در DoconutHost.Initialize() پیکربندی شد
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize در Application_Start قرار می‌گیرد و DoconutHost.Shutdown در Application_End، و Web.config هندلر DocImage.axd و ماژول منبع را به‌دست می‌آورد — هر دو در نصب هستند. تنظیمات ظاهر صفحه به‌ازای هر صفحه (FitType، FixedZoom، ShowHyperlinks، …) از نمونهٔ نمایشگر به گزینه‌های ویجت منتقل شده‌اند، یا به یک ViewerConfig که به Viewer.RenderViewer پاس داده می‌شود (به پیکربندی‌نمایشگر مراجعه کنید). new Viewer() همچنان پس از اجرای DoconutHost.Initialize کامپایل می‌شود، بنابراین کد‑پشت مهاجرت‌شده می‌تواند آن خط را نگه دارد در حالی که تنظیمات را جابه‌جا می‌کنید.

امنیت همان‌طور که قبلاً کار می‌کرد. باز کردن یک سند دسترسی صفحات آن را به نشست فعلی ASP.NET می‌دهد و DocImage.axd برای دیگران رد می‌شود. تنظیم برنامهٔ DoconutUnSafeMode که این را غیرفعال می‌کرد اکنون در DoconutHost.Initialize به صورت options.UnsafeMode است — آن را false بگذارید. به جلسات و امنیت مراجعه کنید.

خطای راه‌اندازی که کل سایت را از کار می‌اندازد. یک افزونهٔ ثبت‌شده که قابلیت آن توسط هیچ مجوزی اعطا نشده در Application_Start استثنا می‌اندازد و برنامه سپس به هر درخواست یک 500 خالی پاسخ می‌دهد — صفحهٔ خطا نیست، چیزی در لاگ IIS نیست، فقط یک ورودی در لاگ رویدادهای ویندوز (منبع ASP.NET). مجوزها از wwwroot زیر ریشهٔ سایت خوانده می‌شوند و در جای دیگری نیستند، و Doconut.Viewer.lic پایه باید موجود باشد وگرنه مجوزهای افزونه در کنار آن خوانده نمی‌شوند. به راه‌اندازی مجوز مراجعه کنید.

4. مزرعه وب: از یک پرچم به حالت توزیع‌شده

مدل کلاسیک viewer.IsWebfarm = true به‌اضافه ExportToPng(path) بود. مدل جدید یک‌بار ثبت می‌شود: هر گره یک فروشگاه و یک کلید امضا را به‌اشتراک می‌گذارد و یک بلیت امضا‌شدهٔ متصل به مرورگر، «هر گره‌ای که پاسخ می‌دهد» را جایگزین می‌کند:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath یک نام مستعار است
        d.SigningKey        = farmKey;                           // >= 32 bytes, یکسان در هر گره
    }));

سپس اسناد را به‌صورت معمول باز کنید، مرورگر را (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) متصل کنید و viewer.AccessToken را همراه با توکن به ویجت بدهید. جلسات و امنیت مراحل را دارد؛ نمونهٔ web-farm یک گرهٔ کامل است. IsWebfarm و WebfarmPath هنوز کامپایل می‌شوند، اما دیگر هیچ‌چیزی را فعال نمی‌کنند.

دو مورد که شبیه موفقیت به نظر می‌رسند اما نیستند: DistributedDocumentPublisher.PublishAsync فایل‌های رندر شدهٔ یک سند را می‌نویسد اما هیچ جلسه‌ای را باز نمی‌کند، بنابراین یک نمایشگر که به توکن منتشر شده اشاره دارد، تصویر خطای حدود ۲ کیلوبایتی با وضعیت ۲۰۰ دریافت می‌کند؛ و یک مشتری تست بدون کوکی doconut-client همان تصویر را دریافت می‌کند، نه یک 401. برای تشخیص صفحهٔ واقعی از تصویر خطا، به اندازهٔ آن توجه کنید.

5. تبدیل یک افزونه است و بسیار کوچک‌تر

enum SourceFormatConverter، دوازده کلاس *ConfigConverter، و enumهای هدف تو در تو آن‌ها با یک enum، ConversionTarget، و یک فراخوانی جایگزین می‌شوند:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// فرض کنید DoconutHost از قبل مقداردهی اولیه شده است و یک CancellationToken به نام ct در دسترس است.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* جریان ورودی شما */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

قالب منبع از پسوندی که می‌گذارید می‌آید. هیچ لایهٔ سازگاری وجود ندارد: هر ارجاع به SourceFormatConverter یک خطای کامپایل است که با حذف آن رفع می‌کنید. اشیای گزینهٔ هر‑قالب زنده نماند — WordConfigConverter.HtmlOptions و CadConfigConverter.CadOptions.ShowColor معادل‌ای در ConvertAsync ندارند. در Web Forms، هرگز روی ConvertAsync مسدود نشوید — ببینید افزونهٔ مبدل.

6. ذخیره‌سازی ابری: دسترسی به آن به‌صورت پوشهٔ مشترک

انواع پیکربندی ابری به‌صورت بدون تغییر به Doconut.Clouds منتقل شدند. با این حال، هندلرهای درخواست ابری، مؤلفه‌های ASP.NET Core هستند و یک برنامهٔ کلاسیک هیچ خط لوله‌ای برای اجرای آن‌ها ندارد. از یک سایت System.Web، به ذخیره‌سازی ابری به‌عنوان پوشهٔ مشترک دسترسی پیدا کنید — در Azure، یک اشتراک Azure Files که بر روی هر گره سوار شده است — از طریق FileShareConfig.

7. تغییرات سمت‌کلاینت که به‌صورت ساکت شکست می‌خورند

هر مورد زیر کامپایل می‌شود، اجرا می‌شود، هیچ‌چیزی لاگ نمی‌کند و کار اشتباهی انجام می‌دهد:

سه مورد دیگر: نمایشگر نوار ابزار خود را رسم نمی‌کند (صفحهٔ شما Zoom، Next، GotoPage و بقیه را به دکمه‌های خود وصل می‌کند)؛ یک نمایشگر که داخل یک مودال مخفی Bootstrap ساخته می‌شود اندازهٔ ۰×۰ دارد و هیچ‌چیزی نمی‌کشد تا زمانی که به کانتینر آن ارتفاع صریح بدهید و آن را بر روی shown.bs.modal دوباره تنظیم کنید؛ و AllowSearch به‌صورت پیش‌فرض برای PDF برابر با false است، بنابراین یک سند به‌طور کامل رندر می‌شود در حالی که هر جستجویی هیچ‌نتیجه‌ای برنمی‌گرداند.

8. چه چیزی ناپدید می‌شود

ترتیب پیشنهادی کار

1. هدف‌گیری مجدد، تعویض بسته، و دریافت Global.asax که با DoconutHost.Initialize و دو ثبت‌نام Web.config کامپایل می‌شود. سایت باید شروع شود.
2. یک صفحه نمایشگر: یک سند برای رندر گرفتن، سپس از بخش ۷ پیش بروید تا نوار ابزار، جستجو و حاشیه‌نویسی‌ها کار کنند. در مرورگر واقعی تأیید کنید — هیچ‌چیزی در آن بخش خطایی ایجاد نمی‌کند.
3. تبدیل (بخش ۵): مکانیکی، و بیشتر خطاهای کامپایل.
4. صفحات باقی‌مانده، با استفاده از نمونه‌های منتقل‌شده به عنوان هدف اختلاف.
5. مزرعه وب (بخش ۴)، اگر دارید. با دو گره و یک مرورگر، یا یک مشتری که کوکی‌ها را نگه می‌دارد، تست کنید.