نصب

افزودن Doconut به پروژه .NET Standard 2.1 خود

کتابخانه پایه Doconut برای .NET Standard به‌صورت یک پکیج NuGet عرضه می‌شود که به هر برنامه ASP.NET Core متصل می‌شود. افزونه‌های اختیاری از پکیج‌های جداگانه استفاده می‌کنند. این صفحه پکیج پایه را نصب می‌کند، اطمینان می‌دهد که میزبان شما می‌تواند آن را مصرف کند، و میدلور را ثبت می‌کند — حداقل مورد نیاز قبل از اولین رندر شما.

ابتدا چارچوب میزبان را بررسی کنید

کتابخانه هدف netstandard2.1 است. این قرارداد نسبت به نسخه قبلی netstandard2.0 محدودتر است و اولین موردی است که باید تأیید شود:

میزبانپشتیبانی شده
.NET Core 3.0 یا بالاتر، شامل .NET 5/6/7/8بله
.NET Framework (هر نسخه)خیر — netstandard2.1 نمی‌تواند توسط .NET Framework مصرف شود

پکیج فقط بر روی Windows اجرا می‌شود. برای میزبان لینوکس، از Doconut.NET8 یا Doconut.NET6 استفاده کنید.

اگر برنامه بر روی .NET Framework اجرا شود، این پکیج مناسب نیست. به جای آن از Doconut.NETFramework استفاده کنید؛ از نسخه ۲۶.۹.۰ به بعد نیاز به .NET Framework ۴.۷.۲ دارد.

نصب پکیج

bash
dotnet add package Doconut.NETStandard

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

bash
dotnet add package Doconut.NETStandard --version 26.10.0

Doconut.NETStandard شناسه پکیج است. پسوند نسخه به نام فایل دانلود شده Doconut.NETStandard.<version>.nupkg تعلق دارد و بخشی از شناسه نیست.

شماره نسخه نسل است

این موضوع در اینجا مهم‌تر از نام پکیج است. هر دو نسل کتابخانه .NET Standard تحت همان شناسه پکیج منتشر می‌شوند و فقط نسخه آن‌ها را از هم متمایز می‌کند:

نسخههدفAPI
26.7.0 و پایین‌ترnetstandard2.0ادغام قبلی
26.8.0 و بالاترnetstandard2.1ادغام مستند شده در اینجا

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

از نام پکیج به تنهایی برای انتخاب مستندات استفاده نکنید:

  • new Viewer(_cache, _accessor, …)، UnSafeMode، همگام OpenDocument(...)، viewer.InitCache()، UseDoconutWebFarm، و اسکریپت‌های نمایشگر کپی شده دستی، ادغام ادغام قبلی را شناسایی می‌کنند؛
  • AddDoconut()، UseDoconutResources()، یک Viewer تزریق شده، و OpenDocumentAsync(...) ادغام جاری مستند شده در اینجا را شناسایی می‌کنند.

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

ثبت Doconut

AddDoconut() تنها نقطه ورودی ثبت است — یک overload واحد وجود دارد و سرویس Viewer، سرویس لایسنس، و زیرساخت رندرینگ را به کانتینر DI متصل می‌کند.

دو فراخوانی میدلور تنظیمات را تکمیل می‌کنند و ترتیب آن‌ها مهم است: UseDoconutResources() باید قبل از UseDoconut() اجرا شود. UseDoconut() میدلور انتهایی است، بنابراین فراخوانی آن ابتدا به این معنی است که هر درخواست به یک منبع /doconut-res هرگز به هندلر منابع نمی‌رسد و ۴۰۴ می‌شود. UseDoconut() به هر درخواست که به آن برسد پاسخ می‌دهد، بنابراین آن را با app.Map در شاخهٔ جداگانه‌ای سوار کنید. اتصال سشن نیز لازم است — امنیت سند پیش‌فرض Doconut هر درخواست صفحه را نسبت به وضعیت سشن ASP.NET اعتبارسنجی می‌کند.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state نیاز به یک کش دارد (MVC/Razor Pages قبلاً یکی اضافه می‌کند)
builder.Services.AddSession(); // امنیت سند Doconut بر پایه session state ASP.NET است

app.UseSession();          // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut());

فضاهای نام

انواع پیکربندی دیگر در چهار فضای نام پخش نشده‌اند. در این نسخه تقریباً همه چیز در فضای نام ریشه‌ای Doconut قرار دارد:

csharp
using Doconut;                       // Viewer، DoconutOptions، DocOptions، تمام پیکربندی‌های فرمت
using Doconut.Middleware;            // AddDoconut، UseDoconut، UseDoconutResources
using Doconut.Clouds;                // پیکربندی‌های ابر و اشتراک‌گذاری فایل
using Doconut.Configs.Conversion;    // ConversionTarget

نام‌های نوع خودشان تغییر نکرده‌اند — PdfConfig، WordConfig، ExcelConfig، CssConfig، ScriptConfig و بقیه همچنان وجود دارند. اگر برنامهٔ موجودی را منتقل می‌کنید، بیشتر فایل‌ها فقط به دو خط حذف شدهٔ using نیاز دارند؛ راهنمای مهاجرت را ببینید.

تمام گزینه‌ها

DoconutOptions ویژگی‌های قابل تنظیم زیر را می‌پذیرد. هر یک اختیاری است — مقادیر پیش‌فرض زیر زمانی اعمال می‌شوند که یک ویژگی تنظیم نشده بماند.

ویژگیپیش‌فرضتوضیح
ShowDoconutInfofalseوقتی true، درخواست بدون token بنر نسخه را به‌جای ۴۰۴ برمی‌گرداند. برای بررسی سریع مفید است؛ در محیط تولید غیرفعال کنید.
UnsafeModefalseوقتی true، بررسی امنیت سشن ASP.NET در درخواست‌های صفحه را نادیده می‌گیرد. در محیط تولید غیرفعال کنید. به املا توجه کنید — کتابخانهٔ قبلی این را UnSafeMode می‌نامید.
MiddlewarePath"/doconut"مقدار هماهنگی برای نقطهٔ پایان صفحه‑تصویر. اعتبارسنجی می‌شود، اما به‌تنهایی شاخه‌ای ایجاد نمی‌کند؛ آن را با نگاشت واقعی UseDoconut() و کلاینت BasePath هم‌راستا نگه دارید.
ResourcesPath"/doconut-res"منبعی که منابع جاسازی‌شده JS/CSS/تصویر از آن سرو می‌شوند.
LicensePath"" (رشتهٔ خالی)مسیر فایل لایسنس. خالی بودن به معنای عبور به منبع بعدی، سپس جستجوی خودکار است.
LicenseContent"" (رشتهٔ خالی)محتوای خام لایسنس — از یک متغیر محیطی، مدیر رازها یا پایگاه داده.
LicenseStreamnullلایسنس به‌صورت جریان، یک‌بار در استارتاپ خوانده می‌شود.
ResetLicensefalseپرچم سازگاری رزرو شده. لایسنس در زمان AddDoconut() خوانده می‌شود؛ پس از تعویض لایسنس برنامه را مجدداً راه‌اندازی کنید.
MaxConcurrentEditorSessions200حداکثر تعداد جلسات ویرایشگر زنده (سندهای باز شده با DocOptions.EditMode). بالاتر از آن، کم‌ترین استفاده‌شدهٔ جلسهٔ بیکار بسته می‌شود. جلسات نمایشگر معمولی حساب نمی‌شوند. 0 یا مقدار منفی به معنای عدم محدودیت است.
EditorSnapshotEveryOps50با فعال‌سازی پایداری ویرایشگر (AddDoconutEditorPersistence)، هر N تغییر ثبت‌شده، سند زنده را اسنپ‌شات می‌کند. 0 یا مقدار منفی هرگز در میانهٔ جلسه اسنپ‌شات نمی‌گیرد. وقتی پایداری غیرفعال باشد، هیچ اثری ندارد.

اولویت لایسنس وقتی بیش از یک منبع تنظیم شده باشد: LicenseStream بر LicenseContent ارجحیت دارد، سپس LicensePath و در نهایت جستجوی خودکار — ببینید راه‌اندازی لایسنس.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // با نقشه‌برداری برنامه و BasePath کلاینت هماهنگ کنید
    options.ResourcesPath   = "/doconut-res"; // جایی که JS/CSS/تصاویر viewer سرو می‌شوند
    options.UnsafeMode      = false;          // امنیت session را فعال نگه دارید
    options.ShowDoconutInfo = false;
});

گام‌های بعدی

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